### OpenTelemetry Example Configurations for Telemetry Export

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

This section provides practical `bash` examples demonstrating various OpenTelemetry configurations. It includes setups for console debugging, OTLP/gRPC export, Prometheus integration, using multiple exporters, configuring separate endpoints for metrics and logs, and setting up metrics-only telemetry.

```bash
# Console debugging (1-second intervals)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# Metrics only (no events/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```

--------------------------------

### Quick Start: Manage Observability Stack Services

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Commands to quickly start and check the status of all services in the observability stack using convenient 'make' commands, simplifying deployment and management.

```bash
# Start all services
make up

# Check status
make status
```

--------------------------------

### Start Development Stack Command

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

Command to initialize and start all services of the Claude Code Observability Stack, including Docker containers for Prometheus and Grafana, facilitating a ready-to-use development environment.

```bash
make up
```

--------------------------------

### Manage Claude Code Observability Stack

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Provides `make` commands for starting, stopping, restarting, and cleaning the observability services, along with commands for viewing logs, checking service status, and validating configurations.

```bash
# Stack management
make up                    # Start all services
make down                  # Stop all services  
make restart              # Restart services
make clean                # Clean up containers and volumes

# Monitoring
make logs                 # View all logs
make logs-collector       # View collector logs only
make status              # Show service status

# Validation
make validate-config     # Validate all configs
make setup-claude       # Show Claude Code setup instructions
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

Illustrative examples of standard commit messages following conventional commit guidelines, used for clear and descriptive version control history and automated release notes generation.

```text
feat: add API request count panel to cost analysis
fix: correct token usage query in performance dashboard
docs: update setup instructions for macOS
refactor: optimize Prometheus queries for better performance
```

--------------------------------

### Clone Claude Code Observability Repository

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

Provides Git commands to clone the Claude Code Observability Stack repository, including both a user's forked version and the original repository, enabling local development setup.

```bash
git clone https://github.com/your-username/claude-code-otel.git
```

```bash
git clone https://github.com/ColeMurray/claude-code-otel.git
```

--------------------------------

### Quick Start: Configure Claude Code for Telemetry Export

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Environment variables required to enable and configure OpenTelemetry exporters within Claude Code, directing metrics and logs to the local OpenTelemetry Collector endpoint. Includes options for faster export intervals for debugging.

```bash
# Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Configure exporters
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# For debugging (faster export intervals)
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

# Run Claude Code
claude
```

--------------------------------

### Configure OpenTelemetry Environment Variables for Claude Code

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

This snippet provides a quick guide to enable and configure OpenTelemetry for Claude Code using environment variables. It covers enabling telemetry, selecting exporters (OTLP, Prometheus, Console), setting OTLP endpoints and protocols, adding authentication headers, and adjusting export intervals for debugging purposes.

```bash
# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude
```

--------------------------------

### Validate Observability Stack Configurations and Health

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

Commands for validating the overall configuration of the observability stack and checking the health status of individual components like Docker Compose, Prometheus, and Grafana, ensuring proper setup before submission.

```bash
# Validate all configurations
make validate-config

# Test individual components
docker compose config  # Validate docker-compose.yml
curl -f http://localhost:9090/-/healthy  # Test Prometheus
curl -f http://localhost:3000/api/health  # Test Grafana
```

--------------------------------

### Observability Backend Recommendations

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Outlines the recommended backend systems for storing and analyzing observability data, specifying Prometheus for metrics, Loki for logs, and emphasizing cardinality management and retention policies.

```APIDOC
Backend Considerations:
  Metrics Backend: Prometheus (time series) + optional columnar stores
  Events Backend: Loki (log aggregation) with JSON parsing
  Cardinality Management: Configurable attribute inclusion
  Retention: Configure based on your analysis needs
```

--------------------------------

### Project File Structure Overview

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

A visual representation of the key files and directories within the Claude Code Observability Stack, indicating the purpose of each configuration or dashboard file for quick navigation and understanding.

```text
├── claude-code-dashboard.json    # Main Grafana dashboard
├── collector-config.yaml         # OpenTelemetry collector config
├── docker-compose.yml           # Main stack configuration
├── prometheus.yml               # Prometheus configuration
├── grafana-*.yml               # Grafana configuration files
├── Makefile                    # Management commands
└── README.md                   # Project documentation
```

--------------------------------

### Observability Stack Architecture Overview

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Illustrates the data flow and components of the Claude Code observability stack, detailing how data moves from Claude Code through OpenTelemetry Collector to Prometheus and Loki, finally visualized in Grafana.

```text
Claude Code → OpenTelemetry Collector → Prometheus (metrics) + Loki (events/logs)
                                     ↓
                              Grafana (visualization & analysis)
