Claude Code Integration - Fiddler Documentation

Overview

Claude Code is Anthropic’s CLI coding agent. It emits OpenTelemetry traces that Fiddler natively ingests and maps to the Fiddler schema, giving you observability over coding agent sessions — including user prompts, LLM calls, tool invocations, token usage, and permission decisions. No Fiddler SDK is required. Claude Code’s built-in OTel instrumentation sends traces directly to Fiddler’s OTLP ingestion endpoint.

Beta telemetry. Claude Code’s OpenTelemetry tracing requires the CLAUDE_CODE_ENHANCED_TELEMETRY_BETA flag and is subject to change between versions. Several content attributes (LLM responses, tool input/output) are not available in trace spans. See Known Limitations for full details.

Capability	Support
User prompt capture	✅ Requires `OTEL_LOG_USER_PROMPTS=1`
LLM response capture	❌ Not available in traces
Tool name tracking	✅ Always available
Tool input/output	❌ Not emitted in trace spans
Token counts	✅ Input, output, cache read, cache creation
Session correlation	✅ Via `session.id`
Permission decision tracking	✅ Accept/deny on tool invocations
Cost tracking	❌ Not emitted by Claude Code
Enrichment (Prompt Safety)	✅ Via Fiddler evaluator rules

Prerequisites

Claude Code v2.1.138 or later
A Fiddler application with a valid application.id

Quick Start

Step 1 — Enable Claude Code telemetry

Set the following environment variables before launching Claude Code:

# Required — enable OTel tracing (beta)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp

# Required — point at Fiddler's OTLP ingestion endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-fiddler-url>"
export OTEL_EXPORTER_OTLP_HEADERS="fiddler-application-id=<your-application-id>,Authorization=Bearer <your-api-key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

# Required — tag traces with your Fiddler application
export OTEL_RESOURCE_ATTRIBUTES="application.id=<your-application-id>"

# Recommended — enable content capture
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1

Step 2 — Launch Claude Code

claude

Use Claude Code normally. Every interaction generates OTel traces that flow to Fiddler.

Step 3 — Verify traces in Fiddler

Navigate to your application in the Fiddler UI. You should see traces appearing within 30 seconds, with:

Agent spans for each user interaction (prompt → reasoning → tool calls → response)
LLM spans for each model call (Sonnet, Haiku) with token counts and latency
Tool spans for each tool invocation (Bash, Read, Write, MCP tools, WebSearch)

Managed Deployment via Settings File

For enterprise or managed deployments, you can configure telemetry via Claude Code’s settings file instead of environment variables. This ensures consistent telemetry across all developers without requiring them to set env vars manually. Create or update .claude/settings.json (project-level) or ~/.claude/settings.json (user-level):

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://<your-fiddler-url>",
    "OTEL_EXPORTER_OTLP_HEADERS": "fiddler-application-id=<your-application-id>,Authorization=Bearer <your-api-key>",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_RESOURCE_ATTRIBUTES": "application.id=<your-application-id>",
    "OTEL_LOG_USER_PROMPTS": "1",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_LOG_TOOL_CONTENT": "1"
  }
}

Do not commit API keys to version control. The OTEL_EXPORTER_OTLP_HEADERS value contains your Fiddler API key. If using project-level .claude/settings.json, add it to .gitignore to prevent accidental exposure. For CI/CD or shared environments, prefer setting credentials via environment variables instead of the settings file.

Settings in .claude/settings.json (project-level) take precedence over environment variables. Settings in the user-level ~/.claude/settings.json apply to all projects unless overridden.

What Gets Captured

Span Hierarchy

Each user interaction produces a trace with the following span structure:

claude_code.interaction (agent — root span, one per user prompt)
├── claude_code.llm_request (llm — LLM API call, e.g., Sonnet or Haiku)
├── claude_code.llm_request (llm — parallel model call, e.g., Haiku for routing)
├── claude_code.tool (tool — tool invocation wrapper)
│   ├── claude_code.tool.blocked_on_user (chain — permission prompt wait)
│   └── claude_code.tool.execution (chain — actual tool execution)
├── claude_code.tool (tool — second tool invocation)
│   └── claude_code.tool.execution (chain)
└── claude_code.llm_request (llm — follow-up LLM call with tool results)

Span Type Mapping

Claude Code Span	Fiddler Span Type	Description
`claude_code.interaction`	`agent`	Root span for a user interaction. Contains the user prompt and interaction-level metadata.
`claude_code.llm_request`	`llm`	Individual LLM API call. Contains model name, token counts, latency, and success/error status.
`claude_code.tool`	`tool`	Tool invocation wrapper. Contains the tool name and total duration (including permission wait).
`claude_code.tool.blocked_on_user`	`chain`	Time spent waiting for the user to accept or deny a tool permission prompt. Contains the user’s decision.
`claude_code.tool.execution`	`chain`	Actual tool execution after permission is granted. Contains success status and execution duration.

Captured Attributes by Span Type

Agent Spans (`claude_code.interaction`)

Attribute	Fiddler Mapping	Requires Env Var	Description
`user_prompt`	`fiddler.contents.gen_ai.llm.input.user`	`OTEL_LOG_USER_PROMPTS=1`	The user’s prompt text. Shows `<REDACTED>` when env var is not set.
`user_prompt_length`	`fiddler.span.user.user_prompt_length`	No	Character count of the user prompt (always available, even when content is redacted).
`interaction.sequence`	`fiddler.span.user.interaction.sequence`	No	Sequence number within the session (1 for first interaction, 2 for second, etc.).
`interaction.duration_ms`	`fiddler.span.user.interaction.duration_ms`	No	Total duration of the interaction in milliseconds.
`session.id`	`fiddler.metadata.gen_ai.conversation.id`	No	Claude Code session UUID. Used for session correlation.

LLM Spans (`claude_code.llm_request`)

Attribute	Fiddler Mapping	Description
`input_tokens`	`fiddler.span.system.gen_ai.usage.input_tokens`	Number of input tokens (excluding cache).
`output_tokens`	`fiddler.span.system.gen_ai.usage.output_tokens`	Number of output tokens.
`cache_read_tokens`	`fiddler.span.user.cache_read_tokens`	Tokens read from Anthropic’s prompt cache.
`cache_creation_tokens`	`fiddler.span.user.cache_creation_tokens`	Tokens written to Anthropic’s prompt cache.
`model`	Passthrough	Model identifier (e.g., `claude-sonnet-4-5@20250929`).
`gen_ai.request.model`	Passthrough	Same as `model`, following OTel GenAI semantic conventions.
`gen_ai.system`	Passthrough	LLM provider (always `anthropic` for Claude Code).
`ttft_ms`	`fiddler.span.user.ttft_ms`	Time to first token in milliseconds.
`stop_reason`	`fiddler.span.user.stop_reason`	Why the LLM stopped: `end_turn`, `tool_use`, `max_tokens`.
`success`	`fiddler.span.user.success`	Whether the LLM call succeeded (`true`/`false`).
`error`	`fiddler.span.user.error`	Error message when `success` is `false`.
`attempt`	`fiddler.span.user.attempt`	Retry attempt number (1 for first try).
`llm_request.context`	`fiddler.span.user.llm_request.context`	Call context: `interaction` (top-level) or `tool` (nested in a tool span).

LLM response content is not available in traces. Claude Code emits LLM output via OTel log records, not trace span attributes. This mapper processes trace spans only. See Known Limitations.

Tool Spans (`claude_code.tool`)

Attribute	Fiddler Mapping	Description
`tool_name`	`fiddler.span.system.gen_ai.tool.name`	Tool identifier (e.g., `Bash`, `Read`, `Write`, `Edit`, `WebSearch`, `mcp__server__tool`).
`duration_ms`	`fiddler.span.user.duration_ms`	Total tool duration including permission wait.

