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:

Configuration file exists
Required environment variables set
OTLP endpoint reachable
Test telemetry successfully sent
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:

Renames .env.telemetry to .env.telemetry.disabled
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):

claude_code.user_prompt - User prompt submissions (full content)
claude_code.tool_result - Tool execution outcomes (tool name, status, duration)
claude_code.api_request - Claude API calls (model, tokens, cost, latency)
claude_code.api_error - Failed API requests (status codes, retry attempts)
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:

Use Claude Code: Run tools (Read, Write, Bash, etc.)
Generate telemetry: Each operation sends data
View in Grafana: Open http://localhost:3000
Check dashboards: Navigate to "Claude Code Overview"
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

claude-code-telemetry-enable