```

--------------------------------

### Configure OpenTelemetry via Managed Settings File for Claude Code

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

This JSON snippet demonstrates how administrators can centrally configure OpenTelemetry settings for Claude Code using a managed settings file. It includes enabling telemetry, specifying OTLP exporters for metrics and logs, defining the OTLP endpoint, and setting authentication headers. These settings have high precedence and cannot be overridden by users.

```json
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}
```

--------------------------------

### Configure Claude Code Telemetry Environment Variables

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Details key environment variables for enabling telemetry, configuring exporters (OTLP, Prometheus), setting protocol and endpoints, defining export intervals, and controlling privacy/cardinality for Claude Code observability.

```bash
# Core telemetry
CLAUDE_CODE_ENABLE_TELEMETRY=1

# Exporter configuration
OTEL_METRICS_EXPORTER=otlp,prometheus    # Multiple exporters
OTEL_LOGS_EXPORTER=otlp

# Protocol and endpoints
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token"

# Export intervals
OTEL_METRIC_EXPORT_INTERVAL=60000        # 1 minute (production)
OTEL_LOGS_EXPORT_INTERVAL=5000           # 5 seconds

# Privacy controls
OTEL_LOG_USER_PROMPTS=1                   # Enable prompt content logging

# Cardinality control
OTEL_METRICS_INCLUDE_SESSION_ID=true
OTEL_METRICS_INCLUDE_VERSION=false
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true
```

--------------------------------

### API Documentation: Claude Code Observability Metrics and Events

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Detailed list of core metrics and event data collected by the Claude Code observability stack, providing insights into session activity, code changes, costs, token usage, and tool decisions, as well as user prompts, tool results, and API interactions.

```APIDOC
Core Metrics:
- claude_code.session.count: CLI sessions started
- claude_code.lines_of_code.count: Lines of code modified (added/removed)
- claude_code.pull_request.count: Pull requests created
- claude_code.commit.count: Git commits created
- claude_code.cost.usage: Cost of sessions by model
- claude_code.token.usage: Token usage (input/output/cache/creation)
- claude_code.code_edit_tool.decision: Tool permission decisions

Event Data:
- claude_code.user_prompt: User prompt submissions
- claude_code.tool_result: Tool execution results and timings
- claude_code.api_request: API requests with duration and tokens
- claude_code.api_error: API errors with status codes
- claude_code.tool_decision: Tool permission decisions
```

--------------------------------

### Pull Request Description Template

Source: https://github.com/colemurray/claude-code-otel/blob/main/CONTRIBUTING.md

Provides a structured template for contributors to use when submitting pull requests, ensuring consistent and comprehensive information regarding changes, type of change, testing performed, and optional screenshots.

```markdown
## Summary
Brief description of changes

## Type of Change
- [ ] Dashboard improvement
- [ ] Configuration enhancement
- [ ] Documentation update
- [ ] Bug fix
- [ ] New feature

## Testing
- [ ] Tested with actual Claude Code telemetry data
- [ ] Verified all dashboard panels work correctly
- [ ] Configuration validation passes
- [ ] Documentation is accurate

## Screenshots (if applicable)
Include screenshots of dashboard changes
```

--------------------------------

### OpenTelemetry Collector Configuration Overview

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Describes the high-level configuration aspects of the OpenTelemetry collector used in the observability stack, including processors, multiple pipelines for routing, and metric relabeling for cardinality control.

```APIDOC
OpenTelemetry Collector Configuration:
  Processors: Resource enrichment and event filtering
  Multiple Pipelines: Separate routing for metrics and different event types
  Metric Relabeling: Cardinality control for better performance