Tool input/output content is not available in traces. Despite the OTEL_LOG_TOOL_CONTENT=1 env var, Claude Code does not currently emit tool.output span events on tool spans. See Known Limitations.

Permission Decision Spans (`claude_code.tool.blocked_on_user`)

Attribute	Fiddler Mapping	Description
`decision`	`fiddler.span.user.decision`	User’s permission decision: `accept` or `deny`.
`source`	`fiddler.span.user.source`	How the decision was made: `user_temporary`, `user_permanent`, `settings`.
`duration_ms`	`fiddler.span.user.duration_ms`	Time spent waiting for the user to respond.

Session Grouping

Claude Code assigns a session.id to each coding session. Fiddler maps this to gen_ai.conversation.id, enabling session-level grouping in the UI. All spans within a session share the same session.id, allowing you to:

View the full timeline of a coding session
Correlate LLM calls with tool invocations
Track interaction sequences within a session

When session.id is absent (rare), Fiddler falls back to using the OTel trace_id as the conversation ID.

Enrichment Setup

Fiddler can automatically score Claude Code user prompts using Prompt Safety (powered by the Centor Model for Safety) or other evaluators. To configure:

Navigate to your application in the Fiddler UI.
Create an evaluator rule with:
- Span type: agent
- Text field: user_prompt
- Evaluator: Prompt Safety (or any custom evaluator)
New claude_code.interaction spans will be scored automatically as they arrive.

Enrichment requires the user_prompt attribute to be populated. Set OTEL_LOG_USER_PROMPTS=1 to enable content capture. When disabled, user_prompt contains <REDACTED> and enrichment will score the redaction placeholder instead of the actual prompt.

Configuration Reference

Environment Variables

Required

Variable	Description
`CLAUDE_CODE_ENABLE_TELEMETRY`	Set to `1` to enable telemetry.
`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`	Set to `1` to enable OTel trace export (beta).
`OTEL_TRACES_EXPORTER`	Set to `otlp` to enable OTLP trace export.
`OTEL_EXPORTER_OTLP_ENDPOINT`	Fiddler’s OTLP ingestion endpoint base URL (e.g., `https://your-fiddler-instance.com`). The OTel SDK appends `/v1/traces` automatically.
`OTEL_EXPORTER_OTLP_HEADERS`	Must include `fiddler-application-id=<uuid>` and `Authorization=Bearer <api-key>`.
`OTEL_EXPORTER_OTLP_PROTOCOL`	Set to `http/protobuf`.
`OTEL_RESOURCE_ATTRIBUTES`	Must include `application.id=<uuid>` matching the header above.

Content Logging

Variable	Default	Description
`OTEL_LOG_USER_PROMPTS`	`0`	Set to `1` to include user prompt text in traces. When disabled, `user_prompt` shows `<REDACTED>`.
`OTEL_LOG_TOOL_DETAILS`	`0`	Set to `1` to include additional tool metadata (`file_path` for Read/Edit/Write, `full_command` for Bash).
`OTEL_LOG_TOOL_CONTENT`	`0`	Set to `1` to include tool input/output content. Currently not functioning as documented — see Known Limitations.

Optional

Variable	Default	Description
`OTEL_SERVICE_NAME`	`claude-code`	Override the service name. Must remain `claude-code` for Fiddler to detect and map the traces correctly.

Troubleshooting

Traces not appearing in Fiddler

Verify telemetry is enabled:

echo $CLAUDE_CODE_ENABLE_TELEMETRY        # should be 1
echo $CLAUDE_CODE_ENHANCED_TELEMETRY_BETA  # should be 1
echo $OTEL_TRACES_EXPORTER                 # should be otlp

Verify the OTLP endpoint, protocol, and headers are set:

echo $OTEL_EXPORTER_OTLP_ENDPOINT    # should be the base URL (no /v1/traces)
echo $OTEL_EXPORTER_OTLP_PROTOCOL    # should be http/protobuf
echo $OTEL_EXPORTER_OTLP_HEADERS     # should contain fiddler-application-id
echo $OTEL_RESOURCE_ATTRIBUTES       # should contain application.id

Verify application.id in OTEL_RESOURCE_ATTRIBUTES is a valid UUID for an existing Fiddler application. Spans with an invalid or missing application.id are dropped during ingestion.
Verify the endpoint URL is the base URL (the SDK appends /v1/traces automatically) and OTEL_EXPORTER_OTLP_PROTOCOL is set to http/protobuf.

User prompts showing as `<REDACTED>`

Set OTEL_LOG_USER_PROMPTS=1 in the environment before launching Claude Code. This is disabled by default for privacy.

Tool details missing from spans

Tool spans only include tool_name and duration_ms by default. Setting OTEL_LOG_TOOL_DETAILS=1 adds file_path (for Read/Edit/Write tools) and full_command (for Bash tools). However, tool input/output content is not currently available in trace spans — see Known Limitations.

Enrichment worker skipping spans

If you see warnings like Missing fiddler.span.system.gen_ai.agent.name in span.attributes, the Fiddler mapper automatically sets this to "claude-code" on all spans. Ensure you are running the latest version of the external OTel consumer that includes the Claude Code mapper.

Spans classified as `chain` instead of expected types

Only three span types have specific classifications: claude_code.interaction (agent), claude_code.llm_request (llm), and claude_code.tool (tool). All other spans — including tool.blocked_on_user and tool.execution — are classified as chain. This is expected behavior.

Known Claude Code Upstream Limitations

Claude Code’s OpenTelemetry tracing is currently in beta and has several limitations that affect what data is available in Fiddler. These are not Fiddler issues — they are limitations of Claude Code’s OTel instrumentation. Fiddler captures and maps every attribute that Claude Code emits.

LLM response content not available in traces

Claude Code does not emit LLM response text as a trace span attribute. Response content is only available via OTel log records (controlled by OTEL_LOGS_EXPORTER and OTEL_LOG_RAW_API_BODIES), not trace spans. Additionally, OTel log records are currently emitted without trace_id or span_id, making log-to-trace correlation impossible. Impact: Session views in Fiddler show user prompts (input) but not Claude’s responses (output). Evaluators that require both input and output (e.g., response faithfulness) cannot run on Claude Code traces.

Tool input/output not emitted in trace spans

Claude Code’s documentation states that OTEL_LOG_TOOL_CONTENT=1 records a tool.output span event with tool input and output bodies. In practice, tool spans have empty event arrays — the tool.output event is not emitted. Tool spans only carry tool_name and duration_ms. Impact: Cannot see what arguments were passed to tools or what they returned. This limits visibility into MCP tool interactions and debugging tool failures.

Tracing is beta and requires opt-in

Claude Code’s OTel tracing requires the CLAUDE_CODE_ENHANCED_TELEMETRY_BETA flag. The trace schema (span names, attribute names, hierarchy) may change between Claude Code versions without notice. Impact: Fiddler’s mapper may need updates when Claude Code’s trace schema changes. Pin Claude Code versions in managed deployments to avoid unexpected schema changes.

No distributed tracing to LLM providers

Claude Code does not send W3C traceparent headers when making LLM API calls. If Claude Code is routed through a proxy (e.g., LiteLLM), the proxy creates a new trace root rather than continuing Claude Code’s trace. Claude Code traces and proxy traces are separate trace trees. Claude Code does propagate TRACEPARENT to Bash subprocesses (e.g., when running shell commands), enabling trace correlation for subprocess-initiated LLM calls in non-interactive mode. Impact: End-to-end distributed traces (user → coding agent → LLM proxy → LLM provider) require joining on session.id or x-claude-code-session-id at query time rather than native trace propagation.

Content redaction is all-or-nothing per category

