OTEL, Prometheus, Grafana로 Claude Code Metrics 실시간 대시보드 구축 방법

Source: Dev.to

위 링크에 있는 전체 글 내용을 제공해 주시면, 해당 텍스트를 한국어로 번역해 드리겠습니다. (코드 블록, URL, 마크다운 형식 등은 그대로 유지합니다.)

개요

나는 Claude Code에서 구체적인 수치—토큰, 비용, 코드 라인 수, 생산성 비율, ROI—를 원했습니다. 이 가이드는 OTEL을 사용해 텔레메트리를 수집하고, Prometheus에 저장하며, Grafana에서 시각화하는 방법을 보여줍니다.

사전 요구 사항

• 기본 OTEL 텔레메트리가 활성화된 Claude Code
• Prometheus (v2.45+ 권장)
• Grafana (v10+ 권장)
• JSON 파싱을 위한 jq (선택 사항, 검증용)

1. Claude Code에서 텔레메트리 활성화

쉘 프로파일(~/.zshrc, ~/.bashrc 등)에 다음 환경 변수를 추가하세요:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9090/api/v1/otlp

편집을 마친 후, 프로파일을 다시 로드합니다:

source ~/.zshrc   # or source ~/.bashrc

2. Prometheus를 OTLP 메트릭 수신하도록 구성하기

Prometheus는 OTLP 수신기가 활성화된 상태와 delta‑to‑cumulative 변환 플래그를 사용하여 시작되어야 합니다:

prometheus \
  --config.file=prometheus.yml \
  --web.enable-otlp-receiver \
  --enable-feature=otlp-deltatocumulative

Note: macOS에서 Homebrew를 사용할 경우, 서비스 plist를 편집하거나 스크립트에 명령을 래핑하여 이러한 플래그를 포함시켜야 할 수도 있습니다.

왜 otlp-deltatocumulative인가?

일부 Claude Code 메트릭(예: 코드 라인 수)은 델타 메트릭입니다. 이 플래그는 이를 자동으로 누적 카운터로 변환하며, 이는 Prometheus가 기대하는 형태입니다.

3. 데이터 수집 확인

다음 명령을 실행하여 Prometheus가 수신한 메트릭 이름을 나열합니다:

curl 'http://localhost:9090/api/v1/label/__name__/values' | jq '.data[]' | grep claude

다음과 같은 메트릭이 표시됩니다:

• claude_code_token_usage_tokens_total
• claude_code_cost_usage_USD_total
• claude_code_active_time_seconds_total
• claude_code_lines_of_code_count_total
• claude_code_session_count_total

4. 메트릭 참조

active_time 해석

• type="cli" – Claude가 처리한 시간.
• type="user" – 사용자가 상호작용한 시간.

생산성 배율은 cli time / user time 입니다.

5. Grafana 대시보드

1. Claude Code Metrics – 토큰 통계, 비용 분해, 생산성 비율.
2. Daily/Weekly Summary – 시간 범위 인식을 포함한 집계 통계.
3. Engineering Economics – ROI 계산, 팀 등가성, 비즈니스 메트릭.

가져오기

JSON 파일을 GitHub gist(링크 대기 중)로 내보낸 뒤 Grafana에서 Dashboards → Import를 통해 가져옵니다.

6. Grafana 변수 및 유용한 쿼리

다음 변수들을 정의합니다:

• 시간당 요금 – ROI 계산에 사용됩니다.
• 개발자 평균 라인/시간 – 팀 규모를 동일하게 맞출 때 사용합니다.
• 생산성 비율 – CLI 시간 / 사용자 시간.

예시 쿼리

생산성 비율

sum(claude_code_active_time_seconds_total{type="cli"}) 
/
sum(claude_code_active_time_seconds_total{type="user"})

달러당 라인 수

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))
/
sum(increase(claude_code_cost_usage_USD_total[$__range]))

동등 개발자 시간 (시간당 75 라인 가정)

sum(sum_over_time(claude_code_lines_of_code_count_total[$__range])) / 75

최대 플랜 ROI (월 $200 구독자 기준)

sum(increase(claude_code_cost_usage_USD_total[$__range])) 
/ (6.67 * ($__range_s / 86400))

델타 메트릭 처리

claude_code_lines_of_code_count_total 은 델타 메트릭이므로 increase() 대신 sum_over_time()을 사용합니다:

# 잘못된 예 – 외삽된 값이 반환됩니다
sum(increase(claude_code_lines_of_code_count_total[$__range]))

# 올바른 예
sum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))

7. 샘플 출력 (1시간)

• 27,000 코드 라인
• 11분 사용자 시간
• 362× 속도 배수
• $47 K에 해당하는 출력 가치

다중 병렬 에이전트를 실행할 때 생산성 비율이 10,000× 이상으로 정점을 찍었습니다.

8. 다른 OTLP 백엔드로 내보내기

OTEL 익스포터는 OTLP‑호환 엔드포인트와 함께 작동합니다. 엔드포인트 변수를 간단히 변경하십시오:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend-endpoint

Datadog의 경우, 해당 OTLP 인테이크 URL을 지정하면 됩니다; 메트릭 이름은 동일하게 유지됩니다.

9. 향후 개선 사항

• 알림 생산성 비율이 떨어질 때 (예: 막힌 경우).
• 비용 예측 현재 소모율을 기반으로.
• 비교 패널 다양한 프로젝트 또는 팀을 위해.

설정을 확장한다면, 결과를 자유롭게 공유하세요!