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 trace data to LangWatch, giving you insights into 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 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

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",
    "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 comprehensive trace data that integrates seamlessly with LangWatch’s observability platform.

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 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 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 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. Verify Configuration

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

# Check if telemetry is enabled
echo $CLAUDE_CODE_ENABLE_TELEMETRY

# Verify endpoint configuration
echo $OTEL_EXPORTER_OTLP_ENDPOINT

# Check authentication headers
echo $OTEL_EXPORTER_OTLP_HEADERS

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. 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 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

The content flags ship the full request and response JSON on every turn, so api_request_body / api_response_body events can reach tens of KB each. 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 OTEL_LOG_RAW_API_BODIES and OTEL_LOG_TOOL_DETAILS to keep payloads small. The other flags (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_CONTENT) are lightweight.

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:

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 I/O, and full request/response bodies are off by default - only token counts and cost ship until you opt in with the content flags (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, OTEL_LOG_RAW_API_BODIES)
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

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

​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. Verify Configuration

​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. Verify Configuration

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