```

--------------------------------

### OpenTelemetry Common Configuration Environment Variables

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

This section details the environment variables available for configuring OpenTelemetry telemetry collection. It covers settings for enabling telemetry, specifying metrics and logs exporters, defining OTLP protocols and endpoints, and setting export intervals.

```APIDOC
Environment Variable | Description | Example Values
----------------------------------------------- | --------------------------------------------------------- | ------------------------------------
`CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1`
`OTEL_METRICS_EXPORTER` | Metrics exporter type(s) (comma-separated) | `console`, `otlp`, `prometheus`
`OTEL_LOGS_EXPORTER` | Logs/events exporter type(s) (comma-separated) | `console`, `otlp`
`OTEL_EXPORTER_OTLP_PROTOCOL` | Protocol for OTLP exporter (all signals) | `grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint (all signals) | `http://localhost:4317`
`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Protocol for metrics (overrides general) | `grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP metrics endpoint (overrides general) | `http://localhost:4318/v1/metrics`
`OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Protocol for logs (overrides general) | `grpc`, `http/json`, `http/protobuf`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP logs endpoint (overrides general) | `http://localhost:4318/v1/logs`
`OTEL_EXPORTER_OTLP_HEADERS` | Authentication headers for OTLP | `Authorization=Bearer token`
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` | Client key for mTLS authentication | Path to client key file
`OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` | Client certificate for mTLS authentication | Path to client cert file
`OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000`
`OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000`
`OTEL_LOG_USER_PROMPTS` | Enable logging of user prompt content (default: disabled) | `1` to enable
```

--------------------------------

### Claude Code OpenTelemetry Metrics Reference

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

Details the OpenTelemetry metrics exported by Claude Code, including their descriptions, units, and common attributes. Each metric's specific attributes and emission conditions are also documented.

```APIDOC
Common Attributes:
  session.id: Unique session identifier (controlled by OTEL_METRICS_INCLUDE_SESSION_ID)
  app.version: Current Claude Code version (controlled by OTEL_METRICS_INCLUDE_VERSION)
  organization.id: Organization UUID (when authenticated)
  user.account_uuid: Account UUID (when authenticated, controlled by OTEL_METRICS_INCLUDE_ACCOUNT_UUID)

Metrics:
  claude_code.session.count:
    Description: Count of CLI sessions started
    Unit: count
    Details: Emitted at the start of each session.
  claude_code.lines_of_code.count:
    Description: Count of lines of code modified
    Unit: count
    Details: Emitted when code is added or removed.
    Attributes:
      type: "added" or "removed"
  claude_code.pull_request.count:
    Description: Number of pull requests created
    Unit: count
    Details: Emitted when creating pull requests via Claude Code.
  claude_code.commit.count:
    Description: Number of git commits created
    Unit: count
    Details: Emitted when creating git commits via Claude Code.
  claude_code.cost.usage:
    Description: Cost of the Claude Code session
    Unit: USD
    Details: Emitted after each API request.
    Attributes:
      model: string
  claude_code.token.usage:
    Description: Number of tokens used
    Unit: tokens
    Details: Emitted after each API request.
    Attributes:
      type: "input", "output", "cacheRead", "cacheCreation"
      model: string
  claude_code.code_edit_tool.decision:
    Description: Count of code editing tool permission decisions
    Unit: count
    Details: Emitted when user accepts or rejects Edit, MultiEdit, Write, or NotebookEdit tool usage.
    Attributes:
      tool: "Edit", "MultiEdit", "Write", "NotebookEdit"
      decision: "accept", "reject"
```

--------------------------------

### Configure OpenTelemetry for Logs Export

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

Sets environment variables to enable OpenTelemetry logs export for Claude Code, directing logs to a local OTLP gRPC endpoint. This configuration ensures that only logs/events are exported, not metrics.

```shell
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```

--------------------------------

### OpenTelemetry Metrics Cardinality Control Variables

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

This section describes environment variables used to manage the cardinality of metrics by including or excluding specific attributes like session ID, application version, and account UUID. Controlling cardinality helps optimize storage requirements and query performance in metrics backends.

