Skip to content

strands.telemetry.tracer

OpenTelemetry integration.

This module provides tracing capabilities using OpenTelemetry, enabling trace data to be sent to OTLP endpoints.

JSONEncoder

class JSONEncoder(json.JSONEncoder)

Defined in: src/strands/telemetry/tracer.py:29

Custom JSON encoder that handles non-serializable types.

encode

def encode(obj: Any) -> str

Defined in: src/strands/telemetry/tracer.py:32

Recursively encode objects, preserving structure and only replacing unserializable values.

Arguments:

  • obj - The object to encode

Returns:

JSON string representation of the object

Tracer

class Tracer()

Defined in: src/strands/telemetry/tracer.py:77

Handles OpenTelemetry tracing.

This class provides a simple interface for creating and managing traces, with support for sending to OTLP endpoints.

When the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set, traces are sent to the OTLP endpoint.

Both attributes are controlled by including “gen_ai_latest_experimental” or “gen_ai_tool_definitions”, respectively, in the OTEL_SEMCONV_STABILITY_OPT_IN environment variable.

__init__

def __init__() -> None

Defined in: src/strands/telemetry/tracer.py:90

Initialize the tracer.

end_span_with_error

def end_span_with_error(span: Span,
                        error_message: str,
                        exception: Exception | None = None) -> None

Defined in: src/strands/telemetry/tracer.py:225

End a span with error status.

Arguments:

  • span - The span to end.
  • error_message - Error message to set in the span status.
  • exception - Optional exception to record in the span.

start_model_invoke_span

def start_model_invoke_span(messages: Messages,
                            parent_span: Span | None = None,
                            model_id: str | None = None,
                            custom_trace_attributes: Mapping[str,
                                                             AttributeValue]
                            | None = None,
                            **kwargs: Any) -> Span

Defined in: src/strands/telemetry/tracer.py:276

Start a new span for a model invocation.

Arguments:

  • messages - Messages being sent to the model.
  • parent_span - Optional parent span to link this span to.
  • model_id - Optional identifier for the model being invoked.
  • custom_trace_attributes - Optional mapping of custom trace attributes to include in the span.
  • **kwargs - Additional attributes to add to the span.

Returns:

The created span, or None if tracing is not enabled.

end_model_invoke_span

def end_model_invoke_span(span: Span, message: Message, usage: Usage,
                          metrics: Metrics, stop_reason: StopReason) -> None

Defined in: src/strands/telemetry/tracer.py:312

End a model invocation span with results and metrics.

Note: The span is automatically closed and exceptions recorded. This method just sets the necessary attributes. Status in the span is automatically set to UNSET (OK) on success or ERROR on exception.

Arguments:

  • span - The span to set attributes on.
  • message - The message response from the model.
  • usage - Token usage information from the model call.
  • metrics - Metrics from the model call.
  • stop_reason - The reason the model stopped generating.

start_tool_call_span

def start_tool_call_span(tool: ToolUse,
                         parent_span: Span | None = None,
                         custom_trace_attributes: Mapping[str, AttributeValue]
                         | None = None,
                         **kwargs: Any) -> Span

Defined in: src/strands/telemetry/tracer.py:371

Start a new span for a tool call.

Arguments:

  • tool - The tool being used.
  • parent_span - Optional parent span to link this span to.
  • custom_trace_attributes - Optional mapping of custom trace attributes to include in the span.
  • **kwargs - Additional attributes to add to the span.

Returns:

The created span, or None if tracing is not enabled.

end_tool_call_span

def end_tool_call_span(span: Span,
                       tool_result: ToolResult | None,
                       error: Exception | None = None) -> None

Defined in: src/strands/telemetry/tracer.py:440

End a tool call span with results.

Arguments:

  • span - The span to end.
  • tool_result - The result from the tool execution.
  • error - Optional exception if the tool call failed.

start_event_loop_cycle_span

def start_event_loop_cycle_span(
        invocation_state: Any,
        messages: Messages,
        parent_span: Span | None = None,
        custom_trace_attributes: Mapping[str, AttributeValue] | None = None,
        **kwargs: Any) -> Span

Defined in: src/strands/telemetry/tracer.py:492

Start a new span for an event loop cycle.

Arguments:

  • invocation_state - Arguments for the event loop cycle.
  • parent_span - Optional parent span to link this span to.
  • messages - Messages being processed in this cycle.
  • custom_trace_attributes - Optional mapping of custom trace attributes to include in the span.
  • **kwargs - Additional attributes to add to the span.

Returns:

The created span, or None if tracing is not enabled.

end_event_loop_cycle_span

def end_event_loop_cycle_span(
        span: Span,
        message: Message,
        tool_result_message: Message | None = None) -> None

Defined in: src/strands/telemetry/tracer.py:534

End an event loop cycle span with results.

Note: The span is automatically closed and exceptions recorded. This method just sets the necessary attributes. Status in the span is automatically set to UNSET (OK) on success or ERROR on exception.

Arguments:

  • span - The span to set attributes on.
  • message - The message response from this cycle.
  • tool_result_message - Optional tool result message if a tool was called.

start_agent_span

def start_agent_span(messages: Messages,
                     agent_name: str,
                     model_id: str | None = None,
                     tools: list | None = None,
                     custom_trace_attributes: Mapping[str, AttributeValue]
                     | None = None,
                     tools_config: dict | None = None,
                     **kwargs: Any) -> Span

Defined in: src/strands/telemetry/tracer.py:579

Start a new span for an agent invocation.

Arguments:

  • messages - List of messages being sent to the agent.
  • agent_name - Name of the agent.
  • model_id - Optional model identifier.
  • tools - Optional list of tools being used.
  • custom_trace_attributes - Optional mapping of custom trace attributes to include in the span.
  • tools_config - Optional dictionary of tool configurations.
  • **kwargs - Additional attributes to add to the span.

Returns:

The created span, or None if tracing is not enabled.

end_agent_span

def end_agent_span(span: Span,
                   response: AgentResult | None = None,
                   error: Exception | None = None) -> None

Defined in: src/strands/telemetry/tracer.py:638

End an agent span with results and metrics.

Arguments:

  • span - The span to end.
  • response - The response from the agent.
  • error - Any error that occurred.

start_multiagent_span

def start_multiagent_span(
    task: MultiAgentInput,
    instance: str,
    custom_trace_attributes: Mapping[str, AttributeValue] | None = None
) -> Span

Defined in: src/strands/telemetry/tracer.py:709

Start a new span for swarm invocation.

end_swarm_span

def end_swarm_span(span: Span, result: str | None = None) -> None

Defined in: src/strands/telemetry/tracer.py:749

End a swarm span with results.

get_tracer

def get_tracer() -> Tracer

Defined in: src/strands/telemetry/tracer.py:880

Get or create the global tracer.

Returns:

The global tracer instance.

serialize

def serialize(obj: Any) -> str

Defined in: src/strands/telemetry/tracer.py:894

Serialize an object to JSON with consistent settings.

Arguments:

  • obj - The object to serialize

Returns:

JSON string representation of the object