[DOCS] OpenTelemetry monitoring docs missing `OTEL_LOG_RAW_API_BODIES` configuration

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

OpenTelemetry configuration, API request/API error event reference, and security/privacy guidance for emitted content

Current Documentation

The docs currently say:

| OTEL_LOG_USER_PROMPTS | Enable logging of user prompt content (default: disabled) | 1 to enable |
| OTEL_LOG_TOOL_DETAILS | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | 1 to enable |
| OTEL_LOG_TOOL_CONTENT | Enable logging of tool input and output content in span events (default: disabled). Requires tracing. Content is truncated at 60 KB | 1 to enable |

Event Name: claude_code.api_request

Attributes:

• 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

Event Name: claude_code.api_error

Attributes:

• 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

• User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set OTEL_LOG_USER_PROMPTS=1
• Tool input arguments and parameters are not logged by default. To include them, set OTEL_LOG_TOOL_DETAILS=1.
• Tool input and output content is not logged in trace spans by default. To include it, set OTEL_LOG_TOOL_CONTENT=1.

| OTEL_LOG_TOOL_CONTENT | Set to 1 to include tool input and output content in OpenTelemetry span events. Disabled by default to protect sensitive data. See Monitoring |
| OTEL_LOG_TOOL_DETAILS | Set to 1 to include tool input arguments, MCP server names, and tool details in OpenTelemetry traces and logs. Disabled by default to protect PII. See Monitoring |
| OTEL_LOG_USER_PROMPTS | Set to 1 to include user prompt text in OpenTelemetry traces and logs. Disabled by default (prompts are redacted). See Monitoring |

What's Wrong or Missing?

Changelog v2.1.111 added OTEL_LOG_RAW_API_BODIES to emit full API request and response bodies as OpenTelemetry log events for debugging, but the docs do not mention this environment variable anywhere in the Claude Code monitoring reference or environment variable reference.

The current monitoring docs describe only three content-related opt-in variables (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, and OTEL_LOG_TOOL_CONTENT) and the API request/error event sections do not explain whether raw request or response bodies can be emitted, where they appear, or what privacy/safety limits apply when this mode is enabled.

That leaves users unable to discover the feature from the docs or understand how to enable it safely.

Suggested Improvement

Add OTEL_LOG_RAW_API_BODIES to the OpenTelemetry documentation in the same places that describe the other opt-in content variables.

Specifically:

1. Add the variable to the configuration table on https://code.claude.com/docs/en/monitoring-usage.
2. Update the API request and API error event reference to explain which log events include raw request/response bodies when this variable is enabled.
3. Add security/privacy guidance covering whether bodies are redacted, truncated, or otherwise bounded, plus a warning that backends may need additional filtering.
4. Add the variable to https://code.claude.com/docs/en/env-vars.
5. If Agent SDK callers can pass this through, update https://code.claude.com/docs/en/agent-sdk/observability so the “Control sensitive data in exports” section stays aligned with the CLI monitoring docs.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/monitoring-usage	87-89	OpenTelemetry configuration table lists the current content-related opt-in variables but omits OTEL_LOG_RAW_API_BODIES
https://code.claude.com/docs/en/monitoring-usage	414-452	API request and API error event sections enumerate attributes but do not describe raw request/response body emission
https://code.claude.com/docs/en/monitoring-usage	606-608	Security/privacy guidance says exported content is controlled by three opt-in variables
https://code.claude.com/docs/en/env-vars	192-194	Environment variable reference lists existing OpenTelemetry content variables but omits OTEL_LOG_RAW_API_BODIES
https://code.claude.com/docs/en/agent-sdk/observability	189-197	Agent SDK observability says only three opt-in variables add content to exported data

Total scope: 3 pages affected

Source: Changelog v2.1.111

Exact changelog entry:

Added OTEL_LOG_RAW_API_BODIES environment variable to emit full API request and response bodies as OpenTelemetry log events for debugging

[coygeek]

Issue #49310 Verification

Title: [DOCS] OpenTelemetry monitoring docs missing OTEL_LOG_RAW_API_BODIES configuration
Issue Date: 2026-04-16
Verification Date: 2026-04-28
Status: RESOLVED

---

Issue Summary

This issue reports that the Claude Code OpenTelemetry documentation did not document OTEL_LOG_RAW_API_BODIES, did not explain the related raw API body events, and did not include aligned security guidance and cross-references on the environment variable and Agent SDK observability pages.

---

Verification Results

Claim 1: The monitoring configuration table should include OTEL_LOG_RAW_API_BODIES