```APIDOC
Environment Variable | Description | Default Value | Example to Disable
----------------------------------- | ----------------------------------------------- | ------------- | ------------------
`OTEL_METRICS_INCLUDE_SESSION_ID` | Include session.id attribute in metrics | `true` | `false`
`OTEL_METRICS_INCLUDE_VERSION` | Include app.version attribute in metrics | `false` | `true`
`OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Include user.account_uuid attribute in metrics | `true` | `false`
```

--------------------------------

### Grafana Dashboard Metrics and Features

Source: https://github.com/colemurray/claude-code-otel/blob/main/README.md

Documents the key sections and metrics available in the Grafana dashboard for Claude Code observability, including cost analysis, API request tracking, token usage, tool performance, real-time monitoring, and error analysis, structured by dashboard section.

```APIDOC
Grafana Dashboard Metrics and Features:
  Real-time Dashboard Analysis:
    - Cost Analysis: Real-time cost tracking with model breakdowns
    - Request Monitoring: API request counts and patterns by model
    - Token Efficiency: Track token usage and cost-per-token metrics
    - Tool Performance: Success rates and execution time analysis
    - Session Analytics: User activity and productivity insights
  Key Metrics Available:
    - Total and per-model costs with trending
    - API request counts independent of cost variations
    - Token usage breakdown (input/output/cache/creation)
    - Tool usage patterns and success rates
    - Session activity and code productivity metrics
  Key Dashboard Features:
    Cost & Usage Analysis:
      - Cost by Model: Track spending across different Claude models
      - API Request Tracking: Monitor actual request counts by model version
      - Token Usage Breakdown: Detailed analysis by token type (input/output/cache)
    Tool Performance:
      - Usage Patterns: Most frequently used Claude Code tools
      - Success Rates: Tool execution success percentages
      - Performance Metrics: Average execution times and bottleneck identification
    Real-time Monitoring:
      - Live Metrics: 30-second refresh rate for current activity
      - Session Tracking: Active sessions and productivity metrics
      - Error Analysis: API errors and troubleshooting information
  Dashboard Sections:
    Overview:
      - Active sessions, cost, token usage, lines of code changed
    Cost & Usage Analysis:
      - Cost trends by model, token usage breakdown
      - NEW: API request count tracking by model version
      - Implements cost monitoring recommendations
    Tool Usage & Performance:
      - Tool frequency and success rates
      - Performance bottleneck identification
    Performance & Errors:
      - API latency by model, error rate tracking
      - Performance monitoring
    User Activity & Productivity:
      - Code changes, commits, pull requests
      - Productivity measurement insights
    Event Logs:
      - Real-time tool execution events and API errors
      - Structured log analysis for troubleshooting
```

--------------------------------

### Claude Code OpenTelemetry Events Reference

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

Documents the OpenTelemetry log events exported by Claude Code, including their names, descriptions, and specific attributes. These events provide detailed insights into user interactions and API calls, useful for monitoring and debugging.

```APIDOC
Events:
  claude_code.user_prompt:
    Description: Logged when a user submits a prompt
    Attributes:
      event.name: "user_prompt"
      event.timestamp: ISO 8601 timestamp
      prompt_length: Length of the prompt
      prompt: Prompt content (redacted by default, enable with OTEL_LOG_USER_PROMPTS=1)
  claude_code.tool_result:
    Description: Logged when a tool completes execution
    Attributes:
      event.name: "tool_result"
      event.timestamp: ISO 8601 timestamp
      name: Name of the tool
      success: "true" or "false"
      duration_ms: Execution time in milliseconds
      error: Error message (if failed)
  claude_code.api_request:
    Description: Logged for each API request to Claude
    Attributes:
      event.name: "api_request"
      event.timestamp: ISO 8601 timestamp
      model: string (e.g., "claude-3-5-sonnet-20241022")
      cost_usd: Estimated cost in USD
      duration_ms: Request duration in milliseconds
      input_tokens: Number of input tokens
      output_tokens: Number of output tokens
      cache_read_tokens: Number of tokens read from cache
      cache_creation_tokens: Number of tokens used for cache creation
  claude_code.api_error:
    Description: Logged when an API request to Claude fails
    Attributes:
      event.name: "api_error"
      event.timestamp: ISO 8601 timestamp
      model: string (e.g., "claude-3-5-sonnet-20241022")
      error: Error message
      status_code: HTTP status code (if applicable)
      duration_ms: Request duration in milliseconds
      attempt: Attempt number (for retried requests)
```

--------------------------------

### Claude Code Tool Decision Event Definition

Source: https://github.com/colemurray/claude-code-otel/blob/main/CLAUDE_OBSERVABILITY.md

Defines the structure and attributes of the `claude_code.tool_decision` event. This event is logged when a tool permission decision (accept or reject) is made within Claude Code, providing details on the tool, decision, and source.

```APIDOC
Event: claude_code.tool_decision
  Description: Logged when a tool permission decision is made (accept/reject)
  Attributes:
    event.name: "tool_decision"
    event.timestamp: ISO 8601 timestamp
    tool_name: Name of the tool (e.g., "Read", "Edit", "MultiEdit", "Write", "NotebookEdit", etc.)
    decision: Either "accept" or "reject"
    source: Decision source - "config", "user_permanent", "user_temporary", "user_abort", or "user_reject"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.