Module loop_instrument 

Available on crate feature otel only.

Reusable chat / execute_tool span + metric helpers.

These primitives are shared by every agent-loop implementation so the daemon-hosted worker emits byte-identical telemetry to the in-process loop.

Why this module exists

The SDK ships two agent-loop implementations:

• the in-process agent_loop (used by AgentLoop / BipAgent), and
• the daemon-hosted re-implementation in agent-server’s worker (crates/agent-server/src/worker/root_turn.rs + agent-service-host’s registry_tool_executor.rs).

Both drive an LLM call and a tool dispatch, and both must emit the same gen_ai.* / agent_sdk.* telemetry so dashboards built against the in-process loop light up unchanged when a session runs on the daemon. Before this module the worker bypassed the SDK instrumentation entirely and emitted none of it.

Rather than copy the span names, attribute keys, and metric label sets into agent-server (where they would silently drift), this module exposes the exact primitives the in-process loop uses:

• build_chat_span / finish_chat_span_success / finish_chat_span_error mirror agent_loop::turn’s build_llm_span / stamp_llm_success / stamp_llm_error.
• build_tool_span / finish_tool_span / ToolSpanOutcome mirror agent_loop::tool_execution’s start_tool_span / finish_tool_span.

The metric recording underneath delegates to crate::observability::metrics::Metrics (the same global singleton), so there is a single source of truth for the label sets and no second meter scope.

Compiled only with feature = "otel".

Structs

ChatSpanParams

Inputs needed to open a chat {model} CLIENT span.

RootTurnSpanParams

Inputs needed to open the daemon’s root invoke_agent span.

StartedRootTurnSpan

A started root-turn span plus the hex ids the worker persists so the turn’s later tasks can re-parent their spans under it.

ToolSpanParams

Inputs needed to open an execute_tool INTERNAL span.

Enums

ToolSpanOutcome

Terminal outcome of a tool execution, used to stamp the outcome attributes + metric labels on an execute_tool span.

Functions

build_chat_span

Open a chat {model} CLIENT span with the gen_ai semconv attributes known before the call.

build_tool_span

Open an execute_tool INTERNAL span.

classify_llm_error

Map a free-form LLM error message to the stable error.type attribute / metric label.

context_from_traceparent

Rebuild an OTel Context from a persisted W3C traceparent.

discard_root_turn_span

Drop the stashed root-turn span for task_id without finalizing.

finalize_root_turn_span

Finalize and end the stashed root-turn span for task_id, stamping run-outcome + usage attributes (see finish_root_turn_span).

finish_chat_span_error

Stamp a chat error onto span, record the gen_ai.client.operation.duration metric with the error.type label, and end the span.

finish_chat_span_success

Stamp a successful chat response onto span, record the gen_ai.client.token.usage + gen_ai.client.operation.duration metrics, and end the span.

finish_reason_str

Map an SDK StopReason to the semconv finish_reason string.

finish_root_turn_span

Finalize the root-turn span with run-outcome attributes + the agent_sdk.runs.outcome counter, then end it.

finish_tool_span

Stamp the terminal outcome on span, record the agent_sdk.tools.execution.{count,duration} metrics, and end the span.

remote_parent_context

Build a Context whose active parent is the root-turn span identified by the hex ids persisted on the turn attempt.

remote_parent_context_with_sampling

Re-parent a child onto a remote span, preserving the root’s real sampled bit.

start_root_turn_span

Start the daemon’s root invoke_agent INTERNAL span and capture the ids the worker persists so the turn’s later tasks can nest under it.

stash_root_turn_span

Stash the live root-turn span under task_id so a later task can finalize it with the correct full duration (see LIVE_ROOT_SPANS).

traceparent_from_ids

Encode hex trace + span ids into a W3C traceparent string.

traceparent_from_ids_with_sampling

Encode hex trace + span ids into a W3C traceparent, stamping the root span’s real sampled bit in the flag byte (-01 when sampled, -00 otherwise).