Administration

Claude Code Administration

Monitoring Overview

Claude Code supports OpenTelemetry (OTel) for metrics and events. The system exports time series data via standard metrics protocol and events through logs/events protocol.

Quick Setup

Enable telemetry:

export CLAUDE_CODE_ENABLE_TELEMETRY=1

Configure exporters (optional, pick what you need):

# Metrics
export OTEL_METRICS_EXPORTER=otlp  # Options: otlp, prometheus, console

# Logs
export OTEL_LOGS_EXPORTER=otlp     # Options: otlp, console

Export Intervals

Default intervals:

• Metrics: 60 seconds
• Logs: 5 seconds

Customize intervals:

export OTEL_METRIC_EXPORT_INTERVAL=30000  # milliseconds
export OTEL_LOGS_EXPORT_INTERVAL=10000    # milliseconds

Available Metrics

Claude Code tracks eight core metrics:

1. Session Counter

CLI sessions started

Use for: Tracking adoption and active users

2. Lines of Code

Code additions/removals tracked by type

Use for: Measuring productivity and code generation volume

3. Pull Requests

Creation count

Use for: Tracking automated PR generation

4. Commits

Git commits via Claude Code

Use for: Measuring development activity

5. Cost Usage

Session costs in USD (model-segmented)

Use for: Budget tracking and cost allocation

Important: Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).

6. Token Usage

Tokens consumed (input/output/cache types)

Use for: Understanding API usage patterns and optimizing costs

7. Code Edit Tool Decisions

Accept/reject counts per tool

Use for: Understanding user trust and automation acceptance

8. Active Time

Actual usage duration in seconds

Use for: Measuring engagement and productivity time

Metric Segmentation

Segment metrics by:

• user.account_uuid - Individual user tracking
• organization.id - Team/organization grouping
• session.id - Session-specific analysis
• model - Model usage breakdown
• app.version - Version tracking

Events & Logging

Five event types are exported:

1. User Prompt Events

Prompt submissions (content redacted by default)

Enable prompt logging:

export OTEL_LOG_USER_PROMPTS=1

Use for: Understanding user interaction patterns

2. Tool Result Events

Tool execution completion with success status and duration

Use for: Monitoring tool performance and reliability

3. API Request Events

Claude API calls with cost and token data

Use for: Detailed cost analysis and API usage tracking

4. API Error Events

Failed requests with HTTP status codes

Use for: Troubleshooting and reliability monitoring

5. Tool Decision Events

User accept/reject actions with decision source

Use for: Understanding automation trust and user preferences

Cost Monitoring

Cost Tracking Setup

Monitor costs by model and user:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

Cost Analysis

View costs segmented by:

• Model (Sonnet vs Haiku)
• User/account
• Session
• Time period

Budget Alerts

Implement budget monitoring:

1. Export cost metrics to your monitoring system
2. Set up alerts for cost thresholds
3. Review high-cost sessions
4. Optimize model selection and usage patterns

Analytics & ROI

ROI Measurement Guide

Reference the Claude Code ROI Measurement Guide for:

• Docker configurations
• Productivity report templates
• ROI calculation methods
• Team analytics dashboards

Key Metrics for ROI

Productivity Metrics:

• Lines of code generated per hour
• Time saved vs manual coding
• PRs created automatically
• Issues resolved automatically

Quality Metrics:

• Code review findings
• Test coverage improvements
• Bug reduction rate
• Technical debt reduction

Adoption Metrics:

• Active users
• Session frequency
• Feature usage patterns
• User satisfaction scores

Monitoring Backend Setup

Prometheus Setup

# prometheus.yml
scrape_configs:
  - job_name: 'claude-code'
    static_configs:
      - targets: ['localhost:9464']

Start with Prometheus exporter:

export OTEL_METRICS_EXPORTER=prometheus
claude

Grafana Dashboard

Create dashboards to visualize:

• Cost over time
• Token usage trends
• Session counts
• User activity
• Tool acceptance rates

Custom Analytics

Export to your own backend:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend.com
export OTEL_EXPORTER_OTLP_HEADERS="api-key=your-key"

Best Practices

1. Enable Monitoring Early

Set up telemetry from day one to establish baselines

2. Segment by Team/Project

Use organization and user IDs for proper attribution

3. Monitor Costs Regularly

Review cost metrics weekly to identify trends

4. Track Adoption

Monitor active users and session frequency

5. Measure Quality Impact

Track bug rates and code review findings

6. Set Alert Thresholds

Configure alerts for:

• Unusual cost spikes
• Error rate increases
• Low adoption indicators

7. Review Metrics with Teams

Share analytics to demonstrate value and identify improvements

8. Optimize Based on Data

Use metrics to:

• Identify high-value use cases
• Optimize model selection
• Improve automation acceptance
• Reduce costs

Privacy Considerations

User Prompts:

• Disabled by default
• Enable only with user consent: OTEL_LOG_USER_PROMPTS=1
• Consider data retention policies

Sensitive Data:

• Avoid logging sensitive information
• Implement data filtering
• Review compliance requirements

Access Control:

• Restrict metrics access appropriately
• Use secure connections for exporters
• Encrypt data in transit and at rest

Troubleshooting Monitoring

Metrics Not Appearing

1. Verify telemetry is enabled: CLAUDE_CODE_ENABLE_TELEMETRY=1
2. Check exporter configuration
3. Verify backend connectivity
4. Review export intervals
5. Check for error logs

High Costs

1. Review token usage by model
2. Identify high-usage sessions
3. Check for inefficient prompts
4. Consider using Haiku for simple tasks
5. Implement cost controls

Low Adoption

1. Review active user metrics
2. Identify barriers to usage
3. Provide training and documentation
4. Gather user feedback
5. Highlight success stories

Example Monitoring Stack

# docker-compose.yml for full monitoring stack
version: '3.8'
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Configure Claude Code:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus
export OTEL_EXPORTER_PROMETHEUS_PORT=9464