Claude Code는 모니터링과 관찰 가능성을 위해 OpenTelemetry (OTel) 메트릭과 이벤트를 지원합니다.

모든 메트릭은 OpenTelemetry의 표준 메트릭 프로토콜을 통해 내보내지는 시계열 데이터이며, 이벤트는 OpenTelemetry의 로그/이벤트 프로토콜을 통해 내보내집니다. 메트릭과 로그 백엔드가 적절히 구성되고 집계 세분성이 모니터링 요구사항을 충족하는지 확인하는 것은 사용자의 책임입니다.

OpenTelemetry 지원은 현재 베타 버전이며 세부사항은 변경될 수 있습니다.

​
빠른 시작

환경 변수를 사용하여 OpenTelemetry를 구성하세요:

# 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 엔드포인트 구성 (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초입니다. 설정 중에는 디버깅 목적으로 더 짧은 간격을 사용할 수 있습니다. 프로덕션 사용 시에는 이를 재설정하는 것을 잊지 마세요.

전체 구성 옵션은 OpenTelemetry 사양을 참조하세요.

​
관리자 구성

관리자는 관리 설정 파일을 통해 모든 사용자를 위한 OpenTelemetry 설정을 구성할 수 있습니다. 이를 통해 조직 전체의 텔레메트리 설정을 중앙에서 제어할 수 있습니다. 설정이 어떻게 적용되는지에 대한 자세한 정보는 설정 우선순위를 참조하세요.

관리 설정 파일의 위치:

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux: /etc/claude-code/managed-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"
  }
}

관리 설정은 MDM(모바일 장치 관리) 또는 기타 장치 관리 솔루션을 통해 배포할 수 있습니다. 관리 설정 파일에 정의된 환경 변수는 높은 우선순위를 가지며 사용자가 재정의할 수 없습니다.

​
구성 세부사항

​
공통 구성 변수

환경 변수설명예시 값
CLAUDE_CODE_ENABLE_TELEMETRY텔레메트리 수집 활성화 (필수)1
OTEL_METRICS_EXPORTER메트릭 익스포터 유형(쉼표로 구분)console, otlp, prometheus
OTEL_LOGS_EXPORTER로그/이벤트 익스포터 유형(쉼표로 구분)console, otlp
OTEL_EXPORTER_OTLP_PROTOCOLOTLP 익스포터 프로토콜 (모든 신호)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 수집기 엔드포인트 (모든 신호)http://localhost:4317
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL메트릭 프로토콜 (일반 설정 재정의)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTLP 메트릭 엔드포인트 (일반 설정 재정의)http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL로그 프로토콜 (일반 설정 재정의)grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP 로그 엔드포인트 (일반 설정 재정의)http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_HEADERSOTLP 인증 헤더Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYmTLS 인증용 클라이언트 키클라이언트 키 파일 경로
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEmTLS 인증용 클라이언트 인증서클라이언트 인증서 파일 경로
OTEL_METRIC_EXPORT_INTERVAL밀리초 단위 내보내기 간격 (기본값: 60000)5000, 60000
OTEL_LOGS_EXPORT_INTERVAL밀리초 단위 로그 내보내기 간격 (기본값: 5000)1000, 10000
OTEL_LOG_USER_PROMPTS사용자 프롬프트 내용 로깅 활성화 (기본값: 비활성화)활성화하려면 1

​
메트릭 카디널리티 제어

다음 환경 변수는 카디널리티를 관리하기 위해 메트릭에 포함되는 속성을 제어합니다:

환경 변수설명기본값비활성화 예시
OTEL_METRICS_INCLUDE_SESSION_ID메트릭에 session.id 속성 포함truefalse
OTEL_METRICS_INCLUDE_VERSION메트릭에 app.version 속성 포함falsetrue
OTEL_METRICS_INCLUDE_ACCOUNT_UUID메트릭에 user.account_uuid 속성 포함truefalse

이러한 변수는 메트릭의 카디널리티를 제어하는 데 도움이 되며, 이는 메트릭 백엔드의 저장 요구사항과 쿼리 성능에 영향을 미칩니다. 일반적으로 낮은 카디널리티는 더 나은 성능과 낮은 저장 비용을 의미하지만 분석을 위한 세분화된 데이터는 줄어듭니다.

​
다중 팀 조직 지원

여러 팀이나 부서가 있는 조직은 OTEL_RESOURCE_ATTRIBUTES 환경 변수를 사용하여 서로 다른 그룹을 구분하는 사용자 정의 속성을 추가할 수 있습니다:

# 팀 식별을 위한 사용자 정의 속성 추가
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

