adaptationio/claude-code-telemetry-enable

Claude Code Telemetry Enable

Enable OpenTelemetry telemetry in Claude Code to send metrics, logs, and traces to your observability stack (local LGTM or Railway).

When to Use

• After deploying observability stack (observability-stack-setup)
• Need to enable Claude Code monitoring
• Want to configure telemetry for local or cloud backends
• Need to verify telemetry connectivity

What This Skill Does

Creates Claude Code environment configuration files that enable:

• Metrics: Token usage, costs, session counts, tool performance
• Logs: User prompts (full content), tool results, API requests/errors
• Traces: Session flows, tool execution spans, API call traces

Privacy Note: Configured for FULL LOGGING (no redactions) per your requirements.

Quick Start

For Local Stack

# After running observability-stack-setup
# Invoke this skill with:
enable-local

# Claude Code will now send telemetry to localhost:4317

For Railway Stack

# After deploying to Railway
# Invoke this skill with:
enable-railway --endpoint https://your-alloy.railway.app:443

# Claude Code will send telemetry to Railway

Operations

enable-local

Configure Claude Code for local LGTM stack.

Creates: ~/.config/claude-code/.env.telemetry

Configuration:

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Fast export (for development)
OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds
OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds

# FULL LOGGING (no privacy restrictions)
OTEL_LOG_USER_PROMPTS=1
OTEL_METRICS_INCLUDE_SESSION_ID=true
OTEL_METRICS_INCLUDE_VERSION=true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true

enable-railway

Configure Claude Code for Railway-hosted LGTM stack.

Parameters:

• --endpoint: Railway Alloy OTLP endpoint URL
• --token: (Optional) Railway authentication token

Example:

enable-railway \
  --endpoint https://your-alloy-abc123.railway.app:443 \
  --token your-railway-token

Creates: ~/.config/claude-code/.env.telemetry with Railway endpoint

enable-custom

Configure for custom OTLP endpoint (Grafana Cloud, DataDog, etc.).

Parameters:

• --endpoint: OTLP endpoint URL
• --protocol: grpc or http (default: grpc)
• --headers: Authentication headers (e.g., "Authorization=Bearer token")

Example:

enable-custom \
  --endpoint https://otlp.grafana.net:443 \
  --protocol grpc \
  --headers "Authorization=Basic base64encodedcreds"

verify

Test telemetry configuration and connectivity.

Checks:

1. Configuration file exists
2. Required environment variables set
3. OTLP endpoint reachable
4. Test telemetry successfully sent
5. Data visible in backend (Grafana/Loki/Prometheus/Tempo)

Output:

Telemetry Configuration Check:
✅ Config file: ~/.config/claude-code/.env.telemetry
✅ CLAUDE_CODE_ENABLE_TELEMETRY=1
✅ OTLP endpoint: localhost:4317
✅ Endpoint reachable
✅ Test span sent successfully
✅ Data visible in Grafana

Status: HEALTHY - Telemetry fully operational

disable

Turn off telemetry completely.

Actions:

1. Renames .env.telemetry to .env.telemetry.disabled
2. OR sets CLAUDE_CODE_ENABLE_TELEMETRY=0

Re-enable: Rename file back or use enable-local / enable-railway again

status

Show current telemetry configuration.

Output:

Telemetry Status:
  State: ENABLED
  Endpoint: http://localhost:4317
  Protocol: gRPC
  Privacy: FULL LOGGING (all data captured)
  Export Intervals: Metrics 10s, Logs 5s

  Captured Data:
    - User prompts (full content)
    - Tool executions (all tools)
    - API requests (tokens, cost, latency)
    - Session metadata (IDs, version, account)

Configuration Details

Environment Variables

Essential:

• CLAUDE_CODE_ENABLE_TELEMETRY: 1 to enable, 0 to disable
• OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL
• OTEL_EXPORTER_OTLP_PROTOCOL: grpc or http

Exporters:

• OTEL_METRICS_EXPORTER: otlp (send metrics via OTLP)
• OTEL_LOGS_EXPORTER: otlp (send logs via OTLP)

Export Intervals:

• OTEL_METRIC_EXPORT_INTERVAL: Milliseconds between metric exports (default: 60000)
• OTEL_LOGS_EXPORT_INTERVAL: Milliseconds between log exports (default: 5000)

Privacy Controls (configured for FULL logging):

• OTEL_LOG_USER_PROMPTS: 1 = log full prompt content, 0 = log length only
• OTEL_METRICS_INCLUDE_SESSION_ID: true = include session IDs in metrics
• OTEL_METRICS_INCLUDE_VERSION: true = include Claude Code version
• OTEL_METRICS_INCLUDE_ACCOUNT_UUID: true = include account identifier

Authentication (for cloud backends):

• OTEL_EXPORTER_OTLP_HEADERS: Headers for authentication (e.g., "Authorization=Bearer token")

What Gets Captured

Metrics (counters, gauges, histograms):

• claude_code.session.count - Session frequency
• claude_code.token.usage - Token consumption (input + output)
• claude_code.cost.usage - API costs in USD
• claude_code.code_edit_tool.decision - Accept/reject patterns
• claude_code.active_time.total - Engagement duration (seconds)
• claude_code.pull_request.count - PR creation count
• claude_code.commit.count - Git commit count

Log Events (structured JSON):

1. claude_code.user_prompt - User prompt submissions (full content)
2. claude_code.tool_result - Tool execution outcomes (tool name, status, duration)
3. claude_code.api_request - Claude API calls (model, tokens, cost, latency)
4. claude_code.api_error - Failed API requests (status codes, retry attempts)
5. claude_code.tool_decision - Permission decisions (approved/rejected)

Traces (distributed tracing):

• Session traces: Complete conversation workflows
• Tool call spans: Read, Write, Edit, Bash, Glob, Grep, Task, etc.
• Agent task spans: Parallel agent execution
• API request spans: Claude API latency breakdown

Retention

All data stored for 365 days (configured in observability stack).

File Locations

Configuration File:

• Linux/WSL: ~/.config/claude-code/.env.telemetry
• macOS: ~/.config/claude-code/.env.telemetry
• Windows: %USERPROFILE%\.config\claude-code\.env.telemetry

Managed Settings (organization-enforced, optional):

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

Troubleshooting

Telemetry Not Appearing in Grafana

Check 1: Is telemetry enabled?

cat ~/.config/claude-code/.env.telemetry
# Should show CLAUDE_CODE_ENABLE_TELEMETRY=1

Check 2: Is OTLP endpoint reachable?

curl -v http://localhost:4317
# Should connect (may get empty response, that's ok)

Check 3: Is observability stack running?

docker compose -f .observability/docker-compose.yml ps
# All 5 services should be "running"

Check 4: Use Claude Code and check immediately

# After using Claude Code, query Loki:
curl -s 'http://localhost:3100/loki/api/v1/query?query={job="claude_code"}' | jq .
# Should show recent logs

Port Already in Use (4317)

If another service is using port 4317:

Option 1: Stop the conflicting service

sudo lsof -i :4317
sudo kill <PID>

Option 2: Change Alloy port in observability stack Edit .observability/docker-compose.yml:

ports:
  - "4318:4317"  # Expose on 4318 instead

Then update telemetry config:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Permission Denied

If configuration file creation fails:

# Create directory manually
mkdir -p ~/.config/claude-code
chmod 755 ~/.config/claude-code

# Try again

Next Steps

After enabling telemetry:

1. Use Claude Code: Run tools (Read, Write, Bash, etc.)
2. Generate telemetry: Each operation sends data
3. View in Grafana: Open http://localhost:3000
4. Check dashboards: Navigate to "Claude Code Overview"
5. Verify metrics: See token usage, costs, tool calls

References

• references/env-telemetry-local.txt - Local configuration template
• references/env-telemetry-railway.txt - Railway configuration template
• references/env-telemetry-custom.txt - Custom endpoint template
• references/telemetry-variables.md - All environment variables explained
• references/privacy-settings.md - Privacy configuration options

Scripts

• scripts/enable-local.sh - Enable for local stack
• scripts/enable-railway.sh - Enable for Railway
• scripts/verify-telemetry.sh - Test configuration and connectivity
• scripts/disable-telemetry.sh - Turn off telemetry