Claude Code 공식문서 리뷰-Administration[5] : Claude Code 설정 - 모니터링(Monitoring)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [관리] 섹션의 내용 중 [Claude Code 설정 - 모니터링(Monitoring)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/monitoring-usage

모니터링 - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

Claude Code 모니터링 및 사용량 추적

OpenTelemetry 기반 관측성 구성 가이드

모니터링이 필요한가?

Claude Code를 팀이나 조직에서 사용하고 있다면, 모니터링 설정을 고려해 볼 만하다. 비용 추적, 사용량 분석, 문제 디버깅에 유용하다.

모니터링이 필요한 경우

• 비용 추적: 팀/개인별 사용량과 비용을 대시보드로 보고 싶다
• 사용량 분석: 누가 얼마나, 어떤 작업에 Claude Code를 쓰는지 파악하고 싶다
• 문제 디버깅: API 에러나 성능 문제를 추적하고 싶다
• 보안 감사: 도구 사용 내역을 로그로 남기고 싶다

모니터링이 필요 없는 경우

• 개인 프로젝트에서 혼자 사용 중이다
• 비용 추적이 필요 없다 (무제한 요금제 등)
• 별도 관측성 인프라가 없다

OpenTelemetry (OTel)란?

분산 시스템의 관측성을 위한 오픈 소스 표준이다. 메트릭, 로그, 트레이스를 수집하고 다양한 백엔드(Prometheus, Datadog, Grafana 등)로 전송할 수 있다.

비유하자면, 집에 스마트 전력 미터기를 달아 전기 사용량을 실시간으로 보는 것과 같다. Claude Code가 얼마나, 어떻게 사용되는지를 수치화해서 모니터링 도구로 보내준다.

실제로 무엇을 볼 수 있나?

• "이번 달 우리 팀이 Claude Code로 $1,200 썼구나"
• "김개발 님이 가장 활발하게 사용 중이네"
• "어제 API 에러가 5건 발생했네, 원인이 뭘까?"
• "Sonnet 모델 사용량이 Haiku보다 3배 많네"

 

빠른 시작

# 1. 텔레메트리 활성화
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 내보내기 도구 선택 (선택사항 - 필요한 것만 구성)
export OTEL_METRICS_EXPORTER=otlp       # 옵션: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # 옵션: otlp, console

# 3. OTLP 엔드포인트 구성
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. 인증 설정 (필요한 경우)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. 디버깅용: 내보내기 간격 줄이기
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10초 (기본값: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5초 (기본값: 5000ms)

# 6. Claude Code 실행
claude

기본 간격: 메트릭은 60초, 로그는 5초이다.

 

시나리오별 설정 가이드

상황에 맞는 설정 방법을 선택하자.

상황 1: "일단 로컬에서 빠르게 테스트하고 싶어요"

관측성 인프라 없이 터미널에서 바로 확인하고 싶다면 console 내보내기를 사용하자.

설정 방법

# 콘솔에 메트릭 출력 (1초 간격)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

claude

터미널에 메트릭이 실시간으로 출력된다. 설정이 제대로 되는지 확인 후 OTLP로 전환하면 된다.

상황 2: "회사 관측성 시스템(Datadog, Honeycomb 등)에 연동하고 싶어요"

대부분의 관측성 플랫폼은 OTLP를 지원한다. OTLP Collector로 데이터를 보내면 된다.

설정 방법

# OTLP/gRPC로 수집기에 전송
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.company.com:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer company-token"

상황 3: "Prometheus + Grafana 스택을 쓰고 있어요"

Prometheus 내보내기를 사용하면 Prometheus가 직접 메트릭을 스크래핑할 수 있다.

설정 방법

# Prometheus 내보내기
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Prometheus가 /metrics 엔드포인트를 스크래핑하도록 설정

Grafana 대시보드 구성은 ROI 측정 가이드를 참고하자.

상황 4: "메트릭과 로그를 다른 시스템으로 보내고 싶어요"

메트릭은 Prometheus로, 로그는 Elasticsearch로 보내는 것처럼 분리할 수 있다.

설정 방법

# 메트릭과 로그에 다른 엔드포인트/프로토콜 사용
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

# 메트릭: HTTP/protobuf
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318

# 로그: gRPC
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

상황 5: "로컬에서 확인하면서 동시에 서버로도 보내고 싶어요"

쉼표로 구분하여 여러 내보내기 도구를 동시에 사용할 수 있다.

설정 방법

# 콘솔과 OTLP 동시 사용
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

 

관리자 구성

조직 전체 제어를 위해 관리형 설정 파일(.claude/settings.json)로 구성한다:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

설정 우선순위: 관리형 설정은 높은 우선순위를 가지며, 사용자가 재정의할 수 없다. 조직 전체에 일관된 모니터링 정책을 적용할 때 유용하다.

동적 헤더 설정

기업 환경에서 인증 토큰이 주기적으로 갱신되어야 한다면, 동적 헤더 스크립트를 사용할 수 있다:

// .claude/settings.json
{
  "otelHeadersHelper": "/path/to/generate_otel_headers.sh"
}

스크립트는 유효한 JSON을 출력해야 한다:

#!/bin/bash
# generate_otel_headers.sh
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

리프레시 동작: 시작 시 실행되고, 이후 기본 29분마다 갱신된다. CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS로 간격을 조정할 수 있다.

 

구성 변수

변수	설명	예시
CLAUDE_CODE_ENABLE_TELEMETRY	텔레메트리 활성화 (필수)	1
OTEL_METRICS_EXPORTER	메트릭 내보내기 도구 유형	console, otlp, prometheus, console,otlp
OTEL_LOGS_EXPORTER	로그/이벤트 내보내기 도구 유형	console, otlp
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP 프로토콜	grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 수집기 엔드포인트	http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	메트릭 전용 엔드포인트 (선택)	http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	로그 전용 엔드포인트 (선택)	http://localhost:4318/v1/logs
OTEL_METRIC_EXPORT_INTERVAL	메트릭 내보내기 간격 (ms)	5000, 60000 (기본값)
OTEL_LOGS_EXPORT_INTERVAL	로그 내보내기 간격 (ms)	5000 (기본값)
OTEL_LOG_USER_PROMPTS	프롬프트 로깅 활성화	1 (기본값: 비활성화)

 

메트릭 카디널리티 제어

카디널리티 (Cardinality)란?

메트릭의 고유 조합 수를 의미한다. 예를 들어, 세션 ID를 포함하면 세션마다 별도 메트릭이 생성되어 카디널리티가 높아진다. 카디널리티가 높으면 저장 비용이 증가하고 쿼리 성능이 저하될 수 있다.

OTEL_METRICS_INCLUDE_SESSION_ID=false    # 기본값: true
OTEL_METRICS_INCLUDE_VERSION=true        # 기본값: false
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false  # 기본값: true

변수	기본값	용도
OTEL_METRICS_INCLUDE_SESSION_ID	true	세션별 추적이 필요하면 true, 비용 절감 우선이면 false
OTEL_METRICS_INCLUDE_VERSION	false	버전별 사용량 비교가 필요하면 true
OTEL_METRICS_INCLUDE_ACCOUNT_UUID	true	사용자별 추적이 필요하면 true

 

사용 가능한 메트릭

메트릭 이름	설명	단위
claude_code.session.count	CLI 세션 시작 수	count
claude_code.lines_of_code.count	수정된 코드 라인 수 (type: added/removed)	count
claude_code.pull_request.count	생성된 PR 수	count
claude_code.commit.count	생성된 Git 커밋 수	count
claude_code.cost.usage	세션 비용 (model 속성 포함)	USD
claude_code.token.usage	사용된 토큰 수 (type: input/output/cacheRead/cacheCreation)	tokens
claude_code.code_edit_tool.decision	도구 권한 결정 수 (tool, decision, language)	count
claude_code.active_time.total	활성 시간 (유휴 시간 제외)	seconds

 

표준 속성

모든 메트릭/이벤트에 포함된다:

속성	설명	제어 변수
session.id	고유 세션 ID	OTEL_METRICS_INCLUDE_SESSION_ID (기본값: true)
app.version	Claude Code 버전	OTEL_METRICS_INCLUDE_VERSION (기본값: false)
organization.id	조직 UUID	인증 시 항상 포함
user.account_uuid	계정 UUID	OTEL_METRICS_INCLUDE_ACCOUNT_UUID (기본값: true)
terminal.type	터미널 유형 (iTerm.app, vscode, cursor, tmux)	감지 시 항상 포함

서비스 정보 리소스 속성

모든 메트릭과 이벤트에 다음 리소스 속성도 포함된다:

속성	설명
service.name	claude-code
service.version	현재 Claude Code 버전
os.type	Linux, darwin, windows
os.version	OS 버전 문자열
host.arch	amd64, arm64 등
wsl.version	WSL 버전 (Windows Subsystem for Linux에서만)

Meter Name: com.anthropic.claude_code

 

사용 가능한 이벤트

모든 이벤트는 OTEL_LOGS_EXPORTER 설정을 사용한다.

사용자 프롬프트 이벤트

• 이름: claude_code.user_prompt
• 속성: prompt_length, prompt (기본값으로 마스킹됨, OTEL_LOG_USER_PROMPTS=1로 활성화)

도구 결과 이벤트

• 이름: claude_code.tool_result
• 속성: tool_name, success, duration_ms, error, decision, source, tool_parameters
• Bash 도구 추가 속성: bash_command, full_command, timeout, description, sandbox

API 요청 이벤트

• 이름: claude_code.api_request
• 속성: model, cost_usd, duration_ms, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens

API 에러 이벤트

• 이름: claude_code.api_error
• 속성: model, error, status_code, duration_ms, attempt

도구 결정 이벤트

• 이름: claude_code.tool_decision
• 속성: tool_name (Read, Edit, Write, NotebookEdit), decision (accept/reject), source

 

데이터 해석 및 활용

수집된 메트릭과 이벤트를 어떻게 활용할 수 있는지 알아보자.

사용량 모니터링

토큰 사용량 분석	claude_code.token.usage를 type, user, team, model별로 분류 예: "Sonnet 모델 입력 토큰이 전체의 80%를 차지하네"
세션 수 추적	claude_code.session.count로 도입률과 활성 사용자 파악 예: "이번 주 일일 세션 수가 지난주 대비 30% 증가"
생산성 측정	claude_code.lines_of_code.count, claude_code.commit.count, claude_code.pull_request.count 예: "이번 달 Claude Code로 1,500 커밋, 120 PR 생성"
워크플로우 영향	커밋/PR 수와 활성 시간을 비교하여 효율성 분석 예: "평균 세션당 3개의 커밋 생성"

비용 모니터링

비용 추적 활용 예시

• 팀/개인별 비용: user.account_uuid로 그룹화하여 비용 분배
• 모델별 비용: model 속성으로 Sonnet vs Haiku 비용 비교
• 비용 추세: 일별/주별 비용 추이를 시계열로 시각화
• 이상 탐지: 갑작스러운 비용 증가 알림 설정

주의: claude_code.cost.usage는 추정치이다. 공식 청구는 API 제공자의 대시보드를 참조하자.

일반적인 알림 설정 예시

• 비용 스파이크: 일일 비용이 평균의 2배를 초과하면 Slack 알림
• 비정상 토큰 사용: 특정 사용자의 토큰 사용량이 갑자기 10배 증가하면 알림
• API 에러 급증: 5분 내 API 에러가 10건 이상 발생하면 알림
• 높은 세션 볼륨: 동시 세션 수가 임계값을 초과하면 알림

세분화 옵션

다음 속성으로 데이터를 필터링/그룹화할 수 있다:

• user.account_uuid - 사용자별
• organization.id - 조직별
• session.id - 세션별
• model - 모델별 (Sonnet, Haiku 등)
• app.version - 버전별
• 커스텀 리소스 속성 (department, team.id 등)

 

멀티 팀 조직 지원

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

W3C Baggage 형식 요구사항

• 값에 공백 사용 불가
• 형식: key1=value1,key2=value2
• US-ASCII 문자만 허용
• 특수 문자는 퍼센트 인코딩 필요

유효한 예시

# 언더스코어 사용
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"

# camelCase 사용
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# 퍼센트 인코딩 사용
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

 

백엔드 선택 가이드

데이터 유형	권장 백엔드	적합한 경우
메트릭	Prometheus, ClickHouse, Honeycomb, Datadog	비율 계산, 집계 메트릭, 시계열 분석
이벤트/로그	Elasticsearch, Loki, ClickHouse, Honeycomb	전체 텍스트 검색, 로그 분석, 구조화된 이벤트 분석

팁: Honeycomb이나 Datadog 같은 관측성 플랫폼은 메트릭과 이벤트 간 상관 분석, 시각화, 알림을 통합 제공한다.

 

문제 해결

문제 1: 메트릭이 수집되지 않음

증상

- Prometheus/Grafana에서 메트릭이 보이지 않음
- 콘솔에 아무것도 출력되지 않음

원인 및 해결

1. 텔레메트리 활성화 확인

   echo $CLAUDE_CODE_ENABLE_TELEMETRY
   # 결과가 1이어야 함

2. 내보내기 도구 설정 확인

   echo $OTEL_METRICS_EXPORTER
   # console, otlp, prometheus 중 하나여야 함

3. console로 먼저 테스트
   OTLP 연결 문제인지 확인하려면 먼저 console로 설정하여 데이터가 생성되는지 확인하자.

문제 2: OTLP 연결 실패

증상

- "connection refused" 에러
- "failed to export" 메시지

원인 및 해결

1. 엔드포인트 주소 확인

   # gRPC는 보통 4317, HTTP는 4318 포트 사용
   # gRPC
   export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
   # HTTP
   export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

2. 프로토콜 일치 확인
   엔드포인트와 프로토콜이 일치해야 함. gRPC 엔드포인트에 http/json을 사용하면 실패한다.
3. 수집기 실행 확인

   curl http://localhost:4317
   # 연결되면 수집기가 실행 중인 것

4. 방화벽/네트워크 확인
   회사 네트워크에서 해당 포트가 열려 있는지 확인하자.

문제 3: 인증 실패

증상

- "401 Unauthorized" 에러
- "authentication failed" 메시지

해결 방법

1. 헤더 형식 확인

   # 올바른 형식
   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
   
   # 여러 헤더
   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token,X-API-Key=key123"

2. 토큰 만료 확인
   토큰이 만료되었다면 동적 헤더 설정(otelHeadersHelper)을 사용하자.

문제 4: 카디널리티 폭발

증상

- 메트릭 저장 비용이 급증
- 쿼리 성능 저하

해결 방법

세션 ID 포함을 비활성화하면 카디널리티를 크게 줄일 수 있다:

export OTEL_METRICS_INCLUDE_SESSION_ID=false

 

보안 및 개인정보

• 옵트인 방식: 텔레메트리는 명시적 구성이 필요하다 (기본값 비활성화)
• 민감한 데이터 없음: API 키, 파일 내용은 절대 포함되지 않는다
• 프롬프트 마스킹: 사용자 프롬프트는 기본적으로 마스킹된다 (길이만 기록)

주의: OTEL_LOG_USER_PROMPTS=1을 활성화하면 사용자 입력이 로그에 포함된다. 민감한 정보가 포함될 수 있으므로 신중히 사용하자.

 

핵심 요약 체크리스트

빠르게 확인하자

아래 항목들이 설정되어 있다면 모니터링 준비가 완료된 것이다.

항목	설정 내용
텔레메트리 활성화	export CLAUDE_CODE_ENABLE_TELEMETRY=1
메트릭 내보내기	export OTEL_METRICS_EXPORTER=otlp (또는 console, prometheus)
로그 내보내기	export OTEL_LOGS_EXPORTER=otlp (선택)
프로토콜	export OTEL_EXPORTER_OTLP_PROTOCOL=grpc (또는 http/json)
엔드포인트	export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
인증 (필요시)	export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token"
팀 구분 (선택)	export OTEL_RESOURCE_ATTRIBUTES="team=platform"

다음 단계

모든 설정이 완료되었다면 Claude Code를 실행하고 메트릭이 수집되는지 확인하자.

# 콘솔로 먼저 테스트
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=5000

claude "Hello, World!"

# 터미널에 메트릭이 출력되면 성공

 

추가 리소스

리소스	언제 유용한가?
ROI 측정 가이드 Docker Compose, Prometheus, 리포팅	이럴 때 보자: - Prometheus + Grafana 스택을 처음부터 구성하고 싶을 때 - 비용 대비 효과(ROI)를 측정하고 보고서를 만들고 싶을 때 - 완성된 Docker Compose 예제가 필요할 때
Bedrock 모니터링 AWS 환경 모니터링	이럴 때 보자: - Amazon Bedrock으로 Claude Code를 사용 중일 때 - AWS CloudWatch와 연동하고 싶을 때
OpenTelemetry 스펙 공식 OTLP 구성 옵션	이럴 때 보자: - 환경 변수 옵션을 상세히 알고 싶을 때 - 고급 OTLP 설정이 필요할 때
공식 문서 Claude Code 모니터링	이럴 때 보자: - 최신 공식 정보를 확인하고 싶을 때 - 이 문서에서 다루지 않은 내용을 찾을 때