이러한 사용자 정의 속성은 모든 메트릭과 이벤트에 포함되어 다음을 가능하게 합니다:

  • 팀이나 부서별로 메트릭 필터링
  • 비용 센터별 비용 추적
  • 팀별 대시보드 생성
  • 특정 팀에 대한 알림 설정

​
구성 예시

# 콘솔 디버깅 (1초 간격)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# 다중 익스포터
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# 메트릭과 로그에 대한 서로 다른 엔드포인트/백엔드
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317

# 메트릭만 (이벤트/로그 없음)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 이벤트/로그만 (메트릭 없음)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​
사용 가능한 메트릭과 이벤트

​
표준 속성

모든 메트릭과 이벤트는 다음 표준 속성을 공유합니다:

속성설명제어 변수
session.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)감지될 때 항상 포함

​
메트릭

Claude Code는 다음 메트릭을 내보냅니다:

메트릭 이름설명단위
claude_code.session.count시작된 CLI 세션 수count
claude_code.lines_of_code.count수정된 코드 라인 수count
claude_code.pull_request.count생성된 풀 리퀘스트 수count
claude_code.commit.count생성된 git 커밋 수count
claude_code.cost.usageClaude Code 세션 비용USD
claude_code.token.usage사용된 토큰 수tokens
claude_code.code_edit_tool.decision코드 편집 도구 권한 결정 수count

​
메트릭 세부사항

​
세션 카운터

각 세션 시작 시 증가합니다.

속성:

​
코드 라인 카운터

코드가 추가되거나 제거될 때 증가합니다.

속성:

​
풀 리퀘스트 카운터

Claude Code를 통해 풀 리퀘스트를 생성할 때 증가합니다.

속성:

​
커밋 카운터

Claude Code를 통해 git 커밋을 생성할 때 증가합니다.

속성:

​
비용 카운터

각 API 요청 후 증가합니다.

속성:

  • 모든 표준 속성
  • model: 모델 식별자 (예: “claude-3-5-sonnet-20241022”)

​
토큰 카운터

각 API 요청 후 증가합니다.

속성:

  • 모든 표준 속성
  • type: ("input", "output", "cacheRead", "cacheCreation")
  • model: 모델 식별자 (예: “claude-3-5-sonnet-20241022”)

​
코드 편집 도구 결정 카운터

사용자가 Edit, MultiEdit, Write, 또는 NotebookEdit 도구 사용을 승인하거나 거부할 때 증가합니다.

속성:

  • 모든 표준 속성
  • tool: 도구 이름 ("Edit", "MultiEdit", "Write", "NotebookEdit")
  • decision: 사용자 결정 ("accept", "reject")
  • language: 편집된 파일의 프로그래밍 언어 (예: "TypeScript", "Python", "JavaScript", "Markdown"). 인식되지 않는 파일 확장자의 경우 "unknown"을 반환합니다.

​
이벤트

Claude Code는 OpenTelemetry 로그/이벤트를 통해 다음 이벤트를 내보냅니다 (OTEL_LOGS_EXPORTER가 구성된 경우):

​
사용자 프롬프트 이벤트

사용자가 프롬프트를 제출할 때 로깅됩니다.

이벤트 이름: claude_code.user_prompt

속성:

  • 모든 표준 속성
  • event.name: "user_prompt"
  • event.timestamp: ISO 8601 타임스탬프
  • prompt_length: 프롬프트 길이
  • prompt: 프롬프트 내용 (기본적으로 편집됨, OTEL_LOG_USER_PROMPTS=1로 활성화)

​
도구 결과 이벤트

도구가 실행을 완료할 때 로깅됩니다.

이벤트 이름: claude_code.tool_result

속성:

  • 모든 표준 속성
  • event.name: "tool_result"
  • event.timestamp: ISO 8601 타임스탬프
  • name: 도구 이름
  • success: "true" 또는 "false"
  • duration_ms: 밀리초 단위 실행 시간
  • error: 오류 메시지 (실패한 경우)

​
API 요청 이벤트

Claude에 대한 각 API 요청에 대해 로깅됩니다.

이벤트 이름: claude_code.api_request

속성:

  • 모든 표준 속성
  • event.name: "api_request"
  • event.timestamp: ISO 8601 타임스탬프
  • model: 사용된 모델 (예: “claude-3-5-sonnet-20241022”)
  • cost_usd: USD 단위 예상 비용
  • duration_ms: 밀리초 단위 요청 지속 시간
  • input_tokens: 입력 토큰 수
  • output_tokens: 출력 토큰 수
  • cache_read_tokens: 캐시에서 읽은 토큰 수
  • cache_creation_tokens: 캐시 생성에 사용된 토큰 수

​
API 오류 이벤트

Claude에 대한 API 요청이 실패할 때 로깅됩니다.

