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

src/strands/telemetry/metrics.py

@@ -4,7 +4,18 @@
 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 +366,74 @@ 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
+        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,72 @@
+"""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"
+        )
+
+
+def get_metrics_client() -> MetricsClient:
+    """Get the singleton instance of MetricsClient."""
+    return MetricsClient()

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,10 +152,10 @@ 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():
+        if self._is_tracer_initialized():
             self.tracer_provider = trace_api.get_tracer_provider()
             self.tracer = self.tracer_provider.get_tracer(self.service_name)
             return
@@ -175,43 +174,35 @@ 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
-                if not endpoint.endswith("/v1/traces") and not endpoint.endswith("/traces"):
-                    if not endpoint.endswith("/"):
-                        endpoint += "/"
-                    endpoint += "v1/traces"
-
                 # Set default content type header if not provided
                 headers = self.otlp_headers.copy()
                 if "Content-Type" not in headers:
                     headers["Content-Type"] = "application/x-protobuf"
 
                 # Create OTLP exporter and processor
                 otlp_exporter = OTLPSpanExporter(
-                    endpoint=endpoint,
                     headers=headers,
                 )
 
                 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)
 
         # Set as global tracer provider
         trace_api.set_tracer_provider(self.tracer_provider)
         self.tracer = trace_api.get_tracer(self.service_name)
 
-    def _is_initialized(self) -> bool:
+    def _is_tracer_initialized(self) -> bool:
         tracer_provider = trace_api.get_tracer_provider()
         return isinstance(tracer_provider, SDKTracerProvider)
 
@@ -294,7 +285,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: