Python · Instrumentation
openinference-instrumentation-strands-agents
OpenInference span processor for Strands Agents - transforms native OpenTelemetry spans to OpenInference format
- Module
openinference.instrumentation.strands_agents- Version
- 0.1.20
- Python
- >=3.10, <3.16
- Instruments
strands-agents >= 1.19.0
Install
pip install openinference-instrumentation-strands-agentsopeninference.instrumentation.strands_agents
OpenInference Instrumentation for Strands Agents.
This package provides a span processor that transforms Strands’ native OpenTelemetry spans (using GenAI semantic conventions) into OpenInference format for compatibility with OpenInference-supported OTEL backends (Phoenix, Arize, etc.).
Usage
from strands.telemetry import StrandsTelemetry
from openinference.instrumentation.strands_agents import StrandsAgentsToOpenInferenceProcessor
# Setup Strands native telemetry
telemetry = StrandsTelemetry()
telemetry.setup_otlp_exporter(endpoint="http://localhost:6006/v1/traces")
# Add OpenInference processor to transform spans
telemetry.tracer_provider.add_span_processor(
StrandsAgentsToOpenInferenceProcessor(debug=False)
)
# Now use your Strands agents normally - spans will be automatically transformed
from strands import Agent
from strands.models.openai import OpenAIModel
model = OpenAIModel(model_id="gpt-4o-mini")
agent = Agent(name="MyAgent", model=model)
result = agent("Hello!")The processor handles:
- Span kind mapping (invoke_agent → AGENT, execute_event_loop_cycle → CHAIN, etc.)
- Attribute transformation (gen_ai.* → llm., tool., agent.*)
- Event extraction (gen_ai.user.message → llm.input_messages)
- Token usage mapping (gen_ai.usage.* → llm.token_count.*)
- Tool parameter extraction
- Message structure flattening
For more information, see: https://github.com/Arize-ai/openinference
StrandsAgentsToOpenInferenceProcessor
classSource ↗class StrandsAgentsToOpenInferenceProcessor(
debug: bool = False,
config: Optional[TraceConfig] = None,
)Also importable from openinference.instrumentation.strands_agents.processor.
SpanProcessor that converts Strands Agents telemetry attributes to OpenInference format for compatibility with OpenInference-compliant backends.
Important: This processor mutates spans in-place. Add it BEFORE any span processors/exporters that should receive the transformed OpenInference spans.
Example
# Correct order: processor first, then exporter
tracer_provider.add_span_processor(StrandsAgentsToOpenInferenceProcessor())
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))Attributes
| Name | Type and value |
|---|---|
debug | debug |
on_start
methodSource ↗def on_start(
span: Span,
parent_context: Optional[Context] = None,
) -> NoneCalled when a span is started.
on_end
methodSource ↗def on_end(span: ReadableSpan) -> NoneCalled when a span ends. Transform the span attributes from Strands format to OpenInference format.
shutdown
methodSource ↗def shutdown() -> NoneShutdown the processor. No-op for this processor.
force_flush
methodSource ↗def force_flush(timeout_millis: Optional[int] = None) -> boolget_migration_guide
staticmethodSource ↗def get_migration_guide() -> Dict[str, str]openinference.instrumentation.strands_agents.semantic_conventions
Strands-specific GenAI semantic convention constants.
This module provides constants from OpenTelemetry’s GenAI semantic conventions, along with additional constants commonly used for mapping GenAI attributes to OpenInference format.
These constants are kept local to the strands instrumentation package to avoid coupling issues with the volatile gen_ai conventions as different 3rd party tools update their OTEL usage at different rates.
GEN_AI_PROVIDER_NAME
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_PROVIDER_NAME.
GEN_AI_REQUEST_MODEL
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_REQUEST_MODEL.
GEN_AI_SYSTEM
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_SYSTEM.
GEN_AI_TOOL_CALL_ID
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_TOOL_CALL_ID.
GEN_AI_TOOL_NAME
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_TOOL_NAME.
GEN_AI_USAGE_INPUT_TOKENS
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_USAGE_INPUT_TOKENS.
GEN_AI_USAGE_OUTPUT_TOKENS
re-exportRe-exported from opentelemetry.semconv._incubating.attributes.gen_ai_attributes.GEN_AI_USAGE_OUTPUT_TOKENS.
GEN_AI_REQUEST_MAX_TOKENS
attributeSource ↗GEN_AI_REQUEST_MAX_TOKENS = 'gen_ai.request.max_tokens'GEN_AI_REQUEST_TEMPERATURE
attributeSource ↗GEN_AI_REQUEST_TEMPERATURE = 'gen_ai.request.temperature'GEN_AI_REQUEST_TOP_P
attributeSource ↗GEN_AI_REQUEST_TOP_P = 'gen_ai.request.top_p'GEN_AI_INPUT_MESSAGES
attributeSource ↗GEN_AI_INPUT_MESSAGES = 'gen_ai.input.messages'GEN_AI_OUTPUT_MESSAGES
attributeSource ↗GEN_AI_OUTPUT_MESSAGES = 'gen_ai.output.messages'GEN_AI_SYSTEM_INSTRUCTIONS
attributeSource ↗GEN_AI_SYSTEM_INSTRUCTIONS = 'gen_ai.system_instructions'GEN_AI_TOOL_CALL_ARGUMENTS
attributeSource ↗GEN_AI_TOOL_CALL_ARGUMENTS = 'gen_ai.tool.call.arguments'GEN_AI_TOOL_CALL_RESULT
attributeSource ↗GEN_AI_TOOL_CALL_RESULT = 'gen_ai.tool.call.result'GEN_AI_USAGE_CACHE_CREATION_TOKENS
attributeSource ↗GEN_AI_USAGE_CACHE_CREATION_TOKENS = 'gen_ai.usage.cache_creation.input_tokens'GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS
attributeSource ↗GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read_input_tokens'GEN_AI_USAGE_CACHE_READ_TOKENS
attributeSource ↗GEN_AI_USAGE_CACHE_READ_TOKENS = 'gen_ai.usage.cache_read.input_tokens'GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS
attributeSource ↗GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS = 'gen_ai.usage.cache_write_input_tokens'GenAIAttributes
classSource ↗class GenAIAttributesGenAI attribute names used by Strands agents.
Attributes
| Name | Type and value |
|---|---|
USAGE_PROMPT_TOKENS | 'gen_ai.usage.prompt_tokens' |
USAGE_COMPLETION_TOKENS | 'gen_ai.usage.completion_tokens' |
USAGE_TOTAL_TOKENS | 'gen_ai.usage.total_tokens' |
AGENT_NAME | 'gen_ai.agent.name' |
AGENT_TOOLS | 'gen_ai.agent.tools' |
TOOL_CALL_ID | 'gen_ai.tool.call.id' |
SYSTEM_PROMPT | 'system_prompt' |
PROMPT | 'gen_ai.prompt' |
COMPLETION | 'gen_ai.completion' |
GenAIEventNames
classSource ↗class GenAIEventNamesGenAI event names for OTEL events.
Attributes
| Name | Type and value |
|---|---|
SYSTEM_MESSAGE | 'gen_ai.system.message' |
USER_MESSAGE | 'gen_ai.user.message' |
ASSISTANT_MESSAGE | 'gen_ai.assistant.message' |
TOOL_MESSAGE | 'gen_ai.tool.message' |
CHOICE | 'gen_ai.choice' |
safe_json_dumps
functionSource ↗def safe_json_dumps(obj: Any, **kwargs: Any = {}) -> strA convenience wrapper around json.dumps that ensures that any object can
be safely encoded without a TypeError and that non-ASCII Unicode
characters are not escaped.