Claude Code Observability Stack 빠른 시작 및 대시보드 가이드

Claude Code Observability Stack 빠른 시작 가이드

Claude Code Observability Stack은 실제로 GitHub에 공개된 예제 리포지터리를 통해, 로컬 환경에서 1~2분 안에 띄워볼 수 있습니다.¹² 이 섹션에서는 공식 리포지터리 기준으로 누구나 따라 할 수 있는 최소 설정 절차와, 기본 제공되는 안전 장치(프롬프트 마스킹 등) 를 정리합니다.

1. 로컬에서 전체 스택 띄우기

아래 리포지터리를 클론하면, OpenTelemetry Collector·Prometheus·Loki·Grafana가 한 번에 올라가도록 Docker Compose가 구성돼 있습니다.¹²

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

# 전체 스택 실행
make up

# 상태 확인 (선택)
make status

기본 포트는 다음과 같이 열립니다.²

Grafana: http://localhost:3000 (기본 계정 admin/admin)
Prometheus: http://localhost:9090
Loki: 3100 포트 (Grafana에서 로그 데이터 소스로 사용)
OpenTelemetry Collector: 4317(gRPC), 4318(HTTP)

이 구조는 기존 노트에서 설명한 아키텍처(Claude Code → OpenTelemetry → Prometheus/Loki → Grafana)와 정확히 일치합니다.¹²

2. Claude Code에서 텔레메트리 활성화하기

Claude Code가 메트릭·로그를 OpenTelemetry Collector로 보내려면, 아래와 같이 환경 변수를 설정한 뒤 claude CLI를 실행하면 됩니다.¹²

# Claude Code의 관측 데이터 전송 활성화
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# OTLP(gRPC) 엔드포인트 설정
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# (선택) 테스트용으로 전송 주기 단축
export OTEL_METRIC_EXPORT_INTERVAL=10000   # 10초
export OTEL_LOGS_EXPORT_INTERVAL=5000      # 5초

# Claude Code 실행
claude

이 설정이 완료되면 Claude Code 세션이 시작될 때마다, 기존 노트에서 소개한 메트릭들(세션 수, 토큰 사용량, 비용, 커밋/PR 수 등)이 Prometheus와 Loki로 자동 전송됩니다.¹²

3. 실제 Grafana 대시보드 화면 예시

리포지터리에는 Claude Code에 특화된 Grafana 대시보드 JSON이 포함돼 있으며, 실행만 해도 아래와 같은 화면을 확인할 수 있습니다.²

3-1. 비용·토큰 사용량 분석 대시보드

아래 이미지는 Cost & Usage Analysis 섹션 예시로, 모델별 비용, API 요청 수, 토큰 타입별 사용량이 한 번에 보이도록 구성돼 있습니다.²

이미지 출처: GitHub - ColeMurray/claude-code-otel

이 화면에서 다음과 같은 분석이 가능합니다.¹²

시간대별·모델별 비용 추이 비교
입력/출력/캐시 토큰 사용량을 분리해서 확인
API 요청 수 변화와 비용 변화를 함께 비교

즉, 기존 노트에서 말한 "어디서, 왜 비용이 나오는지 추적" 을 실제 그래프로 확인할 수 있는 구체적인 구현입니다.

3-2. 사용자 활동·생산성 대시보드

다음 이미지는 User Activity & Productivity 섹션 예시로, 세션 수·도구 사용 패턴·코드 변경량(라인 수, 커밋, PR)을 추적합니다.²

이미지 출처: GitHub - ColeMurray/claude-code-otel

이 화면을 통해 기존 노트에서 설명한 다음 질문들을, 실제 숫자로 확인할 수 있습니다.¹²

Claude Code를 많이 쓰는 사람과 적게 쓰는 사람 사이의 코드 변경량 차이
팀별 AI 도구 활용도와 커밋/PR 패턴의 상관관계
새로운 AI 기능 도입 전후로 생산성 지표가 어떻게 변했는지

4. 프라이버시·보안 관련 기본 동작 (팩트 체크)

실제 리포지터리와 문서 기준으로, Claude Code Observability Stack에는 다음과 같은 안전 장치가 포함돼 있습니다.¹

프롬프트 텍스트는 기본적으로 마스킹(비활성화) 상태
- 사용자 입력 프롬프트 전체를 그대로 로그에 남기지 않고, 필요 시에만 별도 설정으로 활성화하게 되어 있습니다.
- 보안·개인정보·IP 보호 관점에서 "디폴트 안전 모드"에 가깝습니다.
고카디널리티 라벨(세션 ID, 계정 UUID 등)은 토글 가능
- 환경 변수를 통해 세션 ID·계정 UUID 등을 수집하지 않도록 끌 수 있어, 카디널리티 폭발에 따른 성능/비용 문제를 줄일 수 있습니다.
- 이는 기존 노트에서 언급된 "식별자 수준 조정"을 실제 설정 옵션으로 제공하는 형태입니다.
멀티 익스포터 지원
- OpenTelemetry Collector에서 Prometheus뿐 아니라 Datadog 등 다른 모니터링 백엔드로도 동시에 데이터를 보낼 수 있도록 설계되어 있습니다.¹
- 조직에서 이미 쓰고 있는 관측 플랫폼이 있다면 "Claude 전용 스택 + 기존 플랫폼"을 함께 운영하는 구성이 가능합니다.

이 점들을 고려하면, Claude Code Observability Stack은 단순 샘플이 아니라, 실무 관점의 보안·운영 요구사항을 어느 정도 반영한 레퍼런스 구현이라고 볼 수 있습니다.¹²

5. 실제 도입 시 점검 체크리스트

위 구성과 이미지들을 바탕으로, 팀에 도입할 때 최소한 아래 항목만 점검해도 시행착오를 크게 줄일 수 있습니다.

네트워크·포트 개방 여부
- 개발자 로컬 혹은 개발 클러스터에서 4317, 3000, 9090, 3100 포트 접근이 가능한지 확인.²
텔레메트리 범위 정의
- 어떤 메트릭(비용·토큰·세션·코드 활동 등)까지 반드시 보고 싶은지 우선순위를 정하고, 불필요한 로그는 초기에 비활성화.
프롬프트/코드 내용 취급 정책
- 프롬프트 원문을 남길지, 메타데이터만 남길지, 어떤 토큰(예: 이메일, 고객 ID 등)을 마스킹할지 팀별로 규정.
권한·접근 제어
- Grafana에서 비용 데이터와 개발자별 활동 데이터를 누가 볼 수 있는지 롤(Role)을 미리 설계.

이 체크리스트는 기존 노트의 "운영 시 고려할 고급 설정 포인트"를, 실제 GitHub 리포지터리 설정과 대시보드 예시를 바탕으로 다시 구체화한 것입니다.¹²

참고

¹Claude Code Observability Stack: Visualize Token Spend with Grafana

²GitHub - ColeMurray/claude-code-otel: A comprehensive observability solution for monitoring Claude Code usage, performance, and costs.