strands.telemetry.metrics

Utilities for collecting and reporting performance metrics in the SDK.

Trace

class Trace()

Defined in: src/strands/telemetry/metrics.py:21

A trace representing a single operation or step in the execution flow.

__init__

def __init__(name: str,
             parent_id: str | None = None,
             start_time: float | None = None,
             raw_name: str | None = None,
             metadata: dict[str, Any] | None = None,
             message: Message | None = None) -> None

Defined in: src/strands/telemetry/metrics.py:24

Initialize a new trace.

Arguments:

• name - Human-readable name of the operation being traced.
• parent_id - ID of the parent trace, if this is a child operation.
• start_time - Timestamp when the trace started. If not provided, the current time will be used.
• raw_name - System level name.
• metadata - Additional contextual information about the trace.
• message - Message associated with the trace.

end

def end(end_time: float | None = None) -> None

Defined in: src/strands/telemetry/metrics.py:54

Mark the trace as complete with the given or current timestamp.

Arguments:

• end_time - Timestamp to use as the end time. If not provided, the current time will be used.

add_child

def add_child(child: "Trace") -> None

Defined in: src/strands/telemetry/metrics.py:63

Add a child trace to this trace.

Arguments:

• child - The child trace to add.

duration

def duration() -> float | None

Defined in: src/strands/telemetry/metrics.py:71

Calculate the duration of this trace.

Returns:

The duration in seconds, or None if the trace hasn’t ended yet.

add_message

def add_message(message: Message) -> None

Defined in: src/strands/telemetry/metrics.py:79

Add a message to the trace.

Arguments:

• message - The message to add.

to_dict

def to_dict() -> dict[str, Any]

Defined in: src/strands/telemetry/metrics.py:87

Convert the trace to a dictionary representation.

Returns:

A dictionary containing all trace information, suitable for serialization.

ToolMetrics

@dataclass
class ToolMetrics()

Defined in: src/strands/telemetry/metrics.py:108

Metrics for a specific tool’s usage.

Attributes:

• tool - The tool being tracked.
• call_count - Number of times the tool has been called.
• success_count - Number of successful tool calls.
• error_count - Number of failed tool calls.
• total_time - Total execution time across all calls in seconds.

add_call

def add_call(tool: ToolUse,
             duration: float,
             success: bool,
             metrics_client: "MetricsClient",
             attributes: dict[str, Any] | None = None) -> None

Defined in: src/strands/telemetry/metrics.py:125

Record a new tool call with its outcome.

Arguments:

• tool - The tool that was called.
• duration - How long the call took in seconds.
• success - Whether the call was successful.
• metrics_client - The metrics client for recording the metrics.
• attributes - attributes of the metrics.

EventLoopCycleMetric

@dataclass
class EventLoopCycleMetric()

Defined in: src/strands/telemetry/metrics.py:156

Aggregated metrics for a single event loop cycle.

Attributes:

• event_loop_cycle_id - Current eventLoop cycle id.
• usage - Total token usage for the entire cycle (succeeded model invocation, excluding tool invocations).

AgentInvocation

@dataclass
class AgentInvocation()

Defined in: src/strands/telemetry/metrics.py:169

Metrics for a single agent invocation.

AgentInvocation contains all the event loop cycles and accumulated token usage for that invocation.

Attributes:

• cycles - List of event loop cycles that occurred during this invocation.
• usage - Accumulated token usage for this invocation across all cycles.

EventLoopMetrics

@dataclass
class EventLoopMetrics()

Defined in: src/strands/telemetry/metrics.py:184

Aggregated metrics for an event loop’s execution.

Attributes:

• cycle_count - Number of event loop cycles executed.
• tool_metrics - Metrics for each tool used, keyed by tool name.
• cycle_durations - List of durations for each cycle in seconds.
• agent_invocations - Agent invocation metrics containing cycles and usage data.
• traces - List of execution traces.
• accumulated_usage - Accumulated token usage across all model invocations (across all requests).
• accumulated_metrics - Accumulated performance metrics across all model invocations.

latest_agent_invocation

@property
def latest_agent_invocation() -> AgentInvocation | None

Defined in: src/strands/telemetry/metrics.py:211

Get the most recent agent invocation.

Returns:

The most recent AgentInvocation, or None if no invocations exist.

start_cycle

def start_cycle(attributes: dict[str, Any]) -> tuple[float, Trace]

Defined in: src/strands/telemetry/metrics.py:219

Start a new event loop cycle and create a trace for it.

Arguments:

• attributes - attributes of the metrics, including event_loop_cycle_id.

Returns:

A tuple containing the start time and the cycle trace object.

end_cycle

def end_cycle(start_time: float,
              cycle_trace: Trace,
              attributes: dict[str, Any] | None = None) -> None

Defined in: src/strands/telemetry/metrics.py:247

End the current event loop cycle and record its duration.

Arguments:

• start_time - The timestamp when the cycle started.
• cycle_trace - The trace object for this cycle.
• attributes - attributes of the metrics.

add_tool_usage

def add_tool_usage(tool: ToolUse, duration: float, tool_trace: Trace,
                   success: bool, message: Message) -> None

Defined in: src/strands/telemetry/metrics.py:262

Record metrics for a tool invocation.

Arguments:

• tool - The tool that was used.
• duration - How long the tool call took in seconds.
• tool_trace - The trace object for this tool call.
• success - Whether the tool call was successful.
• message - The message associated with the tool call.

update_usage

def update_usage(usage: Usage) -> None

Defined in: src/strands/telemetry/metrics.py:320

Update the accumulated token usage with new usage data.

Arguments:

• usage - The usage data to add to the accumulated totals.

reset_usage_metrics

def reset_usage_metrics() -> None

Defined in: src/strands/telemetry/metrics.py:343

Start a new agent invocation by creating a new AgentInvocation.

This should be called at the start of a new request to begin tracking a new agent invocation with fresh usage and cycle data.

update_metrics

def update_metrics(metrics: Metrics) -> None

Defined in: src/strands/telemetry/metrics.py:351

Update the accumulated performance metrics with new metrics data.

Arguments:

• metrics - The metrics data to add to the accumulated totals.

get_summary

def get_summary() -> dict[str, Any]

Defined in: src/strands/telemetry/metrics.py:362

Generate a comprehensive summary of all collected metrics.

Returns:

A dictionary containing summarized metrics data. This includes cycle statistics, tool usage, traces, and accumulated usage information.

metrics_to_string

def metrics_to_string(event_loop_metrics: EventLoopMetrics,
                      allowed_names: set[str] | None = None) -> str

Defined in: src/strands/telemetry/metrics.py:501

Convert event loop metrics to a human-readable string representation.

Arguments:

• event_loop_metrics - The metrics to format.
• allowed_names - Set of names that are allowed to be displayed unmodified.

Returns:

A formatted string representation of the metrics.

MetricsClient

class MetricsClient()

Defined in: src/strands/telemetry/metrics.py:514

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.

__new__

def __new__(cls) -> "MetricsClient"

Defined in: src/strands/telemetry/metrics.py:538

Create or return the singleton instance of MetricsClient.

Returns:

The single MetricsClient instance.

__init__

def __init__() -> None

Defined in: src/strands/telemetry/metrics.py:548

Initialize the MetricsClient.

This method only runs once due to the singleton pattern. Sets up the OpenTelemetry meter and creates metric instruments.

create_instruments

def create_instruments() -> None

Defined in: src/strands/telemetry/metrics.py:562

Create and initialize all OpenTelemetry metric instruments.