이벤트 이름: claude_code.api_error

속성:

  • 모든 표준 속성
  • event.name: "api_error"
  • event.timestamp: ISO 8601 타임스탬프
  • model: 사용된 모델 (예: “claude-3-5-sonnet-20241022”)
  • error: 오류 메시지
  • status_code: HTTP 상태 코드 (해당하는 경우)
  • duration_ms: 밀리초 단위 요청 지속 시간
  • attempt: 시도 번호 (재시도된 요청의 경우)

​
도구 결정 이벤트

도구 권한 결정(승인/거부)이 내려질 때 로깅됩니다.

이벤트 이름: claude_code.tool_decision

속성:

  • 모든 표준 속성
  • event.name: "tool_decision"
  • event.timestamp: ISO 8601 타임스탬프
  • tool_name: 도구 이름 (예: “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit” 등)
  • decision: "accept" 또는 "reject"
  • source: 결정 소스 - "config", "user_permanent", "user_temporary", "user_abort", 또는 "user_reject"

​
메트릭과 이벤트 데이터 해석

Claude Code에서 내보내는 메트릭은 사용 패턴과 생산성에 대한 귀중한 통찰을 제공합니다. 다음은 생성할 수 있는 일반적인 시각화와 분석입니다:

​
사용량 모니터링

메트릭분석 기회
claude_code.token.usagetype(입력/출력), 사용자, 팀 또는 모델별로 분류
claude_code.session.count시간에 따른 채택률과 참여도 추적
claude_code.lines_of_code.count코드 추가/제거를 추적하여 생산성 측정
claude_code.commit.count & claude_code.pull_request.count개발 워크플로에 미치는 영향 이해

​
비용 모니터링

claude_code.cost.usage 메트릭은 다음에 도움이 됩니다:

  • 팀이나 개인별 사용 추세 추적
  • 최적화를 위한 고사용량 세션 식별

비용 메트릭은 근사치입니다. 공식 청구 데이터는 API 제공업체(Anthropic Console, AWS Bedrock 또는 Google Cloud Vertex)를 참조하세요.

​
알림 및 세분화

고려할 일반적인 알림:

  • 비용 급증
  • 비정상적인 토큰 소비
  • 특정 사용자의 높은 세션 볼륨

모든 메트릭은 user.account_uuid, organization.id, session.id, model, app.version으로 세분화할 수 있습니다.

​
이벤트 분석

이벤트 데이터는 Claude Code 상호작용에 대한 상세한 통찰을 제공합니다:

도구 사용 패턴: 도구 결과 이벤트를 분석하여 다음을 식별:

  • 가장 자주 사용되는 도구
  • 도구 성공률
  • 평균 도구 실행 시간
  • 도구 유형별 오류 패턴

성능 모니터링: API 요청 지속 시간과 도구 실행 시간을 추적하여 성능 병목 지점을 식별합니다.

​
백엔드 고려사항

메트릭과 로그 백엔드 선택에 따라 수행할 수 있는 분석 유형이 결정됩니다:

​
메트릭의 경우:

  • 시계열 데이터베이스 (예: Prometheus): 비율 계산, 집계된 메트릭
  • 컬럼형 저장소 (예: ClickHouse): 복잡한 쿼리, 고유 사용자 분석
  • 완전한 기능의 관찰 가능성 플랫폼 (예: Honeycomb, Datadog): 고급 쿼리, 시각화, 알림

​
이벤트/로그의 경우:

  • 로그 집계 시스템 (예: Elasticsearch, Loki): 전문 검색, 로그 분석
  • 컬럼형 저장소 (예: ClickHouse): 구조화된 이벤트 분석
  • 완전한 기능의 관찰 가능성 플랫폼 (예: Honeycomb, Datadog): 메트릭과 이벤트 간의 상관관계

일일/주간/월간 활성 사용자(DAU/WAU/MAU) 메트릭이 필요한 조직의 경우, 효율적인 고유 값 쿼리를 지원하는 백엔드를 고려하세요.

​
서비스 정보

모든 메트릭은 다음과 함께 내보내집니다:

  • 서비스 이름: claude-code
  • 서비스 버전: 현재 Claude Code 버전
  • 미터 이름: com.anthropic.claude_code

​
보안/개인정보 고려사항

  • 텔레메트리는 옵트인이며 명시적인 구성이 필요합니다
  • API 키나 파일 내용과 같은 민감한 정보는 메트릭이나 이벤트에 포함되지 않습니다
  • 사용자 프롬프트 내용은 기본적으로 편집됩니다 - 프롬프트 길이만 기록됩니다. 사용자 프롬프트 로깅을 활성화하려면 OTEL_LOG_USER_PROMPTS=1을 설정하세요