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.

is_langfuse

@property
def is_langfuse() -> bool

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

Check if Langfuse is configured as the OTLP endpoint.

Returns:

True if Langfuse is the OTLP endpoint, False otherwise.

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:227

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,
                            system_prompt: str | None = None,
                            system_prompt_content: list | None = None,
                            **kwargs: Any) -> Span

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

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.
• system_prompt - Optional system prompt string provided to the model.
• system_prompt_content - Optional list of system prompt content blocks.
• **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:326

End a model invocation span with results and metrics.

Arguments:

• span - The span to end.
• 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:383

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:453

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:506

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:548

End an event loop cycle span with results.

Arguments:

• span - The span to end.
• 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:590

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:649

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:719

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:760

End a swarm span with results.

get_tracer

def get_tracer() -> Tracer

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

Get or create the global tracer.

Returns:

The global tracer instance.

serialize

def serialize(obj: Any) -> str

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

Serialize an object to JSON with consistent settings.

Arguments:

• obj - The object to serialize

Returns:

JSON string representation of the object