feat: initialized meter

Author: poshinchen

src/strands/agent/agent.py

@@ -26,6 +26,7 @@
 from ..handlers.tool_handler import AgentToolHandler
 from ..models.bedrock import BedrockModel
 from ..telemetry.metrics import EventLoopMetrics
+from ..telemetry.metrics_client import MetricsClient
 from ..telemetry.tracer import get_tracer
 from ..tools.registry import ToolRegistry
 from ..tools.thread_pool_executor import ThreadPoolExecutorWrapper
@@ -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

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, Meter, Trace, metrics_to_string
+from .metrics_client import MetricsClient
 from .tracer import Tracer, get_tracer
 
 __all__ = [
@@ -12,4 +13,6 @@
     "metrics_to_string",
     "Tracer",
     "get_tracer",
+    "Meter",
+    "MetricsClient",
 ]

src/strands/telemetry/metrics.py

@@ -1,10 +1,22 @@
 """Utilities for collecting and reporting performance metrics in the SDK."""
 
 import logging
+import os
 import time
 import uuid
 from dataclasses import dataclass, field
-from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
+from importlib.metadata import version
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+import opentelemetry.metrics as metrics_api
+import opentelemetry.sdk.metrics as metrics_sdk
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    MetricReader,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.resources import Resource
 
 from ..types.content import Message
 from ..types.streaming import Metrics, Usage
@@ -355,3 +367,80 @@ 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 Meter:
+    """Handles OpenTelemetry metrics.
+
+    This class provides a simple interface for creating and managing metrics,
+    with support for sending to OTLP endpoints.
+
+    When the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set, metrics
+    are sent to the OTLP endpoint.
+    """
+
+    def __init__(
+        self,
+        service_name: str = "strands-agents",
+    ) -> None:
+        """Initialize the meter with the given service name.
+
+        Args:
+            service_name: The name of the service for which metrics are being collected.
+        """
+        self.service_name = service_name
+        self.meter_provider: Optional[metrics_api.MeterProvider] = None
+        self.meter: Optional[metrics_api.Meter] = None
+        env_metrics_exporter = os.environ.get("OTEL_METRICS_EXPORTER")
+        if env_metrics_exporter and "none" == env_metrics_exporter:
+            logger.info("OTEL_METRICS_EXPORTER set to 'none', using NoOpMeterProvider")
+            self.meter_provider = metrics_api.NoOpMeterProvider()
+            self.meter = self.meter_provider.get_meter(self.service_name)
+            return
+        if self._is_meter_initialized():
+            self.meter_provider = metrics_api.get_meter_provider()
+            self.meter = self.meter_provider.get_meter(self.service_name)
+            return
+        self._initialize_meter()
+
+    def _initialize_meter(self) -> None:
+        """Initialize the OpenTelemetry meter."""
+        logger.info("initializing meter")
+
+        # 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",
+            }
+        )
+
+        # note: it is a concrete implementation from `opentelemetry.sdk`
+        metric_readers = self._create_metric_readers()
+        self.meter_provider = metrics_sdk.MeterProvider(resource=resource, metric_readers=metric_readers)
+
+        # initialize global meter provider
+        metrics_api.set_meter_provider(self.meter_provider)
+        self.meter = metrics_api.get_meter(self.service_name)
+
+    def _is_meter_initialized(self) -> bool:
+        meter_provider = metrics_api.get_meter_provider()
+        return isinstance(meter_provider, metrics_sdk.MeterProvider)
+
+    def _create_metric_readers(self) -> Sequence[MetricReader]:
+        """MetricReaders define how metrics are emitted by OTEL."""
+        # export metrics in batches at designated intervals
+        periodic_metric_reader = PeriodicExportingMetricReader(
+            exporter=OTLPMetricExporter(
+                preferred_temporality={
+                    # Prefer 'DELTA' temporality to avoid storing previous measurements
+                    # https://opentelemetry.io/docs/specs/otel/metrics/data-model/#temporality
+                    metrics_sdk.Counter: AggregationTemporality.DELTA,
+                    metrics_sdk.UpDownCounter: AggregationTemporality.DELTA,
+                    metrics_sdk.Histogram: AggregationTemporality.DELTA,
+                }
+            ),
+        )
+        return [periodic_metric_reader]

src/strands/telemetry/metrics_client.py

@@ -0,0 +1,67 @@
+"""MetricsClient for OpenTelemetry integration.
+
+This module provides meter capabilities using OpenTelemetry,
+enabling metrics data to be sent to OTLP endpoints.
+"""
+
+import threading
+from logging import getLogger
+
+from opentelemetry.metrics import Counter, Meter
+
+from ..telemetry import metrics_constants as constants
+from ..telemetry.metrics import Meter as StrandsMeter
+
+logger = getLogger(__name__)
+
+
+class MetricsClient:
+    """Creates a new instance of the MetricsClient class if it doesn't exist, otherwise returns the existing instance.
+
+    :return: The instance of the MetricsClient class.
+    """
+
+    _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):
+        """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 = StrandsMeter()
+                    cls._instance.meter = meter.meter
+                    cls._instance.create_instruments()
+        return cls._instance
+
+    def create_instruments(self):
+        """Creates the OpenTelemetry Counter instruments."""
+        if not self.meter:
+            logger.warning("Meter is not initialized")
+            return
+        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/tracer.py

@@ -139,7 +139,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(
                 [
@@ -153,8 +152,8 @@ def __init__(
             self._initialize_tracer()
 
     def _initialize_tracer(self) -> None:
-        """Initialize the OpenTelemetry tracer."""
-        logger.info("initializing tracer")
+        """Initialize the OpenTelemetry tracer and meter."""
+        logger.info("initializing tracer and meter")
 
         if self._is_initialized():
             self.tracer_provider = trace_api.get_tracer_provider()
@@ -175,13 +174,13 @@ def _initialize_tracer(self) -> None:
         self.tracer_provider = SDKTracerProvider(resource=resource)
 
         # Add console exporter if enabled
-        if self.enable_console_export and self.tracer_provider:
+        if self.enable_console_export:
             logger.info("enabling console export")
             console_processor = SimpleSpanProcessor(ConsoleSpanExporter())
             self.tracer_provider.add_span_processor(console_processor)
 
         # Add OTLP exporter if endpoint is provided
-        if self.otlp_endpoint and self.tracer_provider:
+        if self.otlp_endpoint:
             try:
                 # Ensure endpoint has the right format
                 endpoint = self.otlp_endpoint
@@ -204,6 +203,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)
 
@@ -294,7 +294,7 @@ def _end_span(
         finally:
             span.end()
             # Force flush to ensure spans are exported
-            if self.tracer_provider and hasattr(self.tracer_provider, 'force_flush'):
+            if self.tracer_provider and hasattr(self.tracer_provider, "force_flush"):
                 try:
                     self.tracer_provider.force_flush()
                 except Exception as e:

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()