Status: RESOLVED

At https://code.claude.com/docs/en/monitoring-usage, lines 87-90, the configuration table now includes: "OTEL_LOG_RAW_API_BODIES" and describes it as: "Emit the full Anthropic Messages API request and response JSON as api_request_body / api_response_body log events (default: disabled). Bodies include the entire conversation history."

Verdict: The missing variable is now documented in the main monitoring configuration table.

---

Claim 2: The monitoring reference should explain which events contain raw request and response bodies

Status: RESOLVED

At https://code.claude.com/docs/en/monitoring-usage, lines 584-598, the docs now add an "API request body event" section stating: "Logged for each API request attempt when OTEL_LOG_RAW_API_BODIES is set" with event name "claude_code.api_request_body" and attributes including "body" and "body_ref". At the same page, lines 603-617 add an "API response body event" section stating: "Logged for each successful API response when OTEL_LOG_RAW_API_BODIES is set" with event name "claude_code.api_response_body" and the corresponding body attributes.

Verdict: The docs now explain where raw request and response bodies appear and how they are emitted.

---

Claim 3: The monitoring reference should include security and privacy guidance for raw API bodies

Status: RESOLVED

At https://code.claude.com/docs/en/monitoring-usage, lines 941-944, the security section now states: "Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set OTEL_LOG_RAW_API_BODIES. With =1, each API call emits api_request_body and api_response_body log events whose body attribute is the JSON-serialized payload, truncated at 60 KB. With =file:<dir>, untruncated bodies are written to .request.json and .response.json files under that directory... In both modes, bodies contain the full conversation history... Claude's extended-thinking content is always redacted from these bodies regardless of other settings".

Verdict: The page now documents truncation, file mode behavior, sensitivity of exported content, and redaction behavior.

---

Claim 4: The environment variables reference should include OTEL_LOG_RAW_API_BODIES

Status: RESOLVED

At https://code.claude.com/docs/en/env-vars, line 206, the environment variable table now includes: "OTEL_LOG_RAW_API_BODIES" with the description: "Emit Anthropic Messages API request and response JSON as api_request_body / api_response_body log events. Set to 1 for inline bodies truncated at 60 KB, or file:<dir> to write untruncated bodies to disk and emit a body_ref path instead. Disabled by default; bodies include the entire conversation history."

Verdict: The environment variable reference has been updated.

---

Claim 5: The Agent SDK observability page should stay aligned with the CLI monitoring docs

Status: RESOLVED

At https://code.claude.com/docs/en/agent-sdk/observability, lines 199-206, the "Control sensitive data in exports" table now includes: "OTEL_LOG_RAW_API_BODIES" and describes it as exporting "Full Anthropic Messages API request and response JSON as claude_code.api_request_body and claude_code.api_response_body log events" with inline and file modes, conversation-history scope, redaction of extended-thinking content, and the warning that enabling it implies consent to the other content-bearing variables.

Verdict: The Agent SDK page is now aligned with the monitoring documentation.

---

Current State

Claim	Status
Monitoring configuration table includes OTEL_LOG_RAW_API_BODIES	RESOLVED
Raw request/response body events are documented	RESOLVED
Security/privacy guidance for raw API bodies is documented	RESOLVED
Environment variables reference includes OTEL_LOG_RAW_API_BODIES	RESOLVED
Agent SDK observability page includes aligned guidance	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

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

• Lines 87-90: Configuration table includes OTEL_LOG_RAW_API_BODIES and describes inline versus file output modes.

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

• Lines 584-617: Dedicated claude_code.api_request_body and claude_code.api_response_body event sections document when raw bodies are emitted and which attributes they contain.

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

• Lines 941-944: Security/privacy section explains truncation, on-disk file mode, conversation-history scope, backend filtering considerations, and extended-thinking redaction.

• URL: https://code.claude.com/docs/en/env-vars

• Line 206: Environment variable reference includes OTEL_LOG_RAW_API_BODIES.

• URL: https://code.claude.com/docs/en/agent-sdk/observability

• Lines 199-206: Agent SDK observability page includes OTEL_LOG_RAW_API_BODIES in the sensitive-data controls table.

---

Conclusion & Recommendation

Primary Concern: The issue reported that Claude Code's OpenTelemetry docs did not document the OTEL_LOG_RAW_API_BODIES feature or its safety implications.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current documentation now covers the environment variable, the emitted raw-body events, the privacy and truncation behavior, and the corresponding references on the env-vars and Agent SDK pages.

---

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.