[DOCS] OpenTelemetry monitoring docs missing command and effort attributes

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](#standard-attributes) model: Model identifier (for example, "claude-sonnet-4-6")

#### Token counter Incremented after each API request. Attributes: All [standard attributes](#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](#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](#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](#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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/monitoring-usage | Primary reference for OpenTelemetry metric and event attributes |
| https://code.claude.com/docs/en/env-vars | Documents OTEL_LOG_TOOL_DETAILS but not the new command-name redaction behavior |
| https://code.claude.com/docs/en/agent-sdk/observability | Repeats the current redaction model for SDK users |

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