모니터링

​

빠른 시작

# 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

​

관리자 구성

{
  "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"
  }
}

​

구성 세부 정보

​

일반적인 구성 변수

​

메트릭 카디널리티 제어

​

동적 헤더

​

설정 구성

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

스크립트 요구 사항

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

​

새로 고침 동작

​

다중 팀 조직 지원

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

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

# ❌ 유효하지 않음 - 공백 포함
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ 유효함 - 대신 언더스코어 또는 camelCase 사용
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ 유효함 - 필요한 경우 특수 문자를 퍼센트 인코딩
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

예제 구성

# 콘솔 디버깅 (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.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.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

​

사용 가능한 메트릭 및 이벤트

​

표준 속성

• prompt.id: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 상관시키는 UUID입니다. 이벤트 상관 속성을 참조하세요.
• workspace.host_paths: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리 (문자열 배열)

​

메트릭

​

메트릭 세부 정보

​

세션 카운터

• 모든 표준 속성

​

코드 라인 카운터

• 모든 표준 속성
• type: ("added", "removed")

​

풀 요청 카운터

• 모든 표준 속성

​

커밋 카운터

• 모든 표준 속성

​

비용 카운터

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

​

토큰 카운터

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

​

코드 편집 도구 결정 카운터

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

​

활성 시간 카운터

• 모든 표준 속성
• type: 키보드 상호 작용의 경우 "user", 도구 실행 및 AI 응답의 경우 "cli"

​

이벤트

​

이벤트 상관 속성

​

사용자 프롬프트 이벤트

• 모든 표준 속성
• event.name: "user_prompt"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• prompt_length: 프롬프트의 길이
• prompt: 프롬프트 콘텐츠 (기본적으로 수정됨, OTEL_LOG_USER_PROMPTS=1로 활성화)

​

도구 결과 이벤트

• 모든 표준 속성
• event.name: "tool_result"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• tool_name: 도구의 이름
• success: "true" 또는 "false"
• duration_ms: 실행 시간 (밀리초)
• error: 오류 메시지 (실패한 경우)
• decision_type: "accept" 또는 "reject"
• decision_source: 결정 출처 - "config", "hook", "user_permanent", "user_temporary", "user_abort" 또는 "user_reject"
• tool_result_size_bytes: 도구 결과의 크기 (바이트)
• mcp_server_scope: MCP 서버 범위 식별자 (MCP 도구의 경우)
• tool_parameters: 도구별 매개변수를 포함하는 JSON 문자열 (사용 가능한 경우)
  • Bash 도구의 경우: bash_command, full_command, timeout, description, dangerouslyDisableSandbox 및 git_commit_id (git commit 명령이 성공할 때 커밋 SHA) 포함
  • MCP 도구의 경우 (OTEL_LOG_TOOL_DETAILS=1일 때): mcp_server_name, mcp_tool_name 포함
  • Skill 도구의 경우 (OTEL_LOG_TOOL_DETAILS=1일 때): skill_name 포함
• tool_input (OTEL_LOG_TOOL_DETAILS=1일 때): JSON 직렬화된 도구 인수입니다. 512자를 초과하는 개별 값은 잘리고, 전체 페이로드는 약 4K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.

​

API 요청 이벤트

• 모든 표준 속성
• event.name: "api_request"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• model: 사용된 모델 (예: “claude-sonnet-4-6”)
• cost_usd: USD 단위의 예상 비용
• duration_ms: 요청 지속 시간 (밀리초)
• input_tokens: 입력 토큰 수
• output_tokens: 출력 토큰 수
• cache_read_tokens: 캐시에서 읽은 토큰 수
• cache_creation_tokens: 캐시 생성에 사용된 토큰 수
• speed: 빠른 모드가 활성화되었는지 여부를 나타내는 "fast" 또는 "normal"

​

API 오류 이벤트

• 모든 표준 속성
• event.name: "api_error"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• model: 사용된 모델 (예: “claude-sonnet-4-6”)
• error: 오류 메시지
• status_code: HTTP 상태 코드 (문자열) 또는 HTTP가 아닌 오류의 경우 "undefined"
• duration_ms: 요청 지속 시간 (밀리초)
• attempt: 시도 번호 (재시도된 요청의 경우)
• speed: 빠른 모드가 활성화되었는지 여부를 나타내는 "fast" 또는 "normal"

​

도구 결정 이벤트

• 모든 표준 속성
• event.name: "tool_decision"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• tool_name: 도구의 이름 (예: “Read”, “Edit”, “Write”, “NotebookEdit”)
• decision: "accept" 또는 "reject"
• source: 결정 출처 - "config", "hook", "user_permanent", "user_temporary", "user_abort" 또는 "user_reject"

​

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

​

사용 모니터링

​

비용 모니터링

• 팀 또는 개인 전체의 사용 추세 추적
• 최적화를 위한 높은 사용 세션 식별

​

경고 및 세분화

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

​

이벤트 분석

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

​

백엔드 고려 사항

​

메트릭의 경우

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

​

이벤트/로그의 경우

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

​

서비스 정보

• service.name: claude-code
• service.version: 현재 Claude Code 버전
• os.type: 운영 체제 유형 (예: linux, darwin, windows)
• os.version: 운영 체제 버전 문자열
• host.arch: 호스트 아키텍처 (예: amd64, arm64)
• wsl.version: WSL 버전 번호 (Windows Subsystem for Linux에서 실행할 때만 표시)
• 미터 이름: com.anthropic.claude_code

​

ROI 측정 리소스

​

보안 및 개인 정보 보호

• 원격 측정은 선택 사항이며 명시적 구성이 필요합니다
• 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 도구 실행 이벤트는 tool_parameters 필드에 bash 명령 및 파일 경로를 포함하며, 이는 민감한 값을 포함할 수 있습니다. 명령에 비밀이 포함될 수 있는 경우 원격 측정 백엔드를 구성하여 tool_parameters를 필터링하거나 수정합니다
• OAuth를 통해 인증된 경우 user.email이 원격 측정 속성에 포함됩니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정합니다
• 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 OTEL_LOG_USER_PROMPTS=1을 설정합니다
• 도구 입력 인수는 기본적으로 기록되지 않습니다. 이를 포함하려면 OTEL_LOG_TOOL_DETAILS=1을 설정합니다. 활성화되면 tool_result 이벤트는 MCP 서버/도구 이름 및 스킬 이름과 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 tool_input 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한되지만 인수에는 여전히 민감한 값이 포함될 수 있습니다. 필요에 따라 tool_input을 필터링하거나 수정하도록 원격 측정 백엔드를 구성합니다

​

Amazon Bedrock에서 Claude Code 모니터링