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 traces to LangWatch using environment variables:

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Configure OTLP exporter for traces
export OTEL_TRACES_EXPORTER=otlp

# 3. Set OTLP protocol and endpoint
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://app.langwatch.ai/api/otel

# 4. Set authentication headers
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-langwatch-api-key"

# 5. Run Claude Code
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_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 traces to LangWatch
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_TRACES_EXPORTER=otlp
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

# 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,cost_center=eng-123"

Debug Configuration

# Debug configuration with console output and LangWatch
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_TRACES_EXPORTER=console,otlp
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,cost_center=eng-123,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 cost center
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
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)

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

Performance issues

Consider using batch span processors for high-volume applications
Implement sampling to reduce the number of traces sent
Use async span processors to avoid blocking your application
Adjust export intervals based on your monitoring needs

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
Sensitive information like API keys or file contents are never included in traces
User prompt content is redacted by default - only prompt length is recorded

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

Overview

SDKs

Frameworks

Model Providers

Tools

No-Code Platforms

Direct Integrations

​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