claude-code - 💡(How to fix) Fix [DOCS] OpenTelemetry monitoring docs missing command and effort attributes [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

OpenTelemetry metrics and events attribute reference, plus the OTEL_LOG_TOOL_DETAILS redaction behavior

Current Documentation

The docs currently say:

Cost counter

Incremented after each API request.

Attributes:

• All standard attributes
• model: Model identifier (for example, "claude-sonnet-4-6")

Token counter

Incremented after each API request.

Attributes:

• All standard attributes
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Model identifier (for example, "claude-sonnet-4-6")

User prompt event

Logged when a user submits a prompt.

Attributes:

• All standard attributes
• event.name: "user_prompt"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• prompt_length: Length of the prompt
• prompt: Prompt content (redacted by default, enable with OTEL_LOG_USER_PROMPTS=1)

API request event

Attributes:

• All standard attributes
• event.name: "api_request"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, "claude-sonnet-4-6")
• cost_usd: Estimated cost in USD
• duration_ms: Request duration in milliseconds
• input_tokens: Number of input tokens
• output_tokens: Number of output tokens
• cache_read_tokens: Number of tokens read from cache
• cache_creation_tokens: Number of tokens used for cache creation
• speed: "fast" or "normal", indicating whether fast mode was active

API error event

Attributes:

• All standard attributes
• event.name: "api_error"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, "claude-sonnet-4-6")
• error: Error message
• status_code: HTTP status code as a string, or "undefined" for non-HTTP errors
• duration_ms: Request duration in milliseconds
• attempt: Total number of attempts made, including the initial request (1 means no retries occurred)
• speed: "fast" or "normal", indicating whether fast mode was active

The related Agent SDK observability page also currently says:

Telemetry is structural by default. Token counts, durations, model names, and tool names are always recorded, but the content your agent reads and writes is not.

| OTEL_LOG_TOOL_DETAILS=1 | Tool input arguments (file paths, shell commands, search patterns) on claude_code.tool_result events |

What's Wrong or Missing?

The OpenTelemetry reference is outdated for the v2.1.117 telemetry schema changes.

A. claude_code.user_prompt is missing the new slash-command fields

The event docs do not mention command_name or command_source for slash-command prompts.

B. Metrics and API events are missing the effort attribute

The docs do not mention that claude_code.cost.usage, claude_code.token.usage, claude_code.api_request, and claude_code.api_error now include an effort attribute when the active model supports effort levels.

C. Redaction behavior for custom and MCP command names is undocumented

The current docs say tool names are always recorded and describe OTEL_LOG_TOOL_DETAILS=1 mainly as enabling tool parameters/input arguments. They do not explain that custom command names and MCP command names are redacted unless OTEL_LOG_TOOL_DETAILS=1 is set.

Suggested Improvement

Update the OpenTelemetry docs to match the v2.1.117 behavior:

1. In https://code.claude.com/docs/en/monitoring-usage, add command_name and command_source to the claude_code.user_prompt event attributes, with a note that they are populated for slash commands.
2. Add effort to the documented attributes for claude_code.cost.usage, claude_code.token.usage, claude_code.api_request, and claude_code.api_error, and note that it appears only when the model supports effort levels.
3. In the security/privacy and environment-variable sections, document that custom command names and MCP command names are redacted by default and are only emitted when OTEL_LOG_TOOL_DETAILS=1 is enabled.
4. Mirror the same redaction explanation in https://code.claude.com/docs/en/agent-sdk/observability so the SDK page stays consistent with the main monitoring reference.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.117

Changelog entry: OpenTelemetry: user_prompt events now include command_name and command_source for slash commands; cost.usage, token.usage, api_request, and api_error now include an effort attribute when the model supports effort levels. Custom/MCP command names are redacted unless OTEL_LOG_TOOL_DETAILS=1 is set