feat: initialized meter

Author: poshinchen

src/strands/agent/agent.py

@@ -25,6 +25,7 @@
 from ..handlers.callback_handler import CompositeCallbackHandler, PrintingCallbackHandler, null_callback_handler
 from ..handlers.tool_handler import AgentToolHandler
 from ..models.bedrock import BedrockModel
+from ..telemetry import MetricsClient
 from ..telemetry.metrics import EventLoopMetrics
 from ..telemetry.tracer import get_tracer
 from ..tools.registry import ToolRegistry
@@ -308,7 +309,7 @@ def __init__(
         # Initialize tracer instance (no-op if not configured)
         self.tracer = get_tracer()
         self.trace_span: Optional[trace.Span] = None
-
+        self.metrics_client = MetricsClient()
         self.tool_caller = Agent.ToolCaller(self)
 
     @property
@@ -372,6 +373,7 @@ def __call__(self, prompt: str, **kwargs: Any) -> AgentResult:
                 - metrics: Performance metrics from the event loop
                 - state: The final state of the event loop
         """
+        self.metrics_client.strands_agent_invocation_count.add(1)
         self._start_agent_trace_span(prompt)
 
         try:

src/strands/telemetry/__init__.py

@@ -3,7 +3,8 @@
 This module provides metrics and tracing functionality.
 """
 
-from .metrics import EventLoopMetrics, Trace, metrics_to_string
+from .metrics import EventLoopMetrics, MetricsClient, Trace, metrics_to_string
+from .strands_config import get_otel_resource
 from .tracer import Tracer, get_tracer
 
 __all__ = [
@@ -12,4 +13,6 @@
     "metrics_to_string",
     "Tracer",
     "get_tracer",
+    "MetricsClient",
+    "get_otel_resource",
 ]

src/strands/telemetry/metrics.py

@@ -1,11 +1,16 @@
 """Utilities for collecting and reporting performance metrics in the SDK."""
 
 import logging
+import threading
 import time
 import uuid
 from dataclasses import dataclass, field
 from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
 
+import opentelemetry.metrics as metrics_api
+from opentelemetry.metrics import Counter, Meter
+
+from ..telemetry import metrics_constants as constants
 from ..types.content import Message
 from ..types.streaming import Metrics, Usage
 from ..types.tools import ToolUse
@@ -355,3 +360,53 @@ def metrics_to_string(event_loop_metrics: EventLoopMetrics, allowed_names: Optio
         A formatted string representation of the metrics.
     """
     return "\n".join(_metrics_summary_to_lines(event_loop_metrics, allowed_names or set()))
+
+
+class MetricsClient:
+    """Singleton client for managing OpenTelemetry metrics instruments.
+
+    The actual metrics export destination (console, OTLP endpoint, etc.) is configured
+    through OpenTelemetry SDK configuration by users, not by this client.
+    """
+
+    _instance = None
+    _lock = threading.Lock()
+
+    meter: Meter
+    strands_agent_invocation_count: Counter
+
+    def __init__(self) -> None:
+        """Initialize a MetricsClient instance.
+
+        Note: Initialization logic is intentionally placed in __new__ rather than __init__
+        to ensure it only runs once when the singleton instance is created, not every
+        time the class is instantiated.
+        """
+        pass
+
+    def __new__(cls) -> "MetricsClient":
+        """Create and initialize a new MetricsClient instance if none exists.
+
+        Implements the singleton pattern by ensuring only one instance exists.
+        The initialization logic (meter setup and instrument creation) is performed
+        here rather than in __init__ to avoid reinitializing the singleton instance
+        on subsequent instantiations.
+
+        Returns:
+            MetricsClient: The singleton instance of the MetricsClient class.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    logger.info("Creating Strands MetricsClient")
+                    cls._instance = super(MetricsClient, cls).__new__(cls)
+                    meter_provider: metrics_api.MeterProvider = metrics_api.get_meter_provider()
+                    cls._instance.meter = meter_provider.get_meter("strands-agents")
+                    cls._instance.create_instruments()
+        return cls._instance
+
+    def create_instruments(self) -> None:
+        """Create and initialize all OpenTelemetry metric instruments."""
+        self.strands_agent_invocation_count = self.meter.create_counter(
+            name=constants.STRANDS_AGENT_INVOCATION_COUNT, unit="Count"
+        )

src/strands/telemetry/metrics_constants.py

@@ -0,0 +1,3 @@
+"""Metrics that are emitted in Strands-Agent."""
+
+STRANDS_AGENT_INVOCATION_COUNT = "strands.agent.invocation_count"

src/strands/telemetry/strands_config.py

@@ -0,0 +1,45 @@
+"""OpenTelemetry configuration and setup utilities for Strands agents.
+
+This module provides centralized configuration and initialization functionality
+for OpenTelemetry components and other telemetry infrastructure shared across Strands applications.
+"""
+
+from importlib.metadata import version
+from typing import Dict
+
+from opentelemetry.sdk.resources import Resource
+
+# Singleton cache for resources
+_resource_cache: Dict[str, Resource] = {}
+
+
+def get_otel_resource(service_name: str = "strands-agents") -> Resource:
+    """Create a standard OpenTelemetry resource with service information.
+
+    This function implements a singleton pattern - it will return the same
+    Resource object for the same service_name parameter.
+
+    Args:
+        service_name: Name of the service for OpenTelemetry.
+
+    Returns:
+        Resource object with standard service information.
+    """
+    # Check if we already have a resource for this service name
+    if service_name in _resource_cache:
+        return _resource_cache[service_name]
+
+    # Create a new resource
+    resource = Resource.create(
+        {
+            "service.name": service_name,
+            "service.version": version("strands-agents"),
+            "telemetry.sdk.name": "opentelemetry",
+            "telemetry.sdk.language": "python",
+        }
+    )
+
+    # Cache the resource
+    _resource_cache[service_name] = resource
+
+    return resource

src/strands/telemetry/tracer.py

@@ -8,20 +8,19 @@
 import logging
 import os
 from datetime import date, datetime, timezone
-from importlib.metadata import version
 from typing import Any, Dict, Mapping, Optional
 
 import opentelemetry.trace as trace_api
 from opentelemetry import propagate
 from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.propagators.composite import CompositePropagator
-from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter, SimpleSpanProcessor
 from opentelemetry.trace import Span, StatusCode
 from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
 
 from ..agent.agent_result import AgentResult
+from ..telemetry import get_otel_resource
 from ..types.content import Message, Messages
 from ..types.streaming import Usage
 from ..types.tools import ToolResult, ToolUse
@@ -151,7 +150,6 @@ def __init__(
         self.otlp_headers = otlp_headers or {}
         self.tracer_provider: Optional[trace_api.TracerProvider] = None
         self.tracer: Optional[trace_api.Tracer] = None
-
         propagate.set_global_textmap(
             CompositePropagator(
                 [
@@ -173,15 +171,7 @@ def _initialize_tracer(self) -> None:
             self.tracer = self.tracer_provider.get_tracer(self.service_name)
             return
 
-        # Create resource with service information
-        resource = Resource.create(
-            {
-                "service.name": self.service_name,
-                "service.version": version("strands-agents"),
-                "telemetry.sdk.name": "opentelemetry",
-                "telemetry.sdk.language": "python",
-            }
-        )
+        resource = get_otel_resource(self.service_name)
 
         # Create tracer provider
         self.tracer_provider = SDKTracerProvider(resource=resource)
@@ -216,6 +206,7 @@ def _initialize_tracer(self) -> None:
                 batch_processor = BatchSpanProcessor(otlp_exporter)
                 self.tracer_provider.add_span_processor(batch_processor)
                 logger.info("endpoint=<%s> | OTLP exporter configured with endpoint", endpoint)
+
             except Exception as e:
                 logger.exception("error=<%s> | Failed to configure OTLP exporter", e)
         elif self.otlp_endpoint and self.tracer_provider:

tests/strands/agent/test_agent.py

@@ -1010,8 +1010,14 @@ def test_agent_init_with_trace_attributes():
     assert "invalid_nested_list" not in agent.trace_attributes
 
 
+@pytest.fixture
+def mock_metrics_client():
+    with unittest.mock.patch("strands.agent.agent.MetricsClient") as mock_metrics_client:
+        yield mock_metrics_client
+
+
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-def test_agent_init_initializes_tracer(mock_get_tracer):
+def test_agent_init_initializes_tracer(mock_get_tracer, mock_metrics_client):
     """Test that the tracer is initialized when creating an Agent."""
     mock_tracer = unittest.mock.MagicMock()
     mock_get_tracer.return_value = mock_tracer
@@ -1025,7 +1031,7 @@ def test_agent_init_initializes_tracer(mock_get_tracer):
 
 
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-def test_agent_call_creates_and_ends_span_on_success(mock_get_tracer, mock_model):
+def test_agent_call_creates_and_ends_span_on_success(mock_get_tracer, mock_metrics_client, mock_model):
     """Test that __call__ creates and ends a span when the call succeeds."""
     # Setup mock tracer and span
     mock_tracer = unittest.mock.MagicMock()
@@ -1060,7 +1066,9 @@ def test_agent_call_creates_and_ends_span_on_success(mock_get_tracer, mock_model
 
 @pytest.mark.asyncio
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-async def test_agent_stream_async_creates_and_ends_span_on_success(mock_get_tracer, mock_event_loop_cycle):
+async def test_agent_stream_async_creates_and_ends_span_on_success(
+    mock_get_tracer, mock_metrics_client, mock_event_loop_cycle
+):
     """Test that stream_async creates and ends a span when the call succeeds."""
     # Setup mock tracer and span
     mock_tracer = unittest.mock.MagicMock()
@@ -1105,7 +1113,7 @@ def call_callback_handler(*args, **kwargs):
 
 
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-def test_agent_call_creates_and_ends_span_on_exception(mock_get_tracer, mock_model):
+def test_agent_call_creates_and_ends_span_on_exception(mock_get_tracer, mock_metrics_client, mock_model):
     """Test that __call__ creates and ends a span when an exception occurs."""
     # Setup mock tracer and span
     mock_tracer = unittest.mock.MagicMock()
@@ -1139,7 +1147,7 @@ def test_agent_call_creates_and_ends_span_on_exception(mock_get_tracer, mock_mod
 
 @pytest.mark.asyncio
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-async def test_agent_stream_async_creates_and_ends_span_on_exception(mock_get_tracer, mock_model):
+async def test_agent_stream_async_creates_and_ends_span_on_exception(mock_get_tracer, mock_metrics_client, mock_model):
     """Test that stream_async creates and ends a span when the call succeeds."""
     # Setup mock tracer and span
     mock_tracer = unittest.mock.MagicMock()
@@ -1174,7 +1182,7 @@ async def test_agent_stream_async_creates_and_ends_span_on_exception(mock_get_tr
 
 
 @unittest.mock.patch("strands.agent.agent.get_tracer")
-def test_event_loop_cycle_includes_parent_span(mock_get_tracer, mock_event_loop_cycle, mock_model):
+def test_event_loop_cycle_includes_parent_span(mock_get_tracer, mock_metrics_client, mock_event_loop_cycle, mock_model):
     """Test that event_loop_cycle is called with the parent span."""
     # Setup mock tracer and span
     mock_tracer = unittest.mock.MagicMock()

tests/strands/telemetry/test_metrics.py

@@ -1,9 +1,13 @@
 import dataclasses
 import unittest
+from unittest import mock
 
 import pytest
+from opentelemetry.metrics._internal import _ProxyMeter
+from opentelemetry.sdk.metrics import MeterProvider
 
 import strands
+from strands.telemetry.metrics import MetricsClient
 from strands.types.streaming import Metrics, Usage
 
 
@@ -13,6 +17,14 @@ def moto_autouse(moto_env, moto_mock_aws):
     _ = moto_mock_aws
 
 
+@pytest.fixture(autouse=True)
+def reset_metrics_client_singleton():
+    """Reset MetricsClient singleton between tests."""
+    yield
+    # Reset the singleton after each test
+    MetricsClient._instance = None
+
+
 @pytest.fixture
 def trace(request):
     params = {
@@ -117,6 +129,38 @@ def test_trace_end(mock_time, end_time, trace):
     assert tru_end_time == exp_end_time
 
 
+@pytest.fixture
+def mock_get_meter_provider():
+    with mock.patch("strands.telemetry.metrics.metrics_api.get_meter_provider") as mock_get_meter_provider:
+        meter_provider_mock = mock.MagicMock(spec=MeterProvider)
+        mock_get_meter_provider.return_value = meter_provider_mock
+
+        mock_meter = mock.MagicMock()
+        meter_provider_mock.get_meter.return_value = mock_meter
+
+        yield mock_get_meter_provider
+
+
+@pytest.fixture
+def mock_sdk_meter_provider():
+    with mock.patch("strands.telemetry.metrics.metrics_sdk.MeterProvider") as mock_meter_provider:
+        yield mock_meter_provider
+
+
+@pytest.fixture
+def mock_noop_meter_provider():
+    with mock.patch("opentelemetry.metrics.NoOpMeterProvider") as mock_noop_meter_provider:
+        mock_meter = mock.MagicMock()
+        mock_noop_meter_provider.get_meter.return_value = mock_meter
+        yield mock_noop_meter_provider
+
+
+@pytest.fixture
+def mock_resource():
+    with mock.patch("opentelemetry.sdk.resources.Resource") as mock_resource:
+        yield mock_resource
+
+
 def test_trace_add_child(child_trace, trace):
     trace.add_child(child_trace)
 
@@ -379,3 +423,26 @@ def test_metrics_to_string(trace, child_trace, tool_metrics, exp_str, event_loop
     tru_str = strands.telemetry.metrics.metrics_to_string(event_loop_metrics)
 
     assert tru_str == exp_str
+
+
+def test_setup_meter_if_meter_provider_is_set(
+    mock_get_meter_provider,
+    mock_resource,
+):
+    """Test global meter_provider and meter are used"""
+    mock_resource_instance = mock.MagicMock()
+    mock_resource.create.return_value = mock_resource_instance
+
+    metricsClient = MetricsClient()
+
+    mock_get_meter_provider.assert_called()
+    mock_get_meter_provider.return_value.get_meter.assert_called_with("strands-agents")
+
+    assert metricsClient is not None
+
+
+def test_use_ProxyMeter_if_no_global_meter_provider():
+    """Return _ProxyMeter"""
+    metricsClient = MetricsClient()
+
+    assert isinstance(metricsClient.meter, _ProxyMeter)