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

​
Claude Code의 OpenTelemetry

Claude Code는 모니터링 및 관측성을 위한 OpenTelemetry(OTel) 메트릭을 지원합니다. 이 문서는 Claude Code에서 OTel을 활성화하고 구성하는 방법을 설명합니다.

모든 메트릭은 OpenTelemetry의 표준 메트릭 프로토콜을 통해 내보내는 시계열 데이터입니다. 메트릭 백엔드가 올바르게 구성되어 있고 집계 세분성이 모니터링 요구 사항을 충족하는지 확인하는 것은 사용자의 책임입니다.

​
빠른 시작

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

# 1. 원격 측정 활성화
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 내보내기 도구 선택
export OTEL_METRICS_EXPORTER=otlp       # 옵션: otlp, prometheus, 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. 디버깅용: 내보내기 간격 줄이기(기본값: 600000ms/10분)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10초

# 6. Claude Code 실행
claude

기본 내보내기 간격은 10분입니다. 설정 중에는 디버깅 목적으로 더 짧은 간격을 사용할 수 있습니다. 프로덕션 환경에서는 이 값을 재설정하는 것을 잊지 마세요.

전체 구성 옵션은 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_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_EXPORTER_OTLP_PROTOCOLOTLP 내보내기 도구용 프로토콜grpc, http/json, http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 수집기 엔드포인트http://localhost:4317
OTEL_EXPORTER_OTLP_HEADERSOTLP용 인증 헤더Authorization=Bearer token
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEYmTLS 인증용 클라이언트 키클라이언트 키 파일 경로
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATEmTLS 인증용 클라이언트 인증서클라이언트 인증서 파일 경로
OTEL_METRIC_EXPORT_INTERVAL내보내기 간격(밀리초, 기본값: 10000)5000, 60000

​
메트릭 카디널리티 제어

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

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

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

​
구성 예시

# 콘솔 디버깅(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

​
사용 가능한 메트릭

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

​
메트릭 세부 정보

모든 메트릭은 다음과 같은 표준 속성을 공유합니다:

  • session.id: 고유 세션 식별자(OTEL_METRICS_INCLUDE_SESSION_ID로 제어)
  • app.version: 현재 Claude Code 버전(OTEL_METRICS_INCLUDE_VERSION으로 제어)
  • organization.id: 조직 UUID(인증된 경우)
  • user.account_uuid: 계정 UUID(인증된 경우, OTEL_METRICS_INCLUDE_ACCOUNT_UUID로 제어)

​
1. 세션 카운터

각 세션 시작 시 발생합니다.

​
2. 코드 라인 카운터

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

  • 추가 속성: type("added" 또는 "removed")

​
3. 풀 리퀘스트 카운터

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

​
4. 커밋 카운터

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

​
5. 비용 카운터

각 API 요청 후 발생합니다.

  • 추가 속성: model

​
6. 토큰 카운터

각 API 요청 후 발생합니다.

  • 추가 속성: type("input", "output", "cacheRead", "cacheCreation") 및 model

​
메트릭 데이터 해석

이러한 메트릭은 사용 패턴, 생산성 및 비용에 대한 인사이트를 제공합니다:

​
사용량 모니터링

메트릭분석 기회
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으로 세분화할 수 있습니다.

​
백엔드 고려 사항

백엔드 유형최적 용도
시계열 데이터베이스(Prometheus)비율 계산, 집계된 메트릭
컬럼형 저장소(ClickHouse)복잡한 쿼리, 고유 사용자 분석
관측성 플랫폼(Honeycomb, Datadog)고급 쿼리, 시각화, 알림

DAU/WAU/MAU 메트릭의 경우 효율적인 고유 값 쿼리를 지원하는 백엔드를 선택하세요.

​
서비스 정보

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

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

​
보안 고려 사항

  • 원격 측정은 옵트인 방식이며 명시적 구성이 필요합니다
  • API 키나 파일 내용과 같은 민감한 정보는 메트릭에 절대 포함되지 않습니다