Content capture is controlled by three separate env vars (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT). Each controls an entire category — there is no per-attribute or per-tool-type granularity. You cannot, for example, capture user prompts while keeping tool content redacted within a single category.

Thinking and reasoning content not available

There is no env var to export Claude’s extended thinking or reasoning steps in OTel telemetry. Only metadata (token counts, model, latency) is available for the reasoning process, not the content.

ScopeName and ScopeVersion empty in collected traces

Despite using instrumentation scope com.anthropic.claude_code.tracing 1.0.0, traces may show empty ScopeName and ScopeVersion fields. This does not affect span routing or processing — service.name and span name prefixes are used for detection.

Summary

Limitation	Severity	Description
No LLM response in traces	High	Output content available only via OTel log records (with broken trace correlation).
No tool input/output	High	`OTEL_LOG_TOOL_CONTENT=1` does not emit `tool.output` span events as documented.
Beta tracing	Medium	Schema may change between versions. Requires `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`.
No traceparent to LLM providers	Medium	Separate trace trees for agent and proxy. Join on session ID.
All-or-nothing redaction	Low	Cannot selectively control content capture per attribute.
No thinking content	Medium	Reasoning steps not available in any telemetry signal.
Empty ScopeName/ScopeVersion	Low	Does not affect functionality.

OpenTelemetry Integration — Manual OTel instrumentation for custom frameworks
LiteLLM Integration — Unified LLM gateway with Fiddler observability
Strands Agents SDK — Native monitoring for Strands agent applications
AgentGateway Integration — Cisco AgentGateway observability
Fiddler OTel SDK — Foundation package for custom OTel instrumentation

​Overview

​Prerequisites

​Quick Start

​Step 1 — Enable Claude Code telemetry

​Step 2 — Launch Claude Code

​Step 3 — Verify traces in Fiddler

​Managed Deployment via Settings File

​What Gets Captured

​Span Hierarchy

​Span Type Mapping

​Captured Attributes by Span Type

​Agent Spans (claude_code.interaction)

​LLM Spans (claude_code.llm_request)

​Tool Spans (claude_code.tool)

​Permission Decision Spans (claude_code.tool.blocked_on_user)

​Session Grouping

​Enrichment Setup

​Configuration Reference

​Environment Variables

​Required

​Content Logging

​Optional

​Troubleshooting

​Traces not appearing in Fiddler

​User prompts showing as <REDACTED>

​Tool details missing from spans

​Enrichment worker skipping spans

​Spans classified as chain instead of expected types

​Known Claude Code Upstream Limitations

​LLM response content not available in traces

​Tool input/output not emitted in trace spans

​Tracing is beta and requires opt-in

​No distributed tracing to LLM providers

​Content redaction is all-or-nothing per category

​Thinking and reasoning content not available

​ScopeName and ScopeVersion empty in collected traces

​Summary

​Related Documentation

Overview

Prerequisites

Quick Start

Step 1 — Enable Claude Code telemetry

Step 2 — Launch Claude Code

Step 3 — Verify traces in Fiddler

Managed Deployment via Settings File

What Gets Captured

Span Hierarchy

Span Type Mapping

Captured Attributes by Span Type

Agent Spans (`claude_code.interaction`)

LLM Spans (`claude_code.llm_request`)

Tool Spans (`claude_code.tool`)

Permission Decision Spans (`claude_code.tool.blocked_on_user`)

Session Grouping

Enrichment Setup

Configuration Reference

Environment Variables

Required

Content Logging

Optional

Troubleshooting

Traces not appearing in Fiddler

User prompts showing as `<REDACTED>`

Tool details missing from spans

Enrichment worker skipping spans

Spans classified as `chain` instead of expected types

Known Claude Code Upstream Limitations

LLM response content not available in traces

Tool input/output not emitted in trace spans

Tracing is beta and requires opt-in

No distributed tracing to LLM providers

Content redaction is all-or-nothing per category

Thinking and reasoning content not available

ScopeName and ScopeVersion empty in collected traces

Summary

Related Documentation