Click to rate this post!

[Total: 0 Average: 0]

Поки роблю LiteLLM (див. LiteLLM: AI Gateway для LLM – overview можливостей), то з’явилась ідея окрім сервісів типу нашого Backend API – помоніторити і Claude Code девелоперів. Чисто інтересу заради – аби побачити що там взагалі є і хто як використовує нашу Anthropic Organization, бо у багатьох там підписка за 200 баксів, яку оплачує проект (в мене дешманська за 20 😥 )

Насправді ця ідея в мене з’явилась давно, але зараз до неї повернувся, бо активно пиляю моніторинг AI, і коли почав робити LiteLLM – то згадав і про Claude Code.

Але моніторити Claude Code з LiteLLM рішення не дуже – бо у нас subscriptions, а LiteLLM вміє тільки в API – тому роутити Claude Code через нього просто для того, аби отримати метрики і трейси така собі затєя.

Втім, Claude Code має власний вбудований моніторинг – вміє слати і трейси, і метрики, і логи в OpenTelemetry форматі, а тому можна просто скористатись ним.

Головна проблема тут була в тому, як всіх девелоперів змусити налаштувати свої інстанси – але і тут знайшлось рішення.

Зміст

Claude Code Telemetry overview

Документація – Monitoring.

Отже, загальна ідея: включаємо телеметрію в Claude Code, отримуємо дані напряму в VictoriaMetrics/VictoriaTraces/VictoriaLogs, малюємо графіки в Grafana або навіть алерти в Slack через iLert (див. ilert: альтернатива Opsgenie – перше знайомство, Alertmanager, Slack).

Хоча в більшості гайдів, які читав все ж використовують OpenTelemetry Collector, який отримує дані від Claude Code і передає до бекендів – але стек OpenTelemetry у нас поки на паузі, ще не дійшли руки, тому роблю простіше – і шлю дані відразу до VictoriaMetrics.

Всі дані Claude Code передає в форматі OpenTelemetry – але всі сервіси VictoriaMetrics чудово з ним працюють без додаткових налаштувань.

Claude Code Telemetry Config

Всі налаштування задаються через змінні оточення, з цікавих додаткових параметрів:

OTEL_LOG_USER_PROMPTS: логувати промпти юзерів – цікаво, але не треба 🙂
OTEL_LOG_TOOL_DETAILS та OTEL_LOG_TOOL_CONTENT: записувати додаткові дані про використання Tools, Skills, MCP, etc
OTEL_LOG_RAW_API_BODIES: зберігати повний зміст API запитів та відповідей – можна глянути, що там відбувається “під капотом”

Пам’ятаємо про High cardinality (див. VictoriaMetrics: Churn Rate, High cardinality, метрики та IndexDB) – і Claude Code має можливість налаштувати те, які атрибути будуть додані до метрик і трейсів, див. Metrics cardinality control.

А зі змінною OTEL_RESOURCE_ATTRIBUTES можемо додати кастомні атрибути.

Ще можна глянути параметри для OTEL_METRIC_EXPORT_INTERVAL – як часто Claude Code буде відправляти дані, по дефолту він їх накопичує 60 секунд і потім шле пачкою.

Поїхали тестити.

Testing locally

Спочатку глянемо локально, як воно працює і що там цікавого є – а потім додамо до нашої організації і розкатаємо на всіх юзерів.

Collecting Claude Code Metrics до VictoriaMetrics

Документація – Metrics.

Почнемо з бази – метрики. Їх не так, щоб дуже багато – але є цікаві і корисні.

Включаємо телеметрію взагалі:

$ export CLAUDE_CODE_ENABLE_TELEMETRY=1

В OTEL_EXPORTER_OTLP_METRICS_ENDPOINT передаємо URL інстансу VictoriaMetrics з /opentelemetry/v1/metrics – див. OpenTelemetry Collector.

$ export OTEL_METRICS_EXPORTER=otlp
$ export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$ export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://vmsingle.monitoring.1-33.ops.example.co/opentelemetry/v1/metrics

Запускаємо в тому ж вікні термінала claude, і за пару хвилин маємо метрики.

Так як це OTel – то формат запиту буде {__name__="claude_code.token.usage"}:

З цікавих метрик тут:

claude_code.cost.usage: умовна вартість використання – умовна, бо у нас subscriptions, але Claude все одно рахує кількість токенів і знає, скільки б це коштувало при роботі напряму через API
claude_code.token.usage: власне, кількість токенів
claude_code.lines_of_code.count: скільки коду нагенерив Claude
claude_code.pull_request.count: скільки Pull Requests

Collecting Claude Code Traces до VictoriaTraces

Документація – Traces.

Поки в Beta, але працює нормально.

В тому ж вікні термінала додаємо змінні для активації відправки трейсів з адресою інстансу VictoriaTraces (див. VictoriaTraces: Tracing, Observability та OpenTelemetry:

$ export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
$ export OTEL_TRACES_EXPORTER=otlp
$ export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://vmtraces.monitoring.1-33.ops.example.co/insert/opentelemetry/v1/traces

Запускаємо claude, перевіряємо чи пішли трейси до VictoriaTraces – дивимось наявні service.name:

$ curl -s 'https://vmtraces.monitoring.1-33.ops.example.co/select/jaeger/api/services'
{"data":["claude-code","kraken-dev","kraken-prod","kraken-staging","morpheus-agent"],"errors": null,"limit": 0,"offset": 0,"total":5}

І тепер можемо глянути самі трейси по {resource_attr:service.name="claude-code"}:

Всі рутові спани – claude_code.interaction, всі основні дані будуть в claude_code.llm_request – див. Span attributes.

Collecting Claude Code Events до VictoriaLogs

Документація – Events.

Кожен Event – це окремий log record по кожній події в роботі Claude Code, наприклад:

user_prompt: юзер відправив промпт
api_request: пішов запит до моделі
tool_result: відпрацював інструмент (Edit/Bash/Read тощо)
tool_decision: юзер прийняв/відхилив запропоновану дію (permission)

Всі Events мають спільний атрибут prompt.id – тому можемо побачити весь процес виконання запиту.

Додаємо змінні, в ендпоінті вказуємо інстанс VictoriaLogs:

$ export OTEL_LOGS_EXPORTER=otlp
$ export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://vmlogs.monitoring.1-33.ops.example.co/insert/opentelemetry/v1/logs

Перезапускаємо claude, шукаємо логи по {service.name="claude-code"}:

Grafana dashboard

Є багато готових дашборд, наприклад Claude Code Metrics, Claude Code Metrics (Prometheus), Claude Code Metrics Dashboard або Claude Code Observability Dashboard.

Для мене і проекту цей моніторинг не такий важливий – тому не буду витрачати час на створення власної борди, як роблю зазвичай, а візьму щось готове і трохи поправлю під себе.

VictoriaMetrics та OpenTelemetry vs Prometheus naming

Єдиний момент з готовими дашбордами в тому, що вони використовують метрики в Prometheus-форматі, а так як в мене дані від Claude Code йдуть напряму до VictoriaMetrics – то і імена там будуть в OTel форматі.

Але можна додати опцію usePrometheusNaming – тоді VictoriaMetrics буде зберігати їх в звичайному форматі, див. Label sanitization.

Якщо деплоїться з Helm-чартом victoria-metrics-k8s-stack – додаємо до values:

...
  vmsingle:
    spec:
      extraArgs:
        opentelemetry.usePrometheusNaming: "true"
...

Тоді маємо метрики і лейблів у вигляді claude_code_token_usage_tokens замість claude_code.token.usage:

Claude Org Managed Settings

Головний стопор був – як всім девелоперам сказати, що треба оновити settings.json?

Але для Organizations є можливість все налаштувати централізовано – див. Configure server-managed settings.

Спершу зробимо локально – знов-таки перевірити, що працює, аби не ламати нічого людям – редагуємо свій ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://vmsingle.monitoring.1-33.ops.example.co/opentelemetry/v1/metrics",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "https://vmtraces.monitoring.1-33.ops.example.co/insert/opentelemetry/v1/traces",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://vmlogs.monitoring.1-33.ops.example.co/insert/opentelemetry/v1/logs",
    "OTEL_METRICS_INCLUDE_SESSION_ID": "false"
  }
}

Зберігаємо, перезапускаємо Claude, якщо все працює і метрики/трейси/логи є – то додаємо всім в Organization settings:

Можна зробити мінімально – тільки метрики:

{
  "channelsEnabled": true,
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://vmsingle.monitoring.1-33.ops.example.co/opentelemetry/v1/metrics",
    "OTEL_METRICS_INCLUDE_SESSION_ID": "false"
  }
}