claude-code - 💡(How to fix) Fix [DOCS] Monitoring usage missing v2.1.121 `llm_request` span attributes [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Traces (beta) → Span attributes for claude_code.llm_request, plus the OTEL_LOG_USER_PROMPTS gating notes for trace content

Current Documentation

The claude_code.llm_request table currently lists these attributes:

| model | Model identifier | | | gen_ai.system | Always anthropic. OpenTelemetry GenAI semantic convention | | | gen_ai.request.model | Same value as model. OpenTelemetry GenAI semantic convention | | | query_source | Subsystem that issued the request, such as repl_main_thread or a subagent name | | | speed | fast or normal | | | llm_request.context | interaction, tool, or standalone depending on the parent span | | | duration_ms | Wall-clock duration including retries | | | ttft_ms | Time to first token in milliseconds | | | input_tokens | Input token count from the API usage block | | | output_tokens | Output token count | | | cache_read_tokens | Tokens read from prompt cache | | | cache_creation_tokens | Tokens written to prompt cache | | | request_id | Anthropic API request ID from the request-id response header | | | gen_ai.response.id | Same value as request_id. OpenTelemetry GenAI semantic convention | | | client_request_id | Client-generated x-client-request-id of the final attempt | | | attempt | Total attempts made for this request | | | success | true or false | | | status_code | HTTP status code when the request failed | | | error | Error message when the request failed | | | response.has_tool_call | true when the response contained tool-use blocks | |

The same page also describes the prompt-content gate this way:

| OTEL_LOG_USER_PROMPTS | Enable logging of user prompt content (default: disabled) |

and later:

• User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set OTEL_LOG_USER_PROMPTS=1

The v2.1.121 changelog says:

OpenTelemetry: added stop_reason, gen_ai.response.finish_reasons, and user_system_prompt (gated behind OTEL_LOG_USER_PROMPTS) to LLM request spans

What's Wrong or Missing?

The tracing reference is out of date for v2.1.121.

A. claude_code.llm_request is missing newly added span attributes

The claude_code.llm_request attribute table does not include stop_reason, gen_ai.response.finish_reasons, or user_system_prompt, even though the changelog says they were added to LLM request spans in v2.1.121.

B. The OTEL_LOG_USER_PROMPTS notes do not mention user_system_prompt

Current gating text only describes user prompt content. It does not tell telemetry users that enabling OTEL_LOG_USER_PROMPTS=1 also exposes user_system_prompt on claude_code.llm_request spans.

Suggested Improvement

Update https://code.claude.com/docs/en/monitoring-usage to reflect the v2.1.121 tracing schema:

1. Add stop_reason, gen_ai.response.finish_reasons, and user_system_prompt to the claude_code.llm_request attribute table.
2. Mark user_system_prompt as gated by OTEL_LOG_USER_PROMPTS.
3. Update the OTEL_LOG_USER_PROMPTS variable description and the Security and privacy section so they explain that this flag can expose both user prompt text and user_system_prompt in traces/logs.
4. If useful, add a short note that these fields were added in v2.1.121 so observability users can reconcile schema changes in their dashboards and pipelines.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.121

Exact changelog entry: OpenTelemetry: added stop_reason, gen_ai.response.finish_reasons, and user_system_prompt (gated behind OTEL_LOG_USER_PROMPTS) to LLM request spans