claude-code - 💡(How to fix) Fix [DOCS] Monitoring reference omits subagent `agent_id` and `parent_agent_id` on OTEL tool spans [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/monitoring-usage

Section/Topic

Traces (beta) → Span hierarchy and Span attributes

Current Documentation

The docs currently say:

Each user prompt starts a claude_code.interaction root span. API calls, tool calls, and hook executions are recorded as its children. Tool spans have two child spans of their own: one for the time spent waiting on a permission decision and one for the execution itself. When the Task tool spawns a subagent, the subagent's API and tool spans nest under the parent's claude_code.tool span.

claude_code.llm_request

Attribute	Description
agent_id	Identifier of the subagent or teammate that issued the request. Absent on the main session
parent_agent_id	Identifier of the agent that spawned this one. Absent for the main session and for agents spawned directly from it

claude_code.tool

Attribute	Description
tool_name	Tool name
duration_ms	Wall-clock duration including permission wait and execution
result_tokens	Approximate token size of the tool result
subagent_type	Subagent type for the Task tool

What's Wrong or Missing?

The page documents the subagent trace-parenting change, and it documents agent_id / parent_agent_id for claude_code.llm_request spans, but the claude_code.tool attribute table does not document those same subagent-attribution fields.

For the v2.1.145 tracing change, this leaves the tool-span schema incomplete: someone querying OpenTelemetry traces can see that subagent spans nest under the dispatching tool span, but the reference does not tell them that the dispatching/subagent tool spans also carry agent_id and parent_agent_id for correlation.

Suggested Improvement

Add agent_id and parent_agent_id rows to the claude_code.tool span attribute table, with the same scope notes used for claude_code.llm_request:

• agent_id: identifier of the subagent or teammate that issued the tool span; absent on the main session
• parent_agent_id: identifier of the agent that spawned this one; absent on the main session and for agents spawned directly from it

That would make the trace-parenting explanation and the span-attribute reference consistent for subagent tracing.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Relevant changelog version: v2.1.145