AzureAIOpenTelemetryTracer

Temporarily adopt an upstream trace context extracted from headers.

This enables scenarios where an HTTP ingress or orchestrator wants to ensure the LangGraph spans are correlated with the inbound trace.

Handle start of a chain/agent invocation.

Creates an invoke_agent span when the chain represents a traced LangGraph node or agent. Chains that are filtered out by _should_ignore_agent_span (internal routing, middleware, etc.) are recorded in _ignored_runs so that :meth:on_chain_end and :meth:on_chain_error skip them as well.

Handle completion of a chain/agent invocation.

Closes the invoke_agent span started by :meth:on_chain_start, records output messages and GOTO routing metadata, propagates accumulated token usage to parent agent spans, and emits the final StatusCode.OK.

Handle errors raised during chain execution.

Records the error type and message on the span, sets StatusCode.ERROR, and propagates accumulated token usage before closing the span.

Record chat model start and create a chat span.

Record LLM (text-completion) start and create a text_completion span.

Record LLM response attributes and finish the span.

Extracts token usage (input/output/total), response model name, finish reason, tool calls, and assistant messages from the LLMResult. Token counts are propagated to parent agent spans for aggregated usage reporting.

Mark the LLM span as errored and close it.

Record streaming chunk timing metrics without mutating span events.

Updates the time_to_first_chunk histogram on the first token and time_per_output_chunk on subsequent tokens. No span events or attributes are written here — the final response is recorded in :meth:on_llm_end.

Create a span representing tool execution.

Records the tool name, description, type, and input arguments. When content recording is enabled, tool call arguments are included in the span attributes.

Finalize a tool span with results and close it.

Records the tool output. If the output is a LangGraph Command-like object, GOTO routing metadata is also captured.

Mark a tool span as errored and close it.

Cache tool context emitted from agent actions.

AgentAction is emitted before tool execution. This method stores the tool name, input, and log in the parent agent span's stash so that subsequent :meth:on_tool_start calls can include richer context.

Close an agent span, record outputs, and propagate token usage.

Start a retriever span.

Creates an execute_tool span with tool_type=retriever and records the retriever query.

Record retriever results and close the span.

Formats retrieved documents and stores them as the gen_ai.retriever.results span attribute.

Mark a retriever span as errored and close it.

Emit a gen_ai.evaluation.result event for an agent span.

Per the OpenTelemetry semantic conventions for GenAI events <https://github.com/open-telemetry/semantic-conventions/blob/main/model/gen-ai/events.yaml>_, the event SHOULD be parented to the GenAI operation span being evaluated. This method activates the target span's context before emitting, so the event is correctly correlated.

The event is emitted via the OTel Logs/Events API (not the deprecated span.add_event()), following the OTel deprecation of Span Events <https://opentelemetry.io/blog/2026/deprecating-span-events/>_. This ensures the event lands in the customEvents table in Azure Monitor / Application Insights (via AzureMonitorLogExporter), where it is independently queryable.

When the OTel Logs API is not available, falls back to the legacy span.add_event() path.