otel-monitoring-setup

# Claude Code OpenTelemetry Setup

Automated workflow for setting up OpenTelemetry telemetry collection for Claude Code usage monitoring, cost tracking, and productivity analytics.

## Quick Decision Matrix

| User Request | Mode | Action |
|--------------|------|--------|
| "Set up telemetry locally" | Mode 1 | Full PoC stack |
| "I want to try OpenTelemetry" | Mode 1 | Full PoC stack |
| "Connect to company endpoint" | Mode 2 | Enterprise config |
| "Set up for team rollout" | Mode 2 | Enterprise + docs |
| "Dashboard not working" | Troubleshoot | See known issues |

## Mode 1: Local PoC Setup

**Goal**: Complete local telemetry stack for individual developer

**Creates**:
- OpenTelemetry Collector (receives data)
- Prometheus (stores metrics)
- Loki (stores logs)
- Grafana (dashboards)

**Prerequisites**:
- Docker Desktop running
- 2GB free disk space
- Write access to ~/.claude/

**Time**: 5-7 minutes

**Workflow**: `modes/mode1-poc-setup.md`

**Output**:
- Grafana at http://localhost:3000 (admin/admin)
- Management scripts in ~/.claude/telemetry/

## Mode 2: Enterprise Setup

**Goal**: Connect Claude Code to centralized company infrastructure

**Required Info**:
- OTEL Collector endpoint URL
- Authentication (API key or certificates)
- Team/department identifier

**Time**: 2-3 minutes

**Workflow**: `modes/mode2-enterprise.md`

**Output**:
- settings.json configured for central endpoint
- Team rollout documentation

## Critical Configuration

**REQUIRED in settings.json** (without these, telemetry won't work):

```json
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
  }
}
```

**Must restart Claude Code after settings changes!**

## Pre-Flight Check

Always run before setup:

```bash
# Verify Docker is running
docker info > /dev/null 2>&1 || echo "Start Docker Desktop first"

# Check available ports
for port in 3000 4317 4318 8