사용량 모니터링

OpenTelemetry(OTel)를 통해 Claude Code의 사용량, 비용, 도구 활동을 시계열 데이터로 내보내고 조직 전체의 사용 현황을 체계적으로 모니터링할 수 있습니다.

빠른 시작

환경 변수를 사용하여 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. 디버깅용 내보내기 간격 단축 (기본값: 60초)
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10초

# 6. Claude Code 실행
claude

참고: 기본 내보내기 간격은 메트릭 60초, 로그 5초입니다. 설정 중에는 짧은 간격을 사용하되, 프로덕션에서는 기본값으로 되돌리세요.

관리자 구성

관리자는 관리 설정 파일을 통해 모든 사용자에 대한 OpenTelemetry 설정을 중앙에서 구성할 수 있습니다. 이를 통해 조직 전체의 텔레메트리 설정을 일관되게 관리할 수 있습니다.

{
  "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.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

참고: 관리 설정에 정의된 환경 변수는 높은 우선순위를 가지며 사용자가 재정의할 수 없습니다.

주요 구성 변수

환경 변수	설명	예시 값
`CLAUDE_CODE_ENABLE_TELEMETRY`	텔레메트리 수집 활성화 (필수)	`1`
`OTEL_METRICS_EXPORTER`	메트릭 내보내기 유형	`console`, `otlp`, `prometheus`
`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_HEADERS`	OTLP 인증 헤더	`Authorization=Bearer token`
`OTEL_METRIC_EXPORT_INTERVAL`	메트릭 내보내기 간격 (밀리초, 기본값: 60000)	`5000`, `60000`
`OTEL_LOGS_EXPORT_INTERVAL`	로그 내보내기 간격 (밀리초, 기본값: 5000)	`1000`, `10000`
`OTEL_LOG_USER_PROMPTS`	사용자 프롬프트 내용 로깅 활성화 (기본값: 비활성화)	`1`
`OTEL_LOG_TOOL_DETAILS`	MCP 서버/도구 이름 로깅 활성화	`1`

메트릭 카디널리티 제어

다음 환경 변수로 메트릭에 포함되는 속성을 제어하여 카디널리티를 관리할 수 있습니다.

환경 변수	설명	기본값
`OTEL_METRICS_INCLUDE_SESSION_ID`	메트릭에 session.id 포함	`true`
`OTEL_METRICS_INCLUDE_VERSION`	메트릭에 app.version 포함	`false`
`OTEL_METRICS_INCLUDE_ACCOUNT_UUID`	메트릭에 user.account_uuid 포함	`true`

낮은 카디널리티는 일반적으로 더 나은 성능과 낮은 스토리지 비용을 의미하지만, 분석 데이터의 세밀함이 감소합니다.

다중 팀 조직 지원

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

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

이 사용자 정의 속성을 통해 다음이 가능합니다.

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

중요: OTEL_RESOURCE_ATTRIBUTES는 공백을 포함할 수 없습니다. 공백 대신 언더스코어 또는 camelCase를 사용하세요.

사용 가능한 메트릭

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.usage`	Claude Code 세션 비용	USD
`claude_code.token.usage`	사용된 토큰 수	tokens
`claude_code.code_edit_tool.decision`	코드 편집 도구 권한 결정 수	count
`claude_code.active_time.total`	총 활성 사용 시간	초

모든 메트릭의 표준 속성

속성	설명
`session.id`	고유 세션 식별자
`app.version`	현재 Claude Code 버전
`organization.id`	조직 UUID (인증된 경우)
`user.account_uuid`	계정 UUID (인증된 경우)
`user.id`	익명 기기/설치 식별자
`user.email`	사용자 이메일 (OAuth 인증 시)
`terminal.type`	터미널 유형

이벤트 유형

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

이벤트 상관 관계

사용자가 프롬프트를 제출하면 Claude Code가 여러 API 호출과 도구를 실행할 수 있습니다. prompt.id 속성을 사용하면 단일 프롬프트에서 생성된 모든 이벤트를 추적할 수 있습니다.

주요 이벤트

이벤트	트리거
`claude_code.user_prompt`	사용자가 프롬프트를 제출할 때
`claude_code.tool_result`	도구 실행이 완료될 때
`claude_code.api_request`	Claude에 대한 각 API 요청 시
`claude_code.api_error`	API 요청이 실패할 때
`claude_code.tool_decision`	도구 권한 결정(승인/거부) 시

메트릭 및 이벤트 데이터 해석