Claude Code Integration Guide

Claude Code supports OpenTelemetry (OTel) traces for monitoring and observability. This guide shows you how to configure Claude Code to send that trace data to LangWatch, so you can see usage patterns and performance.

OpenTelemetry support in Claude Code is currently in beta and details are subject to change.

Prerequisites

Obtain your LANGWATCH_API_KEY from the LangWatch dashboard
Claude Code installed on your system
Access to configure environment variables or managed settings

Quick Start

Configure Claude Code to send telemetry to LangWatch using environment variables:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1
export OTEL_LOG_RAW_API_BODIES=1
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-langwatch-api-key"
claude

CLAUDE_CODE_ENHANCED_TELEMETRY_BETA is an experimental Claude Code flag, and it is the one that turns spans on. Without it OTEL_TRACES_EXPORTER does nothing and OTEL_LOG_TOOL_CONTENT has no span events to write to, so you get flat log records instead of a trace: no tool call tree, no latencies, and every subagent folded into the main session rather than branching off it.

The four OTEL_LOG_* flags are what put your session content in LangWatch: prompt text, tool input and output, and the model request and response bodies of every turn. Claude Code sends none of it without them. Read Security and Privacy before you run this somewhere the content matters.

Administrator Configuration

Administrators can configure OpenTelemetry settings for all users through the managed settings file. This allows for centralized control of telemetry settings across an organization. The managed settings file is located at:

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux and WSL: /etc/claude-code/managed-settings.json
Windows: C:\ProgramData\ClaudeCode\managed-settings.json

Example managed settings configuration for LangWatch:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOG_USER_PROMPTS": "1",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_LOG_TOOL_CONTENT": "1",
    "OTEL_LOG_RAW_API_BODIES": "1",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://app.langwatch.ai/api/otel",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-langwatch-api-key"
  }
}

Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and cannot be overridden by users.

LangWatch-Specific Configuration

Endpoint Configuration

LangWatch provides OpenTelemetry endpoints for traces:

# General OTLP endpoint (recommended)
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel

# Specific traces endpoint (if needed)
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://app.langwatch.ai/api/otel/v1/traces

Protocol Selection

LangWatch supports multiple OTLP protocols. For Claude Code integration, we recommend:

# HTTP/JSON (recommended for Claude Code)
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Alternative: gRPC (if you prefer binary protocol)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Authentication

Set your LangWatch API key for authentication:

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-langwatch-api-key"

Never commit API keys to version control. Use environment variables or managed settings for secure configuration.

Available Trace Data

Claude Code exports its trace data over OTLP to the LangWatch endpoint you configured above.

Standard Attributes

All traces share these standard attributes:

Attribute	Description	Controlled By
`session.id`	Unique session identifier	`OTEL_METRICS_INCLUDE_SESSION_ID` (default: true)
`app.version`	Current Claude Code version	`OTEL_METRICS_INCLUDE_VERSION` (default: false)
`organization.id`	Organization UUID (when authenticated)	Always included when available
`user.account_uuid`	Account UUID (when authenticated)	`OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (default: true)
`terminal.type`	Terminal type (e.g., `iTerm.app`, `vscode`, `cursor`, `tmux`)	Always included when detected

Key Trace Information

Claude Code traces include:

Session tracking: CLI session lifecycle and duration
Code generation: Lines of code added/removed, file operations
Tool usage: Edit, MultiEdit, Write, and NotebookEdit tool decisions
API interactions: Claude API requests, responses, and performance
User interactions: Prompt submissions and tool acceptances/rejections

Configuration Examples

Basic LangWatch Integration

# Enable telemetry and send to LangWatch
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1
export OTEL_LOG_RAW_API_BODIES=1
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-api-key"

Advanced Configuration with Custom Attributes

# Basic telemetry setup
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1
export OTEL_LOG_RAW_API_BODIES=1

# LangWatch endpoint configuration
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-api-key"

# Custom resource attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform"

Debug Configuration

# Debug configuration with console output and LangWatch
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=console,otlp
export OTEL_LOGS_EXPORTER=console,otlp
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_LOG_USER_PROMPTS=1
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-api-key"

Multi-Team Organization Support

Organizations with multiple teams can add custom attributes to distinguish between different groups:

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,project=langwatch-integration"

These custom attributes will be included in all traces sent to LangWatch, allowing you to:

Filter traces by team or department
Track usage per department
Create team-specific dashboards
Set up alerts for specific teams

Important formatting requirements for OTEL_RESOURCE_ATTRIBUTES:The OTEL_RESOURCE_ATTRIBUTES environment variable follows the W3C Baggage specification, which has strict formatting requirements:

No spaces allowed: Values cannot contain spaces. For example, user.organizationName=My Company is invalid
Format: Must be comma-separated key=value pairs: key1=value1,key2=value2
Allowed characters: Only US-ASCII characters excluding control characters, whitespace, double quotes, commas, semicolons, and backslashes
Special characters: Characters outside the allowed range must be percent-encoded

Examples:

# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Dynamic Headers for Enterprise

For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

Settings Configuration

Add to your .claude/settings.json:

{
  "otelHeadersHelper": "/bin/generate_langwatch_headers.sh"
}

Script Requirements

The script must output valid JSON with string key-value pairs representing HTTP headers:

#!/bin/bash
# Example: Generate LangWatch headers dynamically
echo "{\"Authorization\": \"Bearer $(get-langwatch-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Headers are fetched only at startup, not during runtime. This is due to OpenTelemetry exporter architecture limitations.For scenarios requiring frequent token refresh, use an OpenTelemetry Collector as a proxy that can refresh its own headers.

Verification and Testing

1. Check the shell overrides

After setting up your configuration, verify that Claude Code is sending data to LangWatch:

# Shell override for telemetry
echo $CLAUDE_CODE_ENABLE_TELEMETRY

# Shell override for span tracing
echo $CLAUDE_CODE_ENHANCED_TELEMETRY_BETA

# Shell override for the endpoint
echo $OTEL_EXPORTER_OTLP_ENDPOINT

# Shell override for the authentication headers
echo $OTEL_EXPORTER_OTLP_HEADERS

These read your shell and nothing else. Claude Code also takes the same variables from the env block of a settings file, so an empty line here does not mean the setting is missing: check .claude/settings.json, .claude/settings.local.json, and your managed settings file too. The one check that covers every source is whether traces arrive in LangWatch, which is the next step.

2. Test Data Flow

Start Claude Code with your configuration
Make some interactions (ask questions, edit code, use tools)
Check LangWatch dashboard for incoming traces
Verify data appears in the dashboard

Troubleshooting

No data appearing in LangWatch

Verify CLAUDE_CODE_ENABLE_TELEMETRY=1 is set
Verify OTEL_LOGS_EXPORTER=otlp is set. Claude Code 2.1.x ships its cost-bearing events as OTLP logs, not spans, so with only OTEL_TRACES_EXPORTER set you’ll see nothing in LangWatch
Check that the endpoint URL is correct: https://app.langwatch.ai/api/otel
Ensure your API key is valid and has proper permissions
Check network connectivity to the LangWatch endpoint
Verify the OTLP protocol is supported (http/json or grpc)

Trace lands but has no tool call tree, latencies, or subagents

Set CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1. It is the experimental flag that turns span tracing on, and OTEL_TRACES_EXPORTER is a no-op without it. Cost and token events still arrive over the logs exporter, so the session shows up, but with no spans LangWatch has no structure to hang them on: every subagent folds into the main session instead of branching off it. OTEL_LOG_TOOL_CONTENT also depends on this flag, because the tool input and output it enables are written as span events.

Trace shows but input/prompt is empty

Set OTEL_LOG_USER_PROMPTS=1. Claude Code redacts the prompt body on its user_prompt event by default. Without this env, the receiver has no input text to attach to the synthesized trace.

Trace shows but output/response is empty

Set OTEL_LOG_RAW_API_BODIES=1. Claude Code only emits the assistant’s response text on its api_response_body event, and that event is off by default. With the flag set, LangWatch lifts the full response text into the trace output alongside the cost and token breakdown.Claude Code also emits api_response_body for non-conversational utility calls (autosuggestions, session-title generation). LangWatch filters those by query_source so only genuine conversation turns populate the trace output, never a stray title or suggestion.

Authentication errors

Verify the Authorization header format: Bearer YOUR_API_KEY
Ensure the API key is valid and not expired
Check that the API key has the necessary permissions for trace ingestion
Verify the header is properly formatted in the environment variable

Large payloads or truncated content

OTEL_LOG_RAW_API_BODIES is the flag that carries the large payload: it ships the Messages API request and response JSON on every turn, so api_request_body / api_response_body events can reach tens of KB each. Claude Code truncates each inline body at 60 KB (raise the limit with CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH) and redacts extended thinking. LangWatch caps oversized log records on ingestion to protect the pipeline, keeping the lifted input and output text while trimming the rest. If you only need cost and token data, drop all four content flags. The other three send smaller records than the raw bodies do, but they are content too: OTEL_LOG_USER_PROMPTS sends the whole prompt, OTEL_LOG_TOOL_DETAILS sends what each tool call was asked to do (the Bash command text, the Edit diff, the path a Read opened), and OTEL_LOG_TOOL_CONTENT sends what the tool gave back, including the contents of files a tool read or wrote.

Configuration not taking effect

Restart Claude Code after changing environment variables
Check for conflicting settings in managed settings files
Verify environment variable precedence (managed settings override user settings)
Use claude --help to verify configuration is loaded

Best Practices

1. Start with Console Exporter for Debugging

# Begin with console output to verify telemetry is working
export OTEL_TRACES_EXPORTER=console,otlp

2. Implement Proper Error Handling

Monitor for export failures and implement retry logic if needed. LangWatch provides reliable endpoints, but network issues can occur.

3. Use Resource Attributes for Organization

# Add meaningful attributes for better data organization
export OTEL_RESOURCE_ATTRIBUTES="environment=production,region=us-west-2,team=platform"

Usage Insights

With LangWatch integration, you can gain insights into Claude Code usage:

Which of these you get depends on which flags are set, and nothing is exported at all without CLAUDE_CODE_ENABLE_TELEMETRY=1. With that alone you get the usage fields: token counts, cost, model and latency. The tool call tree, per-tool timings, session structure and subagent attribution need CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, which is what turns spans on. Prompt text, tool input and output, and the model request and response bodies each need their own content flag (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, OTEL_LOG_RAW_API_BODIES).

Productivity Tracking

Monitor code generation patterns
Track tool usage and acceptance rates
Analyze session duration and frequency

User Behavior Analysis

Understand how teams use Claude Code
Identify popular features and workflows
Monitor adoption across different teams

Next Steps

Set up your configuration using the examples above
Verify data flow to LangWatch
Explore the LangWatch dashboard to view your Claude Code traces
Create custom dashboards for your team’s specific needs
Set up alerts for unusual usage patterns

For comprehensive monitoring resources, see the Claude Code Monitoring Guide.

Security and Privacy

Telemetry is opt-in and requires explicit configuration
Prompts, tool input and output, and model request and response bodies are off by default - without the content flags (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, OTEL_LOG_RAW_API_BODIES) the export still carries usage: token counts, cost, latency, the tool call tree and subagent attribution. What it leaves out is the content itself
Once enabled, prompt text, tool outputs, and file contents passed to tools will appear in traces - enable the flags only where capturing that content is acceptable
Every example on this page enables the content flags, because that is what makes a trace worth reading. Trim them to the ones you want before rolling the configuration out to a team, and keep the same decision in mind for managed settings, which apply to everyone at once

All data sent to LangWatch is encrypted in transit and stored securely. Review LangWatch’s privacy policy and security practices for more details.

Overview

SDKs

Frameworks

Model Providers

Tools

No-Code Platforms

Direct Integrations

Claude Code Integration Guide

Prerequisites

Quick Start

Administrator Configuration

LangWatch-Specific Configuration

Endpoint Configuration

Protocol Selection

Authentication

Available Trace Data

Standard Attributes

Key Trace Information

Configuration Examples

Basic LangWatch Integration

Advanced Configuration with Custom Attributes

Debug Configuration

Multi-Team Organization Support

Dynamic Headers for Enterprise

Settings Configuration

Script Requirements

Verification and Testing

1. Check the shell overrides

2. Test Data Flow

Troubleshooting

Best Practices

1. Start with Console Exporter for Debugging

2. Implement Proper Error Handling

3. Use Resource Attributes for Organization

Usage Insights

Productivity Tracking

User Behavior Analysis

Next Steps

Security and Privacy

​Prerequisites

​Quick Start

​Administrator Configuration

​LangWatch-Specific Configuration

​Endpoint Configuration

​Protocol Selection

​Authentication

​Available Trace Data

​Standard Attributes

​Key Trace Information

​Configuration Examples

​Basic LangWatch Integration

​Advanced Configuration with Custom Attributes

​Debug Configuration

​Multi-Team Organization Support

​Dynamic Headers for Enterprise

​Settings Configuration

​Script Requirements

​Verification and Testing

​1. Check the shell overrides

​2. Test Data Flow

​Troubleshooting

​Best Practices

​1. Start with Console Exporter for Debugging

​2. Implement Proper Error Handling

​3. Use Resource Attributes for Organization

​Usage Insights

​Productivity Tracking

​User Behavior Analysis

​Next Steps

​Security and Privacy

Prerequisites

Quick Start

Administrator Configuration

LangWatch-Specific Configuration

Endpoint Configuration

Protocol Selection

Authentication

Available Trace Data

Standard Attributes

Key Trace Information

Configuration Examples

Basic LangWatch Integration

Advanced Configuration with Custom Attributes

Debug Configuration

Multi-Team Organization Support

Dynamic Headers for Enterprise

Settings Configuration

Script Requirements

Verification and Testing

1. Check the shell overrides

2. Test Data Flow

Troubleshooting

Best Practices

1. Start with Console Exporter for Debugging

2. Implement Proper Error Handling

3. Use Resource Attributes for Organization

Usage Insights

Productivity Tracking

User Behavior Analysis

Next Steps

Security and Privacy