모니터링

Claude Code에 대한 OpenTelemetry를 활성화하고 구성하는 방법을 알아봅니다.

OpenTelemetry(OTel)를 통해 원격 측정 데이터를 내보내 조직 전체에서 Claude Code 사용, 비용 및 도구 활동을 추적합니다. Claude Code는 표준 메트릭 프로토콜을 통해 메트릭을 시계열 데이터로 내보내고, 로그/이벤트 프로토콜을 통해 이벤트를 내보내며, 선택적으로 추적 프로토콜을 통해 분산 추적을 내보냅니다.

빠른 시작

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

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

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

# 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

메트릭을 내보내는 설정을 확인하려면 백엔드에서 claude_code.session.count 메트릭을 확인하세요. Claude Code는 세션이 시작될 때 이 메트릭을 내보냅니다. 로그 전용 설정을 확인하려면 프롬프트를 제출하고 claude_code.user_prompt 이벤트를 확인하세요.

아무것도 도착하지 않으면 claude --debug를 실행하고 디버그 로그를 확인하세요. Claude Code는 구성한 내보내기에서의 실패를 [3P telemetry] 오류로 보고합니다. 여기서 3P는 타사를 의미합니다. [Anthropic telemetry]로 시작하는 줄은 Anthropic의 별도 운영 원격 측정을 설명하며 설정 문제를 나타내지 않습니다.

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

관리자 구성

관리자는 관리 설정 파일을 통해 모든 사용자에 대한 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는 OTEL_* 환경 변수를 Bash 도구, 훅, MCP 서버 및 언어 서버를 포함하여 생성하는 하위 프로세스에 전달하지 않습니다. Bash 도구를 통해 실행하는 OpenTelemetry 계측 애플리케이션은 Claude Code의 내보내기 엔드포인트 또는 헤더를 상속하지 않으므로 해당 애플리케이션이 자신의 원격 측정을 내보내야 하는 경우 명령에서 직접 이러한 변수를 설정합니다.

관리 설정이 OTLP 대상을 잠그는 방식

관리 설정에서 OTEL_EXPORTER_OTLP_* 변수를 설정하면 Claude Code는 시작 시 충돌하는 개발자 설정 변수를 제거하고 claude --debug로 볼 수 있는 경고를 기록합니다. 제거되는 항목은 설정하는 변수에 따라 달라집니다:

• 엔드포인트: OTEL_EXPORTER_OTLP_ENDPOINT를 설정하면 Claude Code는 개발자가 설정한 모든 신호별 엔드포인트를 제거합니다. 개발자가 한 신호를 다른 수집기로 지정할 수 없으므로 관리 설정에서 신호별 엔드포인트 변수를 설정할 필요가 없습니다.

• 프로토콜: OTEL_EXPORTER_OTLP_PROTOCOL을 설정하면 Claude Code는 개발자가 설정한 모든 신호별 프로토콜을 제거합니다.

• 자격증명: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY 또는 OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE를 설정하면 Claude Code는 해당 변수의 개발자 설정 신호별 버전과 모든 개발자 설정 엔드포인트 변수(일반 또는 신호별)를 제거합니다. 이러한 자격증명이 관리 설정이 선택하지 않은 수집기에 도달할 수 있기 때문입니다.

• 내보내기 선택기: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER 및 베타 OTEL_TRACES_EXPORTER는 일반적인 키별 우선순위를 따릅니다. 개발자의 설정이 여전히 신호를 비활성화하거나 콘솔 내보내기로 전환할 수 있으므로 필요한 경우 관리 설정에서도 선택기를 설정하세요. 관리 소스에서 OTEL_LOGS_EXPORTER는 원격 측정 단위를 따르는 반면 다른 두 선택기는 키별로 병합됩니다. Claude Code v2.1.223 이상이 필요합니다.

• 베타 추적 엔드포인트: 상세 베타 추적이 활성화되면 Claude Code는 로그 및 추적 내보내기를 통해서가 아니라 BETA_TRACING_ENDPOINT로 내보냅니다. 따라서 Claude Code는 다음 관리 설정 중 하나가 신호의 대상을 결정할 때마다 개발자 설정 BETA_TRACING_ENDPOINT를 제거합니다:

  • 일반 또는 로그/추적 엔드포인트 또는 자격증명
  • otelHeadersHelper
  • none, console 또는 비어있음으로 설정된 로그 또는 추적 내보내기 선택기(신호를 수집기에서 유지하는 값)
  • CLAUDE_CODE_ENABLE_TELEMETRY 비활성화

  메트릭 전용 엔드포인트 또는 자격증명은 제거하지 않습니다. v2.1.251 이전에는 개발자 설정 BETA_TRACING_ENDPOINT가 관리 설정이 수집기를 고정했을 때도 상세 베타 추적이 내보내는 로그 및 추적을 리디렉션했습니다.

Claude Code는 관리 설정 자체에서 설정한 신호별 변수를 제거하지 않으므로 해당 변수를 설정하여 한 신호를 다른 수집기로 라우팅할 수 있습니다(SIEM 예에서 수행하는 것처럼). 신호별 자격증명을 설정하면 Claude Code는 해당 신호에 대한 개발자 설정 엔드포인트를 제거합니다.

이 제거 동작은 원격 측정이 전달되는 위치를 변경하며 Claude Code가 수집하는 항목은 변경하지 않습니다.

v2.1.217 이전에는 모든 변수가 키별 설정 우선순위를 독립적으로 따랐으므로 사용자 설정 또는 셸에서 설정한 신호별 엔드포인트가 해당 신호를 관리 수집기에서 리디렉션했습니다.

데스크톱 앱 또는 자체 호스팅 환경 실행기가 Claude Code를 시작하고 제공하는 환경에서 OTLP 엔드포인트를 지정하면 Claude Code는 동일한 방식으로 대상을 고정합니다: 실행기의 원격 측정 변수는 관리 설정과 정확히 동일하게 개발자 설정 변수를 제거합니다. Claude Code는 실행기 자체가 설정한 변수를 제거하지 않습니다. Claude Code v2.1.251 이상이 필요합니다.

구성 세부 정보

일반적인 구성 변수

이러한 변수는 모든 배포에 대한 내보내기, 엔드포인트 및 내보내기 동작을 구성합니다. OTEL_EXPORTER_OTLP_METRICS_ENDPOINT와 같은 신호별 엔드포인트 또는 프로토콜 변수를 설정하면 Claude Code는 해당 신호에 대해 일반 변수 대신 이를 사용합니다. OTEL_EXPORTER_OTLP_METRICS_HEADERS와 같은 신호별 헤더 변수를 설정하면 Claude Code는 해당 신호에 대해 일반 OTEL_EXPORTER_OTLP_HEADERS와 병합합니다. 관리되는 설정이 있는 머신에서는 관리되는 설정이 OTLP 대상을 잠그는 방법을 참조하여 Claude Code가 제거하는 항목을 확인합니다.

http/protobuf 및 http/json 프로토콜의 경우 Claude Code는 각 내보내기 요청을 Content-Length 헤더와 함께 전송합니다. v2.1.212 이전에는 v2.1.191 이상의 Claude Code 버전이 청크 전송 인코딩을 사용하여 이러한 요청을 전송했습니다. Azure Monitor 및 기타 선언된 길이가 필요한 엔드포인트는 411 Length Required 또는 400 오류로 거부했습니다.

mTLS 인증

OTLP 내보내기를 위한 클라이언트 인증서를 구성하는 방법은 해당 신호에 사용되는 OTLP 프로토콜에 따라 다르며, OTEL_EXPORTER_OTLP_PROTOCOL 또는 신호별 재정의를 통해 설정됩니다. 동일한 구성이 메트릭, 로그 및 추적에 적용됩니다.

grpc의 경우 OpenTelemetry SDK는 표준 OTLP 변수를 직접 읽으므로 신호별 메트릭 변수를 설정하는 기존 구성은 계속 작동합니다. 관리되는 설정이 있는 머신에서는 Claude Code가 시작 시 개발자가 설정한 신호별 자격 증명 및 엔드포인트를 제거할 수 있습니다.

메트릭 카디널리티 제어

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

낮은 카디널리티는 일반적으로 더 나은 성능과 낮은 저장소 비용을 의미하지만 분석을 위한 세분화된 데이터는 적습니다.

추적 (베타)

분산 추적은 각 사용자 프롬프트를 해당 프롬프트가 트리거하는 API 요청 및 도구 실행에 연결하는 스팬을 내보내므로 추적 백엔드에서 전체 요청을 단일 추적으로 볼 수 있습니다.

추적은 기본적으로 꺼져 있습니다. 활성화하려면 CLAUDE_CODE_ENABLE_TELEMETRY=1 및 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1을 모두 설정한 다음 OTEL_TRACES_EXPORTER를 설정하여 스팬을 보낼 위치를 선택합니다. 추적은 엔드포인트, 프로토콜, 헤더 및 mTLS에 대해 일반적인 OTLP 구성을 재사용합니다. 관리되는 설정이 있는 머신에서는 Claude Code가 시작 시 개발자가 설정한 신호별 자격 증명 및 엔드포인트를 제거할 수 있습니다.

스팬은 기본적으로 사용자 프롬프트 텍스트, 도구 입력 세부 정보 및 도구 콘텐츠를 수정합니다. OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 및 OTEL_LOG_TOOL_CONTENT=1을 설정하여 포함합니다.

추적이 활성화되면 Bash 및 PowerShell 하위 프로세스는 활성 도구 실행 스팬의 W3C 추적 컨텍스트를 포함하는 TRACEPARENT 환경 변수를 자동으로 상속합니다. 이를 통해 TRACEPARENT를 읽는 모든 하위 프로세스가 자신의 스팬을 동일한 추적 아래에 부모로 지정할 수 있으므로 Claude가 실행하는 스크립트 및 명령을 통한 엔드투엔드 분산 추적이 가능합니다.

추적이 활성화되고 Claude Code가 Anthropic API에 직접 연결되어 있으면 각 모델 요청은 claude_code.llm_request 스팬의 컨텍스트로 설정된 W3C traceparent 헤더를 전달하고, API의 traceresponse 헤더는 스팬 링크로 기록됩니다. 이들은 함께 Claude Code의 클라이언트 측 스팬을 모든 호환 중간 계층을 통해 서버 측 추적에 연결합니다. 아웃바운드 HTTP MCP 요청은 동일한 방식으로 traceparent를 전달합니다. 헤더는 타사 제공자에게 전송되지 않습니다.

기본적으로 모델 및 HTTP MCP 요청의 traceparent 헤더는 ANTHROPIC_BASE_URL이 설정되지 않았거나 Anthropic API를 가리킬 때만 전송됩니다. 일부 프록시는 인식되지 않는 헤더를 거부하기 때문입니다. 하위 프로세스 TRACEPARENT 변수는 일관성을 위해 동일한 스위치로 제어됩니다. 사용자 정의 ANTHROPIC_BASE_URL 프록시를 통해 Claude Code를 실행하고 추적 컨텍스트를 전파하려면 CLAUDE_CODE_PROPAGATE_TRACEPARENT=1을 설정합니다.

Agent SDK 및 -p로 시작된 비대화형 세션에서 Claude Code는 각 상호 작용 스팬을 시작할 때 자신의 환경에서 TRACEPARENT 및 TRACESTATE를 읽습니다. 이를 통해 임베딩 프로세스가 활성 W3C 추적 컨텍스트를 하위 프로세스에 전달할 수 있으므로 Claude Code의 스팬이 호출자의 분산 추적의 자식으로 나타납니다. 대화형 세션은 CI 또는 컨테이너 환경의 주변 값을 실수로 상속하는 것을 피하기 위해 인바운드 TRACEPARENT를 무시합니다.

인바운드 추적 컨텍스트는 이벤트에도 적용됩니다. TRACEPARENT가 설정된 Agent SDK 및 -p 세션에서 각 OTLP 이벤트 로그 레코드는 추적 내보내기가 구성되지 않은 경우에도 로깅 백엔드가 이벤트를 추적의 나머지 부분과 상관시킬 수 있도록 애플리케이션의 추적에 조인하는 trace_id 및 span_id 값을 전달합니다.

활성 상호 작용 중에 내보낸 레코드는 권한 프롬프트 콜백이나 시작 중에 버퍼링되고 나중에 내보낸 레코드와 같이 스팬의 비동기 컨텍스트 외부에서 Claude Code가 내보낸 경우에도 상호 작용 스팬의 ID를 전달합니다. 활성 상호 작용 스팬이 없는 상태에서 내보낸 레코드는 인바운드 TRACEPARENT ID를 직접 전달합니다. v2.1.214 이전에는 스팬의 비동기 컨텍스트 외부에서 내보낸 레코드가 스팬의 ID 대신 인바운드 TRACEPARENT ID를 전달했습니다. v2.1.212 이전에는 활성 스팬 외부에서 내보낸 이벤트 레코드가 trace_id 또는 span_id를 전달하지 않았습니다.

스팬 계층 구조

각 사용자 프롬프트는 claude_code.interaction 루트 스팬을 시작합니다. API 호출, 도구 호출 및 훅 실행은 자식으로 기록됩니다. 도구 스팬에는 권한 결정 대기 시간과 실행 자체에 대한 두 개의 자식 스팬이 있습니다. Agent 도구 또는 레거시 Task 도구가 하위 에이전트를 생성하면 하위 에이전트의 API 및 도구 스팬은 부모의 claude_code.tool 스팬 아래에 중첩됩니다.

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (상세 베타 추적 필요)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent 도구) 하위 에이전트 claude_code.llm_request / claude_code.tool 스팬

Agent SDK 및 claude -p 세션에서 TRACEPARENT가 환경에 설정되면 claude_code.interaction 자체가 호출자의 스팬의 자식이 됩니다.

PreToolUse 훅이 도구 호출을 나중으로 연기하면 Claude Code는 이를 연기한 턴의 추적 컨텍스트를 저장합니다. 세션을 재개하고 도구가 다시 실행되면 도구의 스팬은 턴의 claude_code.interaction 스팬의 자식으로 이전 턴의 추적에 조인됩니다.

스팬 속성

모든 스팬은 표준 속성과 이름과 일치하는 span.type 속성을 전달합니다. 아래 표는 각 스팬에 설정된 추가 속성을 나열합니다. llm_request, tool.execution 및 hook 스팬은 실패를 기록할 때 OpenTelemetry 상태 ERROR를 설정합니다. 다른 스팬은 항상 상태 UNSET으로 끝납니다.

claude_code.interaction

claude_code.llm_request

각 재시도 시도는 attempt 및 client_request_id 속성이 있는 gen_ai.request.attempt 스팬 이벤트로도 기록됩니다.

claude_code.tool

OTEL_LOG_TOOL_CONTENT=1일 때 이 스팬은 속성에 도구의 입력 및 출력 본문을 포함하는 tool.output 스팬 이벤트도 기록합니다 (속성당 콘텐츠 제한 (기본값 60KB)에서 잘림).

claude_code.tool.blocked_on_user

claude_code.tool.execution

claude_code.hook

이 스팬은 상세 베타 추적이 활성화되어 있을 때만 나타나며, 이는 ENABLE_BETA_TRACING_DETAILED=1 및 BETA_TRACING_ENDPOINT가 필요합니다. 이 쌍은 또한 로그 및 추적이 이동하는 위치를 변경합니다. 셸, 사용자 설정 또는 관리되는 설정에서 쌍을 설정합니다. 두 변수 모두 프로젝트 및 로컬 설정에서 무시됩니다. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA만으로는 생성되지 않습니다.

대화형 CLI 세션에서 상세 베타 추적은 또한 조직이 이 기능에 대해 허용 목록에 있어야 합니다. Agent SDK 및 비대화형 -p 세션은 허용 목록이 필요하지 않습니다.

동적 헤더

동적 인증이 필요한 엔터프라이즈 환경의 경우 스크립트를 구성하여 헤더를 동적으로 생성할 수 있습니다. 동적 헤더는 http/protobuf 및 http/json 프로토콜에만 적용됩니다. grpc 프로토콜의 경우 Claude Code는 정적 헤더 변수 OTEL_EXPORTER_OTLP_HEADERS 및 신호별 변형만 사용합니다.

설정 구성

.claude/settings.json에 추가합니다 (경로를 자신의 스크립트로 바꿉니다):

{
  "otelHeadersHelper": "/path/to/generate-otel-headers.sh"
}

값은 공백을 포함한 경로를 포함하는 실행 파일의 경로이거나 인수가 있는 셸 명령줄일 수 있습니다. Windows에서 값은 항상 셸을 통해 실행되므로 공백을 포함하는 경로를 JSON 값 내에 따옴표로 묶습니다.

스크립트 요구 사항

스크립트는 HTTP 헤더를 나타내는 문자열 키-값 쌍이 있는 유효한 JSON을 출력해야 합니다:

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

도우미가 실패하거나 이러한 요구 사항을 충족하지 않는 출력을 인쇄하면 Claude Code는 다음에서 오류를 보고합니다:

• /status 출력
• --debug로 실행하거나 세션에서 /debug를 실행한 후의 디버그 로그
• -p로 시작된 비대화형 세션의 stderr

새로 고침 동작

헤더 도우미 스크립트는 시작 시 그리고 그 이후 주기적으로 실행되어 토큰 새로 고침을 지원합니다. 기본적으로 스크립트는 29분마다 실행됩니다. CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS 환경 변수로 간격을 사용자 정의합니다.

다중 팀 조직 지원

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

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

이러한 사용자 정의 속성은 모든 메트릭 및 이벤트에 포함되어 다음을 수행할 수 있습니다:

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

Claude Code는 이러한 값을 모든 메트릭 데이터포인트 및 이벤트 레코드의 속성으로 첨부하고, OTLP 리소스 블록에서도 전송합니다. 대부분의 메트릭 백엔드는 데이터포인트 속성을 쿼리 가능한 레이블로 노출하므로 사용자 정의 키로 직접 메트릭을 그룹화하고 필터링할 수 있습니다. vcs.* 저장소 속성을 제외하고 사용자 정의 키는 user.id 또는 session.id와 같은 표준 속성을 재정의하지 않습니다. 키가 충돌하면 Claude Code는 기본 제공 값을 유지합니다.

각 사용자 정의 키는 모든 메트릭 시리즈의 레이블이 되므로 높은 카디널리티 값은 메트릭 백엔드의 저장소 비용을 증가시킵니다. 사용자 정의 속성을 리소스 블록에만 보내고 데이터포인트 레이블에서 생략하려면 OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false를 설정합니다. 메트릭 카디널리티 제어를 참조합니다.

예제 구성

claude를 실행하기 전에 이러한 환경 변수를 설정합니다. 각 시나리오는 완전한 구성을 보여주며, 각 변수는 일반적인 구성 변수에서 설명됩니다. 구성이 적용되었는지 확인하려면 세션을 시작한 후 백엔드에서 claude_code.session.count 메트릭을 확인합니다. 빠른 시작은 로그 전용 확인 및 아무것도 도착하지 않을 때 확인할 사항을 다룹니다.

콘솔 디버깅 (1초 간격):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

OTLP over 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 (http://localhost:9464/metrics에서 스크래핑):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

자체 호스팅 환경에서 세션은 러너의 기본 용량 1에서만 포트 9464를 바인딩합니다. 더 높은 용량에서 러너는 대신 자신의 /metrics 엔드포인트에서 세션 카운터 및 게이지를 다시 노출합니다.

여러 내보내기로 메트릭을 보내려면:

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

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

표준 속성

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

Claude Code가 Claude 앱 게이트웨이에 로그인되어 있으면 CLI는 게이트웨이 세션의 인증된 ID로 내보내기를 스탬프합니다: user.id는 익명 설치 식별자가 아닌 IdP 주체이고, user.email은 로그인한 이메일이며, user.groups는 IdP 그룹 멤버십을 쉼표로 구분된 문자열로 전달합니다. 각 내보내기는 또한 identity.source: gateway-oidc를 전달합니다. 게이트웨이 ID는 마지막에 적용되므로 OTEL_RESOURCE_ATTRIBUTES를 통해 설정된 user.* 및 identity.* 키는 게이트웨이 세션에서 무시됩니다.

이벤트는 추가로 다음 속성을 포함합니다. 이들은 무한 카디널리티를 야기할 수 있으므로 메트릭에는 절대 첨부되지 않습니다:

• prompt.id: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 연관시키는 UUID입니다. 이벤트 상관 속성 참조.
• workspace.host_paths: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리(문자열 배열)
• workflow.run_id: Workflow 도구 실행에 속하는 에이전트가 내보낸 API 및 도구 이벤트의 실행 식별자(접두사 wf_). 하나의 workflow.run_id로 이벤트를 필터링하면 해당 실행의 API 요청 및 도구 결과를 재구성합니다. 식별자는 워크플로우 스크립트가 생성하는 에이전트와 그 에이전트가 차례로 생성하는 모든 에이전트(예: 스킬 호출)를 포함합니다. Workflow 도구 결과에서 보고된 실행 식별자와 일치합니다. 다른 모든 이벤트에는 없습니다. Claude Code v2.1.202 이상 필요
• workflow.name: 워크플로우의 이름(스크립트의 meta.name), workflow.run_id와 함께 내보냅니다. 기본 제공 워크플로우 이름은 실행이 수정되지 않은 기본 제공 스크립트를 실행할 때 그대로 나타납니다. 기본 제공 스크립트의 편집된 복사본을 포함한 사용자 작성 이름은 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 custom으로 대체됩니다. Claude Code v2.1.202 이상 필요

저장소 속성

OTEL_METRICS_INCLUDE_REPOSITORY=true를 설정하여 메트릭과 이벤트를 세션의 저장소 ID로 태그하면, 공유 수집기가 저장소별로 사용량을 속성화할 수 있습니다. Claude Code v2.1.269 이상 필요합니다.

Claude Code는 저장소의 origin 원격에서 이러한 속성을 세션당 한 번 파생합니다. 하나의 저장소의 HTTPS 및 SSH 원격은 동일한 값을 생성합니다:

값은 소문자로 변환되며, 원격 URL의 자격 증명, 쿼리 문자열, 및 조각은 절대 나타나지 않습니다. 세션에 origin 원격이 없을 때, 원격이 URL 형태가 아닐 때, 또는 유일한 포함 저장소가 홈 디렉토리일 때 속성은 생략됩니다.

OTEL_RESOURCE_ATTRIBUTES에서 선언한 vcs.* 키는 해당 키의 파생 값을 대체합니다. vcs.repository.url.full을 선언하면 Claude Code는 절대 원격을 읽지 않으며 선언한 키만 보고합니다.

속성은 자신의 내보내기로만 흐릅니다. Anthropic의 원격 측정은 모든 vcs.* 키를 삭제합니다.

메트릭

Claude Code는 다음 메트릭을 내보냅니다. Unit 열은 각 메트릭에 첨부된 OpenTelemetry 단위 문자열을 보여줍니다. 카운트 메트릭은 없습니다.

prometheus가 OTEL_METRICS_EXPORTER에 나열된 유일한 내보내기일 때, Claude Code는 스크래이프가 유효한 Prometheus 텍스트 형식으로 유지되도록 내보낸 메트릭에서 USD, tokens, 및 s 단위를 생략합니다. 메트릭 이름은 변경되지 않으며, otlp,prometheus와 같이 내보내기를 결합하는 구성은 단위를 유지합니다. v2.1.216 이전에는 Prometheus 스크래이프에 일부 스크래이퍼가 거부한 OpenMetrics 전용 # UNIT 라인이 포함되었습니다.

메트릭 세부 정보

각 메트릭은 위에 나열된 표준 속성을 포함합니다. 추가 컨텍스트별 속성이 있는 메트릭은 아래에 표시됩니다.

세션 카운터

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

속성:

• 모든 표준 속성
• start_type: 세션이 시작된 방식. "fresh", "resume", "continue", 또는 "agents_view" 중 하나입니다. "agents_view" 값은 claude agents 대시보드 프로세스(대화형 세션이 아닌 사용자가 시작한 로컬 UI)를 식별합니다. 이 값으로 필터링하여 대시보드에서 UI 프로세스 시작을 대화형 세션과 분리합니다.

코드 라인 카운터

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

속성:

• 모든 표준 속성
• type: ("added", "removed")
• model: 변경을 수행한 모델의 모델 식별자(예: "claude-sonnet-5")

풀 요청 카운터

Claude Code가 셸 명령 또는 MCP 도구를 통해 풀 요청 또는 병합 요청을 생성할 때 증가합니다.

속성:

• 모든 표준 속성

커밋 카운터

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

속성:

• 모든 표준 속성

비용 카운터

각 API 요청 후 증가합니다.

속성:

• 모든 표준 속성
• model: 모델 식별자(예: "claude-sonnet-5")
• query_source: 요청을 발급한 하위 시스템의 범주. "main", "subagent", 또는 "auxiliary" 중 하나입니다.
• speed: 요청이 빠른 모드를 사용했을 때 "fast". 그 외에는 없습니다.
• effort: 요청에 적용된 노력 수준: "low", "medium", "high", "xhigh", 또는 "max". 모델이 노력을 지원하지 않을 때는 없습니다.
• agent.name: 요청을 발급한 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다. 다른 사용자 정의 에이전트 이름은 "custom"으로 대체됩니다. 요청이 명명된 하위 에이전트 유형에 의해 발급되지 않았을 때는 없습니다.
• skill.name: 요청에 대해 활성화된 스킬(Skill 도구, / 명령, 또는 생성된 하위 에이전트에 의해 상속됨으로 설정됨). 기본 제공, 번들, 사용자 정의, 및 공식 마켓플레이스 플러그인 스킬 이름은 그대로 나타납니다. 타사 플러그인 스킬 이름은 "third-party"로 대체됩니다. 활성 스킬이 없을 때는 없습니다.
• plugin.name: 활성 스킬 또는 하위 에이전트가 플러그인에 의해 제공될 때의 소유 플러그인. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다. 타사 플러그인 이름은 "third-party"로 대체됩니다. 스킬과 하위 에이전트 모두 소유 플러그인을 가지지 않을 때는 없습니다.
• marketplace.name: 소유 플러그인이 설치된 마켓플레이스. 공식 마켓플레이스 플러그인에 대해서만 내보냅니다. 그 외에는 없습니다.
• mcp_server.name: 이 요청이 소비한 도구 결과의 MCP 서버. 기본 제공, claude.ai 프록시, 및 공식 레지스트리 서버 이름은 그대로 나타납니다. 사용자 구성 서버 이름은 "custom"으로 대체됩니다. 요청이 MCP 도구 결과를 소비하지 않았을 때는 없습니다. v2.1.222 이전에는 Claude Code가 MCP 도구 호출 후 모든 요청에 이 속성을 설정했으며, 도구 결과를 소비한 요청에만 설정하지 않았으므로 이를 집계하는 대시보드는 업그레이드 후 단계적 감소를 보여줍니다.
• mcp_tool.name: 이 요청이 소비한 도구 결과의 MCP 도구(MCP 서버 이름과 동일한 수정 및 버전 동작 포함). 요청이 MCP 도구 결과를 소비하지 않았을 때는 없습니다.

토큰 카운터

각 API 요청 후 증가합니다.

속성:

• 모든 표준 속성
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: 모델 식별자(예: "claude-sonnet-5")
• query_source: 요청을 발급한 하위 시스템의 범주. "main", "subagent", 또는 "auxiliary" 중 하나입니다.
• speed: 요청이 빠른 모드를 사용했을 때 "fast". 그 외에는 없습니다.
• effort: 요청에 적용된 노력 수준. 세부 정보는 비용 카운터를 참조하세요.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: 요청에 대한 스킬, 플러그인, 에이전트, 및 MCP 속성. 정의 및 수정 동작은 비용 카운터를 참조하세요.

코드 편집 도구 결정 카운터

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

속성:

• 모든 표준 속성
• 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"을 반환합니다.

활성 시간 카운터

유휴 시간을 제외하고 Claude Code를 적극적으로 사용하는 실제 시간을 추적합니다. 이 메트릭은 입력 및 응답 읽기와 같은 사용자 상호 작용 중, 그리고 도구 실행 및 AI 응답 생성과 같은 CLI 처리 중에 증가합니다.

속성:

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

이벤트

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

이벤트 상관 속성

사용자가 프롬프트를 제출하면 Claude Code는 여러 API 호출을 수행하고 여러 도구를 실행할 수 있습니다. prompt.id 속성을 사용하면 이러한 모든 이벤트를 이를 트리거한 단일 프롬프트에 연결할 수 있습니다.

단일 프롬프트로 트리거된 모든 활동을 추적하려면 특정 prompt.id 값으로 이벤트를 필터링하세요. 이는 user_prompt 이벤트, 모든 api_request 이벤트, 및 해당 프롬프트 처리 중에 발생한 모든 tool_result 이벤트를 반환합니다.

event.sequence는 Claude Code 프로세스가 시작될 때마다 0에서 시작하고 해당 프로세스의 수명 동안 계속 증가합니다. /clear를 통해 계속 계산되며, 이는 새로운 session.id를 할당합니다. 세션을 포크하지 않고 재개하면, 세션은 session.id를 유지하지만 세션을 재개한 프로세스에서 event.sequence 값을 가져오므로, 한 세션 내에서 나중의 이벤트가 이전 이벤트보다 낮은 값을 전달하거나 하나를 반복할 수 있습니다. 세션의 이벤트를 순서대로 정렬하려면 event.timestamp로 정렬하고 동일한 타임스탬프를 공유하는 이벤트를 순서대로 정렬하려면 event.sequence를 사용하세요.

메시지 수준 재구성의 경우, 각 이벤트 클래스는 세션 트랜스크립트의 필드와 일치하는 키를 전달합니다. 트랜스크립트 항목 형식은 Claude Code 내부이며 버전 간에 변경되므로, 이러한 필드에 조인하는 파이프라인은 모든 릴리스에서 중단될 수 있습니다. 조인을 안정적인 계약이 아닌 버전별 조인으로 취급하세요:

• user_prompt 및 assistant_response의 message.uuid
• API 이벤트의 request_id(트랜스크립트의 어시스턴트 항목에 requestId로 저장됨)
• tool_result 및 tool_decision 이벤트의 tool_use_id

사용자 프롬프트 이벤트

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

이벤트 이름: claude_code.user_prompt

속성:

• 모든 표준 속성
• event.name: "user_prompt"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• prompt_length: 프롬프트의 길이
• prompt: 프롬프트 내용. 기본적으로 수정됨. OTEL_LOG_USER_PROMPTS=1을 설정하여 포함시킵니다.
• message.uuid: 저장된 트랜스크립트 항목과 일치하는 결과 사용자 메시지의 UUID입니다. 명령 디스패치에는 없습니다(0개 이상의 메시지를 생성할 수 있음). Claude Code v2.1.214 이상 필요
• command_name: 프롬프트가 명령을 호출할 때의 명령 이름. compact 또는 debug와 같은 기본 제공 및 번들 명령 이름은 그대로 내보냅니다. reset과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냅니다. 사용자 정의, 플러그인, 및 MCP 명령 이름은 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 custom 또는 mcp로 축소됩니다.
• command_source: 명령이 있을 때의 명령 출처: builtin, custom, 또는 mcp. 플러그인 제공 명령은 custom으로 보고합니다.

어시스턴트 응답 이벤트

텍스트 콘텐츠를 모델에서 반환하는 각 API 요청 후 기록됩니다. 응답의 텍스트 블록만 포함됩니다. 사고 블록 및 도구 사용 블록은 제외됩니다. Claude Code v2.1.193 이상 필요.

이벤트 이름: claude_code.assistant_response

속성:

• 모든 표준 속성
• event.name: "assistant_response"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• response_length: 응답 텍스트의 길이(문자)
• response: 응답 텍스트(콘텐츠 제한(기본값 60KB)에서 잘림). 기본적으로 <REDACTED>로 수정됨. OTEL_LOG_ASSISTANT_RESPONSES=1을 설정하여 포함시킵니다. OTEL_LOG_ASSISTANT_RESPONSES가 설정되지 않으면 OTEL_LOG_USER_PROMPTS가 대신 제어하므로, 프롬프트 로깅이 켜져 있는 동안 응답을 수정된 상태로 유지하려면 OTEL_LOG_ASSISTANT_RESPONSES=0을 설정하세요.
• model: 모델 식별자(예: "claude-sonnet-5")
• request_id: 응답의 request-id 헤더에서 Anthropic API 요청 ID. API가 반환할 때만 있습니다.
• message.uuid: 응답의 최종 트랜스크립트 항목의 UUID입니다. API 응답은 콘텐츠 블록당 하나의 트랜스크립트 항목으로 저장됩니다. 이것은 마지막 항목이며, 다음 턴의 parentUuid가 이로부터 체인됩니다. Claude Code v2.1.214 이상 필요
• query_source: 요청을 발급한 하위 시스템(예: "repl_main_thread", "compact", 또는 하위 에이전트 이름)

도구 결과 이벤트

도구 실행이 완료될 때 기록됩니다. 도구 호출이 거부된 경우 내보내지 않습니다. 거부에 대해서는 도구 결정 이벤트를 참조하세요.

이벤트 이름: claude_code.tool_result

속성:

• 모든 표준 속성
• event.name: "tool_result"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• tool_name: 도구의 이름
• tool_use_id: 이 도구 호출의 고유 식별자. 훅에 전달된 tool_use_id와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.
• success: "true" 또는 "false"
• duration_ms: 실행 시간(밀리초)
• error_type: 도구가 실패했을 때의 오류 범주 문자열(예: "Error:ENOENT" 또는 "ShellError")
• error (OTEL_LOG_TOOL_DETAILS=1일 때): 도구가 실패했을 때의 전체 오류 메시지
• decision_type: 항상 "accept"(이 이벤트는 도구 실행 후에만 내보내짐). 거부된 호출은 도구 결과를 생성하지 않습니다.
• decision_source: 권한 결정이 어디서 나왔는지. "config", "hook", "user_permanent", 또는 "user_temporary" 중 하나입니다. 각 값의 의미는 도구 결정 이벤트를 참조하세요. 거부 전용 소스 "user_abort" 및 "user_reject"는 이 이벤트에 나타나지 않습니다.
• tool_input_size_bytes: JSON 직렬화된 도구 입력의 크기(바이트)
• tool_result_size_bytes: 도구 결과의 크기(바이트)
• mcp_server_scope: MCP 서버 범위 식별자(MCP 도구의 경우)
• vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type (OTEL_LOG_TOOL_DETAILS=1일 때): Bash 또는 PowerShell 도구에 의해 실행된 성공적인 git commit의 커밋 ID. vcs.ref.head.revision은 커밋 SHA이고, vcs.ref.head.name은 커밋된 브랜치이며, vcs.ref.head.type은 branch입니다. 커밋이 분리된 HEAD에서 이루어졌을 때 이름과 유형은 생략됩니다. Claude Code v2.1.269 이상 필요
• tool_parameters (OTEL_LOG_TOOL_DETAILS=1일 때): 도구별 매개변수를 포함하는 JSON 문자열. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 mcp_server_name/mcp_tool_name 쌍은 플래그 없이도 포함됩니다. 이는 도구 결정 이벤트와 동일한 호스트 작성 예외입니다. Claude Code v2.1.214 이상 필요. 매개변수는 도구에 따라 다릅니다:
  • Bash 도구의 경우: bash_command, full_command, timeout, description, dangerouslyDisableSandbox, 및 git_commit_id와 git_branch(git commit 명령이 성공할 때)를 포함합니다. git_commit_id는 커밋이 세션의 작업 디렉토리의 HEAD일 때 전체 커밋 SHA이고, 그 외에는 git의 축약된 SHA입니다. git_branch는 커밋된 브랜치이며, 분리된 HEAD에서는 생략됩니다.
  • 데스크톱 앱의 작업 공간 Bash 도구(또한 tool_name을 Bash로 보고함): bash_command, full_command, 및 timeout만 포함합니다.
  • MCP 도구의 경우: mcp_server_name, mcp_tool_name을 포함합니다.
  • Skill 도구의 경우: skill_name을 포함합니다.
  • Agent 도구 또는 레거시 Task 도구의 경우: subagent_type을 포함합니다.
• tool_input (OTEL_LOG_TOOL_DETAILS=1일 때): JSON 직렬화된 도구 인수. 512자를 초과하는 개별 값은 잘리고, 전체 페이로드는 약 4K 문자로 제한됩니다. MCP 도구를 포함한 모든 도구에 적용됩니다.

API 요청 이벤트

Claude에 대한 각 API 요청에 대해 기록됩니다.

이벤트 이름: claude_code.api_request

속성:

• 모든 표준 속성
• event.name: "api_request"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• model: 사용된 모델(예: "claude-sonnet-5")
• cost_usd: USD 단위의 예상 비용
• cost_usd_micros: 미국 달러의 백만분의 일 단위의 예상 비용(정수로 내보냄)
• duration_ms: 요청 지속 시간(밀리초)
• input_tokens: 입력 토큰 수
• output_tokens: 출력 토큰 수
• cache_read_tokens: 캐시에서 읽은 토큰 수
• cache_creation_tokens: 캐시 생성에 사용된 토큰 수
• request_id: 응답의 request-id 헤더에서 Anthropic API 요청 ID(예: "req_011..."). API가 반환할 때만 있습니다.
• client_request_id: x-client-request-id 요청 헤더로 전송된 클라이언트 생성 UUID. 있을 때에 대해서는 이벤트 상관 속성 표를 참조하세요. Claude Code v2.1.214 이상 필요
• speed: "fast" 또는 "normal"(빠른 모드가 활성화되었는지 여부를 나타냄)
• query_source: 요청을 발급한 하위 시스템(예: "repl_main_thread", "compact", 또는 하위 에이전트 이름)
• effort: 요청에 적용된 노력 수준: "low", "medium", "high", "xhigh", 또는 "max". 모델이 노력을 지원하지 않을 때는 없습니다.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: 요청에 대한 스킬, 플러그인, 에이전트, 및 MCP 속성. 정의 및 수정 동작은 비용 카운터를 참조하세요.

API 오류 이벤트

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

이벤트 이름: claude_code.api_error

속성:

• 모든 표준 속성
• event.name: "api_error"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• model: 사용된 모델(예: "claude-sonnet-5")
• error: 오류 메시지
• status_code: HTTP 상태 코드(숫자). 연결 실패와 같은 비HTTP 오류의 경우 없습니다.
• duration_ms: 요청 지속 시간(밀리초)
• attempt: 초기 요청을 포함한 총 시도 횟수(1은 재시도가 발생하지 않았음을 의미)
• request_id: 응답의 request-id 헤더에서 Anthropic API 요청 ID(예: "req_011..."). API가 반환할 때만 있습니다.
• client_request_id: x-client-request-id 요청 헤더로 전송된 클라이언트 생성 UUID. 타임아웃 또는 연결 오류와 같은 실패가 서버 request_id를 생성하지 않은 경우에도 사용 가능합니다. 있을 때에 대해서는 이벤트 상관 속성 표를 참조하세요. Claude Code v2.1.214 이상 필요
• speed: "fast" 또는 "normal"(빠른 모드가 활성화되었는지 여부를 나타냄)
• query_source: 요청을 발급한 하위 시스템(예: "repl_main_thread", "compact", 또는 하위 에이전트 이름)
• effort: 요청에 적용된 노력 수준. 모델이 노력을 지원하지 않을 때는 없습니다.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: 요청에 대한 스킬, 플러그인, 에이전트, 및 MCP 속성. 정의 및 수정 동작은 비용 카운터를 참조하세요.

API 거부 이벤트

API 요청이 stop_reason: "refusal"을 반환할 때 기록됩니다. 거부는 HTTP 오류가 아닌 성공적인 응답 스트림에 도착하므로 api_error 이벤트는 이에 대해 발생하지 않습니다. 이 이벤트를 사용하면 거부 빈도를 추적하고 거부를 api_request 및 api_error와 동일한 속성으로 그룹화할 수 있습니다.

이벤트 이름: claude_code.api_refusal

속성:

• 모든 표준 속성
• event.name: "api_refusal"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• model: 요청의 모델 식별자
• request_id: 응답의 request-id 헤더에서 Anthropic API 요청 ID(예: "req_011..."). API가 반환할 때만 있습니다.
• query_source: 요청을 발급한 하위 시스템(예: "repl_main_thread", "compact", 또는 하위 에이전트 이름). 정의는 api_request를 참조하세요.
• speed: 빠른 모드가 활성화되었을 때 "fast", 또는 "normal"
• attempt: 재시도 시도 번호. 첫 번째 시도는 1입니다.
• effort: 요청에 적용된 노력 수준. 모델이 노력을 지원하지 않을 때는 없습니다.
• server_fallback_hop: API의 서버 측 모델 폴백이 이미 이 거부를 다른 모델에서 재시도했으므로 사용자가 이 특정 거부를 보지 못했을 때 true. 요청이 거부로 끝났을 때 false. 단일 턴은 폴백 모델도 거부할 때 나중의 false 최종 이벤트와 true 홉 이벤트를 모두 내보낼 수 있습니다.
• has_category: API 응답이 "cyber", "bio", "frontier_llm", 또는 "reasoning_extraction"의 stop_details.category를 전달했을 때 true. 응답이 범주를 전달하지 않았거나 해당 집합 외의 값을 전달했을 때 false. server_fallback_hop이 true일 때는 없습니다(홉 블록은 stop_details를 전달하지 않음).
• has_explanation: API 응답이 stop_details.explanation을 전달했을 때 true, 그 외에는 false. server_fallback_hop이 true일 때는 없습니다.
• category: API 응답의 stop_details.category 값. "cyber", "bio", "frontier_llm", 또는 "reasoning_extraction" 중 하나. OTEL_LOG_TOOL_DETAILS=1이 설정되고 has_category가 true일 때만 있습니다.
• agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name: 요청에 대한 스킬, 플러그인, 에이전트, 및 MCP 속성. 정의 및 수정 동작은 비용 카운터를 참조하세요.

API 요청 본문 이벤트

OTEL_LOG_RAW_API_BODIES가 설정되었을 때 각 API 요청 시도에 대해 기록됩니다. 시도당 하나의 이벤트가 내보내지므로 조정된 매개변수를 사용한 재시도는 각각 자신의 이벤트를 생성합니다.

이벤트 이름: claude_code.api_request_body

속성:

• 모든 표준 속성
• event.name: "api_request_body"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• body: JSON 직렬화된 Messages API 요청 매개변수(예: 시스템 프롬프트, 메시지, 및 도구)(콘텐츠 제한(기본값 60KB)에서 잘림). 이전 어시스턴트 턴의 확장 사고 콘텐츠는 수정됩니다. 인라인 모드(OTEL_LOG_RAW_API_BODIES=1)에서만 내보냅니다.
• body_ref: 잘리지 않은 본문을 포함하는 <dir>/<uuid>.request.json 파일의 절대 경로. 파일 모드(OTEL_LOG_RAW_API_BODIES=file:<dir>)에서만 내보냅니다.
• body_length: 잘리지 않은 본문 길이. OTEL_LOG_RAW_API_BODIES=file:<dir>일 때 UTF-8 바이트, 또는 =1일 때 UTF-16 코드 단위
• body_truncated: 인라인 잘림이 발생했을 때 "true". 파일 모드 및 잘림이 발생하지 않았을 때는 없습니다.
• model: 요청 매개변수의 모델 식별자
• query_source: 요청을 발급한 하위 시스템(예: "compact")

API 응답 본문 이벤트

OTEL_LOG_RAW_API_BODIES가 설정되었을 때 각 성공적인 API 응답에 대해 기록됩니다.

이벤트 이름: claude_code.api_response_body

속성:

• 모든 표준 속성
• event.name: "api_response_body"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• body: JSON 직렬화된 Messages API 응답(id, 콘텐츠 블록, 사용량, 및 중지 이유 포함)(콘텐츠 제한(기본값 60KB)에서 잘림). 확장 사고 콘텐츠는 수정됩니다. 인라인 모드(OTEL_LOG_RAW_API_BODIES=1)에서만 내보냅니다.
• body_ref: 잘리지 않은 본문을 포함하는 <dir>/<request_id>.response.json 파일의 절대 경로. 파일 모드(OTEL_LOG_RAW_API_BODIES=file:<dir>)에서만 내보냅니다.
• body_length: 잘리지 않은 본문 길이. OTEL_LOG_RAW_API_BODIES=file:<dir>일 때 UTF-8 바이트, 또는 =1일 때 UTF-16 코드 단위
• body_truncated: 인라인 잘림이 발생했을 때 "true". 파일 모드 및 잘림이 발생하지 않았을 때는 없습니다.
• model: 모델 식별자
• query_source: 요청을 발급한 하위 시스템
• request_id: 응답의 request-id 헤더에서 Anthropic API 요청 ID(예: "req_011..."). API가 반환할 때만 있습니다.

도구 결정 이벤트

도구 권한 결정(수락/거부)이 내려질 때 기록됩니다.

이벤트 이름: claude_code.tool_decision

속성:

• 모든 표준 속성
• event.name: "tool_decision"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• tool_name: 도구의 이름(예: "Read", "Edit", "Write", "NotebookEdit")
• tool_use_id: 이 도구 호출의 고유 식별자. 훅에 전달된 tool_use_id와 일치하여 OTel 이벤트와 훅 캡처 데이터 간의 상관 관계를 허용합니다.
• decision: "accept" 또는 "reject"
• tool_source: 항상 있습니다. 도구의 출처(CLI 작성 값의 폐쇄 집합). Claude Code v2.1.214 이상 필요
  • "builtin": CLI 자체의 도구
  • "mcp": 일반적으로 MCP 서버
  • "sdk_host_builtin_mcp": Claude Desktop 자체에 내장된 프로세스 내 서버(Claude Desktop이 소유한 세션). Claude Desktop은 자신의 진입점 중 하나(claude-desktop, claude-desktop-3p, 또는 local-agent)에서 시작한 세션을 소유합니다. 중첩된 자식이 아닐 때(Claude Code 자체가 생성하는 세션을 포함한 중첩된 세션은 이러한 서버를 "mcp"로 보고).
• source: 결정이 어디서 나왔는지:
  • "config": 프롬프트 없이 자동으로 결정됨. 프로젝트 설정, 사용자의 개인 설정의 허용 또는 거부 규칙, 엔터프라이즈 관리 정책, --allowedTools 또는 --disallowedTools 플래그, 활성 권한 모드, 동일한 대화형 CLI 세션의 이전 프롬프트에서의 세션 범위 부여, 또는 도구가 본질적으로 안전하기 때문입니다. 이벤트는 이러한 소스 중 어느 것이 일치했는지 나타내지 않습니다. Claude Code는 또한 권한 프롬프트 요청 자체가 실패할 때 "config"을 보고합니다. 예를 들어 Agent SDK의 canUseTool 콜백 또는 --permission-prompt-tool 도구가 잘못된 결과를 반환하거나 입력 스트림이 요청 대기 중에 닫힐 때입니다. v2.1.216 이전에는 Claude Code가 이러한 실패를 "user_reject"로 보고했습니다.
  • "hook": PreToolUse 또는 PermissionRequest 훅이 결정을 반환했습니다.
  • "user_permanent": 사용자가 권한 프롬프트에서 "Yes, and don't ask again for ..."을 선택했을 때 내보내집니다. 이는 개인 설정에 허용 규칙을 저장합니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내집니다. 나중의 호출이 저장된 규칙과 일치하면 "config"을 내보냅니다. Agent SDK 또는 비대화형 -p 세션에서는 초기 선택과 나중의 규칙 일치 모두 "user_permanent"를 내보냅니다. 수락으로 취급됩니다.
  • "user_temporary": 사용자가 권한 프롬프트에서 "Yes"를 선택했거나 파일 편집 또는 읽기 프롬프트에서 세션의 나머지 부분에 대한 액세스를 부여하는 옵션을 선택했을 때 내보내집니다. 대화형 CLI에서는 선택 자체에 대해서만 내보내집니다. 나중의 호출이 해당 세션 범위 부여와 일치하면 "config"을 내보냅니다. Agent SDK 또는 비대화형 -p 세션에서는 선택과 나중의 일치 모두 "user_temporary"를 내보냅니다. 수락으로 취급됩니다.
  • "user_abort": 사용자가 답변 없이 권한 프롬프트를 해제했을 때 내보내집니다. Agent SDK 및 비대화형 -p 세션에서는 canUseTool 또는 --permission-prompt-tool 권한 요청이 대기 중일 때 턴을 중단하는 것을 포함합니다. v2.1.216 이전에는 Claude Code가 해당 중단을 "user_reject"로 보고했습니다. 거부로 취급됩니다.
  • "user_reject": 사용자가 프롬프트에서 "No"를 선택했을 때 내보내집니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내집니다. 사용자의 개인 설정의 거부 규칙과 일치하는 호출은 "config"을 내보냅니다. Agent SDK 또는 비대화형 -p 세션에서는 개인 설정의 거부 규칙과 일치하는 호출이 "user_reject"를 내보냅니다. 거부로 취급됩니다.
• tool_parameters (OTEL_LOG_TOOL_DETAILS=1일 때): 도구별 매개변수를 포함하는 JSON 문자열. 도구 결과 이벤트와 동일한 형태이지만 git_commit_id와 같은 실행 후 필드는 제외됩니다. 권한 결정이 updatedInput을 통해 도구 입력을 다시 쓸 경우 수락된 호출의 tool_result와 값이 다를 수 있습니다. 이 속성을 사용하여 decision이 "reject"일 때 어떤 명령이 거부되었는지 확인하세요.
  • "sdk_host_builtin_mcp" 도구의 경우: mcp_server_name 및 mcp_tool_name은 OTEL_LOG_TOOL_DETAILS가 꺼져 있어도 포함됩니다. 호스트 애플리케이션이 이러한 이름을 정의하기 때문입니다. 이들이 없으면 이러한 기본 제공 서버 중 하나에 대한 거부된 호출은 기본 스트림에서 속성을 지정할 수 없습니다. 사용자 구성 MCP 서버의 경우, 이벤트의 tool_name은 항상 리터럴 "mcp_tool"이고, 서버 및 도구 이름은 플래그가 켜져 있을 때만 tool_parameters에 나타납니다. 인수 콘텐츠는 모든 곳에서 플래그가 필요합니다. Claude Code v2.1.214 이상 필요
  • Bash 도구의 경우: bash_command, full_command, timeout, description, dangerouslyDisableSandbox를 포함합니다. 데스크톱 앱의 작업 공간 bash 도구도 tool_name을 Bash로 보고하지만 bash_command, full_command, 및 timeout만 포함합니다.
  • MCP 도구의 경우: mcp_server_name, mcp_tool_name을 포함합니다.
  • Skill 도구의 경우: skill_name을 포함합니다.
  • Agent 도구 또는 레거시 Task 도구의 경우: subagent_type을 포함합니다.

권한 모드 변경 이벤트

권한 모드가 변경될 때 기록됩니다. 예를 들어 Shift+Tab 순환, 계획 모드 종료, 또는 자동 모드 게이트 확인에서.

이벤트 이름: claude_code.permission_mode_changed

속성:

• 모든 표준 속성
• event.name: "permission_mode_changed"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• from_mode: 이전 권한 모드(예: "default", "plan", "acceptEdits", "auto", 또는 "bypassPermissions")
• to_mode: 새 권한 모드
• trigger: 변경을 야기한 것. "shift_tab", "exit_plan_mode", "auto_gate_denied", 또는 "auto_opt_in" 중 하나. SDK 또는 브리지에서 전환이 시작될 때는 없습니다.

인증 이벤트

/login 또는 /logout이 완료될 때 기록됩니다.

이벤트 이름: claude_code.auth

속성:

• 모든 표준 속성
• event.name: "auth"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• action: "login" 또는 "logout"
• success: "true" 또는 "false"
• auth_method: 인증 방법(예: "oauth")
• error_category: 작업이 실패했을 때의 범주별 오류 종류. 원본 오류 메시지는 절대 포함되지 않습니다.
• status_code: 작업이 HTTP 오류로 실패했을 때의 HTTP 상태 코드(문자열)

MCP 서버 연결 이벤트

MCP 서버가 연결, 연결 해제, 또는 연결 실패할 때 기록됩니다.

이벤트 이름: claude_code.mcp_server_connection

속성:

• 모든 표준 속성
• event.name: "mcp_server_connection"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• status: "connected", "failed", 또는 "disconnected"
• transport_type: 서버 전송(예: "stdio", "sse", 또는 "http")
• server_scope: 서버가 구성된 범위(예: "user", "project", 또는 "local")
• duration_ms: 연결 시도 지속 시간(밀리초)
• error_code: 연결이 실패했을 때의 오류 코드
• is_plugin: 서버가 플러그인에 의해 제공될 때 true, 그 외에는 false
• plugin_id_hash (is_plugin이 true일 때): 플러그인 이름과 마켓플레이스의 안정적인 해시(이름을 노출하지 않고 플러그인별로 이벤트를 그룹화하기 위해). Claude Code는 플러그인 로드 이벤트 아래에 설명된 대로 계산합니다.
• plugin.name (is_plugin이 true일 때): 서버를 제공하는 플러그인의 이름. 타사 플러그인의 경우 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 리터럴 문자열 "third-party"입니다. 이는 기본적으로 로그에 타사 플러그인 이름이 나타나는 것을 방지합니다. 공식 Anthropic 소스의 플러그인은 항상 이름으로 식별됩니다. plugin_id_hash 및 plugin.name 속성은 자신의 모니터링 백엔드로 흐르며 Anthropic으로 전송되지 않습니다.
• server_name (OTEL_LOG_TOOL_DETAILS=1일 때): 구성된 서버 이름
• error (OTEL_LOG_TOOL_DETAILS=1일 때): 연결이 실패했을 때의 전체 오류 메시지

내부 오류 이벤트

Claude Code가 예상치 못한 내부 오류를 포착할 때 기록됩니다. 오류 클래스 이름과 errno 스타일 코드만 기록됩니다. 오류 메시지와 스택 추적은 절대 포함되지 않습니다. 이 이벤트는 Amazon Bedrock, Google Cloud의 Agent Platform, 또는 Microsoft Foundry에 대해 실행 중이거나 DISABLE_ERROR_REPORTING이 설정되었을 때 내보내지지 않습니다.

이벤트 이름: claude_code.internal_error

속성:

• 모든 표준 속성
• event.name: "internal_error"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• error_name: 오류 클래스 이름(예: "TypeError" 또는 "SyntaxError")
• error_code: 오류에 있을 때의 Node.js errno 코드(예: "ENOENT")

플러그인 설치 이벤트

플러그인이 설치를 완료할 때 기록됩니다. claude plugin install CLI 명령과 대화형 /plugin UI 모두에서.

이벤트 이름: claude_code.plugin_installed

속성:

• 모든 표준 속성
• event.name: "plugin_installed"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• marketplace.is_official: 마켓플레이스가 공식 Anthropic 마켓플레이스일 때 "true", 그 외에는 "false"
• install.trigger: "cli" 또는 "ui"
• plugin.name: 설치된 플러그인의 이름. 타사 마켓플레이스의 경우 OTEL_LOG_TOOL_DETAILS=1일 때만 포함됩니다.
• plugin.version: 마켓플레이스 항목에서 선언된 플러그인 버전. 타사 마켓플레이스의 경우 OTEL_LOG_TOOL_DETAILS=1일 때만 포함됩니다.
• marketplace.name: 플러그인이 설치된 마켓플레이스. 타사 마켓플레이스의 경우 OTEL_LOG_TOOL_DETAILS=1일 때만 포함됩니다.

플러그인 로드 이벤트

세션 시작 시 활성화된 플러그인당 한 번 기록됩니다. 이 이벤트를 사용하여 플릿 전체에서 활성화된 플러그인을 인벤토리하세요. plugin_installed는 설치 작업 자체를 기록하는 보완입니다.

이벤트 이름: claude_code.plugin_loaded

속성:

• 모든 표준 속성
• event.name: "plugin_loaded"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• plugin.name: 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 "third-party"입니다.
• marketplace.name: 플러그인이 설치된 마켓플레이스(알려진 경우). plugin.name과 동일한 조건에서 "third-party"로 수정됩니다.
• plugin.version: 플러그인 매니페스트의 버전. 이름이 수정되지 않고 매니페스트가 버전을 선언할 때만 포함됩니다.
• plugin.scope: 플러그인의 출처 범주: "official", "community", "org", "user-local", 또는 "default-bundle"
• enabled_via: 플러그인이 활성화되도록 된 방식: "default-enable", "org-policy", "admin-install", "seed-mount", 또는 "user-install". "admin-install" 값은 플러그인이 조직 설정 > 플러그인에서 조직에 대해 필수 또는 자동 설치로 설정되어 있음을 의미합니다. v2.1.246 이전에는 Claude Code가 이러한 플러그인을 "user-install" 또는 "seed-mount"로 보고했습니다.
• plugin_id_hash: 플러그인 이름과 마켓플레이스의 결정적 해시(구성된 내보내기로만 전송됨). 이름을 기록하지 않고 플릿 전체에서 로드된 서로 다른 타사 플러그인을 계산할 수 있습니다. claude.ai에서 동기화된 플러그인의 경우, Claude Code는 플러그인 이름을 claude.ai가 플러그인에 대해 보고하는 마켓플레이스 이름과 함께 해시하거나, 그 외에는 synced와 함께 해시합니다. v2.1.246 이전에는 Claude Code가 해시에서 claude.ai가 보고하는 마켓플레이스 이름을 사용하지 않았습니다.
• has_hooks: 플러그인이 훅을 제공하는지 여부
• has_mcp: 플러그인이 MCP 서버를 제공하는지 여부
• host_owned_mcp: SDK 호스트가 이 플러그인의 MCP 연결을 관리하고 Claude Code가 플러그인의 MCP 서버 구성 읽기를 건너뛸 때 true, 그 외에는 false. Claude Code v2.1.172 이상 필요
• skill_path_count: 플러그인이 선언하는 스킬 디렉토리 수
• command_path_count: 플러그인이 선언하는 명령 디렉토리 수
• agent_path_count: 플러그인이 선언하는 에이전트 디렉토리 수
• safe_mode: 세션이 --safe-mode로 시작되었을 때 "true", 그 외에는 "false". 안전 모드에서 이 이벤트는 구성된 인벤토리만 보고합니다. 플러그인의 명령, 스킬, 훅, 및 MCP 서버는 로드되지 않습니다. Claude Code v2.1.169 이상 필요

스킬 활성화 이벤트

스킬이 호출될 때 기록됩니다. Claude가 Skill 도구를 통해 호출하든 / 명령으로 실행하든.

이벤트 이름: claude_code.skill_activated

속성:

• 모든 표준 속성
• event.name: "skill_activated"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• skill.name: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 플레이스홀더 "custom_skill"입니다.
• invocation_trigger: 스킬이 트리거된 방식("user-slash", "claude-proactive", 또는 "nested-skill")
• skill.source: 스킬이 로드된 위치(예: "bundled", "userSettings", "projectSettings", "plugin")
• skill.kind: 스킬이 워크플로우 스킬일 때 "workflow". 그 외에는 없습니다.
• plugin.name (OTEL_LOG_TOOL_DETAILS=1이거나 플러그인이 공식 마켓플레이스에서 나올 때): 스킬이 플러그인에 의해 제공될 때의 소유 플러그인의 이름
• marketplace.name (OTEL_LOG_TOOL_DETAILS=1이거나 플러그인이 공식 마켓플레이스에서 나올 때): 스킬이 플러그인에 의해 제공될 때, 소유 플러그인이 설치된 마켓플레이스

@ 멘션 이벤트

Claude Code가 프롬프트의 @-멘션을 해결할 때 기록됩니다. 모든 멘션이 이벤트를 내보내는 것은 아닙니다. 권한 거부, 과도한 파일, PDF 참조 첨부, 및 디렉토리 나열 실패와 같은 조기 종료 경로는 로깅 없이 반환됩니다.

이벤트 이름: claude_code.at_mention

속성:

• 모든 표준 속성
• event.name: "at_mention"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• mention_type: 멘션의 유형("file", "directory", "agent", "mcp_resource", "peer"). "peer" 값은 다른 Claude Code 세션 중 하나를 멘션했음을 의미합니다. Claude Code v2.1.232 이상 필요
• success: 멘션이 성공적으로 해결되었는지 여부("true" 또는 "false")

API 재시도 소진 이벤트

API 요청이 둘 이상의 시도 후 실패할 때 한 번 기록됩니다. 최종 api_error 이벤트와 함께 내보내집니다.

이벤트 이름: claude_code.api_retries_exhausted

속성:

• 모든 표준 속성
• event.name: "api_retries_exhausted"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• model: 사용된 모델
• error: 최종 오류 메시지
• status_code: HTTP 상태 코드(숫자). 비HTTP 오류의 경우 없습니다.
• total_attempts: 수행된 총 시도 횟수
• total_retry_duration_ms: 모든 시도에 걸친 총 벽시계 시간
• speed: "fast" 또는 "normal"

훅 등록 이벤트

세션 시작 시 구성된 훅당 한 번 기록됩니다. 이 이벤트를 사용하여 플릿 전체에서 활성화된 훅을 인벤토리하세요. 실행별 hook_execution_start 및 hook_execution_complete 이벤트를 보완합니다.

이벤트 이름: claude_code.hook_registered

속성:

• 모든 표준 속성
• event.name: "hook_registered"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• hook_event: 훅 이벤트 유형(예: "PreToolUse" 또는 "PostToolUse")
• hook_type: 훅 구현 유형: "command", "prompt", "mcp_tool", "http", 또는 "agent"
• hook_source: 훅이 정의된 위치: "userSettings", "projectSettings", "localSettings", "flagSettings", "policySettings", 또는 "pluginHook"
• safe_mode: 세션이 --safe-mode로 시작되었을 때 "true", 그 외에는 "false". Claude Code v2.1.169 이상 필요
• hook_matcher (OTEL_LOG_TOOL_DETAILS=1일 때): 훅 구성에서 설정된 경우의 매처 문자열
• plugin.name (hook_source가 "pluginHook"일 때): 기여하는 플러그인의 이름. 공식 마켓플레이스 및 기본 제공 번들 외부의 플러그인의 경우 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 "third-party"입니다.
• plugin_id_hash (hook_source가 "pluginHook"일 때): 플러그인 이름과 마켓플레이스의 결정적 해시(구성된 내보내기로만 전송됨). 이름을 기록하지 않고 기여하는 서로 다른 플러그인을 계산할 수 있습니다. Claude Code는 플러그인 로드 이벤트 아래에 설명된 대로 계산합니다.

훅 실행 시작 이벤트

하나 이상의 훅이 훅 이벤트에 대해 실행을 시작할 때 기록됩니다.

이벤트 이름: claude_code.hook_execution_start

속성:

• 모든 표준 속성
• event.name: "hook_execution_start"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• hook_event: 훅 이벤트 유형(예: "PreToolUse" 또는 "PostToolUse")
• hook_name: 매처를 포함한 전체 훅 이름(예: "PreToolUse:Write")
• num_hooks: 일치하는 훅 명령 수
• managed_only: 관리 정책 훅만 허용될 때 "true"
• hook_source: "policySettings" 또는 "merged"
• safe_mode: 세션이 --safe-mode로 시작되었을 때 "true", 그 외에는 "false". Claude Code v2.1.169 이상 필요
• hook_definitions: JSON 직렬화된 훅 구성. 상세 베타 추적과 OTEL_LOG_TOOL_DETAILS=1이 모두 활성화되었을 때만 포함됨

훅 실행 완료 이벤트

훅 이벤트의 모든 훅이 완료되었을 때 기록됩니다.

이벤트 이름: claude_code.hook_execution_complete

속성:

• 모든 표준 속성
• event.name: "hook_execution_complete"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• hook_event: 훅 이벤트 유형
• hook_name: 매처를 포함한 전체 훅 이름
• num_hooks: 일치하는 훅 명령 수
• num_success: 성공적으로 완료된 수
• num_blocking: 차단 결정을 반환한 수
• num_non_blocking_error: 차단 없이 실패한 수
• num_cancelled: 완료 전에 취소된 수
• total_duration_ms: 모든 일치하는 훅의 벽시계 지속 시간
• managed_only: 관리 정책 훅만 허용될 때 "true"
• hook_source: "policySettings" 또는 "merged"
• safe_mode: 세션이 --safe-mode로 시작되었을 때 "true", 그 외에는 "false". Claude Code v2.1.169 이상 필요
• hook_definitions: JSON 직렬화된 훅 구성. 상세 베타 추적과 OTEL_LOG_TOOL_DETAILS=1이 모두 활성화되었을 때만 포함됨

훅 플러그인 메트릭 이벤트

공식 마켓플레이스 플러그인 훅이 호출별 메트릭을 내보낼 때 기록됩니다. 공식 Anthropic 마켓플레이스에서 설치된 플러그인만 이를 내보낼 수 있습니다. 타사 마켓플레이스 플러그인 및 사용자 구성 훅은 이 이벤트로 내보내지 않습니다. 이 이벤트를 사용하여 자신의 관찰성 스택에서 찾기 비율, 비용, 및 지속 시간과 같은 플러그인 동작을 모니터링하세요.

이벤트 이름: claude_code.hook_plugin_metrics

속성:

• 모든 표준 속성
• event.name: "hook_plugin_metrics"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• plugin_id: <name>@<marketplace> 형식의 플러그인 식별자
• hook_event: 메트릭을 내보낸 훅 이벤트 유형
• 최대 20개의 플러그인 내보낸 메트릭 키. 이름은 ^[a-z][a-z0-9_]{0,39}$와 일치합니다. 값은 부울 또는 숫자입니다.

압축 이벤트

대화 압축이 완료될 때 기록됩니다.

이벤트 이름: claude_code.compaction

속성:

• 모든 표준 속성
• event.name: "compaction"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• trigger: "auto" 또는 "manual"
• success: "true" 또는 "false"
• duration_ms: 압축 지속 시간
• pre_tokens: 압축 전 대략적인 토큰 수
• post_tokens: 압축 후 대략적인 토큰 수
• error: 압축이 실패했을 때의 오류 메시지
• precompute_reuse: trigger가 "manual"일 때만 설정됩니다. 자동 압축은 컨텍스트 윈도우가 채워지기 전에 백그라운드에서 요약을 준비할 수 있으며, 이 속성은 /compact가 해당 준비된 요약을 재사용했는지 기록합니다. "hit"는 재사용되었음을 의미합니다. "miss_custom_instructions", "miss_hook", 및 "miss_not_ready"는 대신 새로운 요약이 계산된 이유를 제공합니다. Claude Code v2.1.153 이상 필요

하위 에이전트 완료 이벤트

하위 에이전트가 완료되고 이를 시작한 대화에 결과를 반환할 때 기록됩니다. 하위 에이전트 유형별로 도구 사용 및 실행 시간을 롤업하는 데 사용하세요. 토큰 또는 비용 롤업의 경우, 이 이벤트의 total_tokens는 최종 요청만 포함하므로 query_source "subagent"로 필터링된 토큰 카운터 및 비용 카운터를 사용하세요. "subagent" 범주는 또한 하위 에이전트 이벤트를 내보내지 않는 에이전트 기반 훅의 요청을 계산합니다.

이벤트 이름: claude_code.subagent_completed

속성:

• 모든 표준 속성
• event.name: "subagent_completed"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• agent_type: 하위 에이전트 유형. 기본 제공 에이전트 이름과 공식 마켓플레이스 플러그인의 에이전트는 그대로 나타납니다. 다른 에이전트 이름은 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 "custom"으로 대체됩니다.
• agent.source: 에이전트 정의가 어디서 나왔는지: built-in, plugin, 또는 userSettings 또는 projectSettings와 같은 사용자 정의 에이전트를 정의한 설정 소스
• is_built_in: 하위 에이전트가 기본 제공 에이전트 유형인지 여부
• is_async: 하위 에이전트가 백그라운드에서 실행되었는지 여부
• total_tokens: 하위 에이전트의 최종 API 요청의 토큰 풋프린트: 해당 하나의 요청의 입력, 캐시 생성, 캐시 읽기, 및 출력 토큰(대략 완료 시 하위 에이전트의 컨텍스트 크기). 실행 전체에 걸친 합계가 아님
• total_tool_uses: 하위 에이전트가 전체 실행에 걸쳐 수행한 도구 호출 수
• duration_ms: 실행 시간(밀리초)
• model: 하위 에이전트가 실행하도록 해결된 모델
• final_model: 하위 에이전트의 최종 응답을 생성한 모델(폴백과 같은 중간 실행 전환 후 model과 다름). Claude Code v2.1.212 이상 필요
• model_swapped: 둘 이상의 모델이 하위 에이전트의 요청을 제공했는지 여부. Claude Code v2.1.212 이상 필요
• plugin_id_hash, plugin.name: 플러그인 제공 에이전트에 대해 있습니다. 공식 마켓플레이스 플러그인 이름은 그대로 나타납니다. 다른 플러그인 이름은 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 "third-party"로 대체됩니다.

피드백 설문 이벤트

세션 품질 설문이 표시되거나 답변될 때 기록됩니다. 설문이 수집하는 것과 이를 제어하는 방법은 세션 품질 설문을 참조하세요.

이벤트 이름: claude_code.feedback_survey

속성:

• 모든 표준 속성
• event.name: "feedback_survey"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• event_type: 설문 생명 주기 이벤트(예: "appeared", "responded", 또는 "transcript_prompt_appeared")
• appearance_id: 하나의 설문 인스턴스에 대해 내보낸 이벤트를 연결하는 고유 ID
• survey_type: 이벤트를 생성한 설문. "session"은 "Claude가 어떻게 하고 있나요?" 평가 프롬프트입니다.
• response: responded 이벤트의 사용자 선택
• enabled_via_override: CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL이 설정되었을 때 true. 부울로 내보내집니다(문자열이 아님). session 설문 이벤트에 있습니다. 이 속성으로 필터링하여 플릿 전체에서 재정의가 적용되었는지 확인하세요.

보존 스윕 이벤트

세션 트랜스크립트 및 기타 애플리케이션 데이터를 cleanupPeriodDays 설정보다 오래된 것을 삭제하는 보존 정리 스윕의 실행당 한 번 기록됩니다. Claude Code는 스윕을 백그라운드에서 세션당 최대 한 번 실행하며, 아무것도 삭제하지 않는 실행도 이벤트를 내보냅니다. Claude Code가 지난 24시간 동안 동일한 머신의 모든 세션에서 스윕을 실행했다면, 이 세션의 스윕을 최소 10분 이상 지연시키므로 더 빨리 종료되는 세션은 아무것도 내보내지 않습니다. claude -p를 --bare로 실행하면 Claude Code는 스윕을 실행하지 않으며 아무것도 내보내지 않습니다.

이 페이지의 모든 OTel 이벤트처럼, 구성한 원격 측정 백엔드로만 이동합니다. Claude Code v2.1.227 이상 필요.

Claude Code가 보존 기간을 안전하게 결정할 수 없을 때, 스윕을 일시 중지하고 result를 "skipped"로 설정하고 skip_reason을 포함하는 이벤트를 내보냅니다. 관리 설정이 cleanupPeriodDays를 설정할 때, 관리 값은 보존 기간을 고정하고 낮은 우선순위 범위의 설정 파일이 손상되거나 유효하지 않아도 스윕이 실행됩니다. managed-settings.json 자체를 읽을 수 없을 때, Claude Code는 관리 계층이 서버 관리 설정과 같은 다른 곳에서 cleanupPeriodDays를 제공하지 않으면 스윕을 일시 중지합니다. 또는 손상된 파일 옆의 managed-settings.d/ 드롭인. 삭제 카운터 속성은 result가 "complete"일 때만 있습니다.

이벤트 이름: claude_code.retention_sweep

속성:

• 모든 표준 속성
• event.name: "retention_sweep"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 이벤트 순서 지정을 위한 프로세스별 카운터(이벤트 상관 속성에 설명됨)
• result: 스윕이 실행되었을 때 "complete", Claude Code가 일시 중지했을 때 "skipped"
• period_days: 병합된 설정의 cleanupPeriodDays 값(일 단위) 또는 소스가 설정하지 않을 때 30. 건너뛴 이벤트에서, 스윕이 사용했을 값(Claude Code가 읽을 수 있는 설정 소스에서 계산됨)
• used_default: 읽을 수 있는 설정 소스가 cleanupPeriodDays를 설정하지 않을 때 "true", 그 외에는 "false". 완료 이벤트에서, "true"는 30일 기본값이 적용되었음을 의미합니다.
• skip_reason: Claude Code가 스윕을 일시 중지한 이유. result가 "skipped"일 때만 있습니다:
  • "user_source_disabled": 사용자 설정이 제외됩니다(예: --setting-sources 플래그 또는 SDK의 settingSources 옵션에 의해), 그리고 활성화된 소스가 cleanupPeriodDays를 제공하지 않습니다.
  • "settings_unknowable": 설정 파일을 읽거나 구문 분석할 수 없어서 cleanupPeriodDays 또는 desktopSessionCleanupPeriodDays가 Claude Code가 볼 수 없는 값으로 설정될 수 있습니다.
  • "settings_invalid_key_set": 설정에 유효성 검사 오류가 있고 cleanupPeriodDays 또는 desktopSessionCleanupPeriodDays가 명시적으로 설정되어 있어서 기본값으로 폴백하면 해당 설정에 대해 파일을 삭제하거나 유지할 수 있습니다.
• transcripts_deleted: 스윕이 삭제한 세션 트랜스크립트(최상위 ~/.claude/projects/*/*.jsonl 파일) 수
• transcripts_exempted_desktop: 보존 기간을 지난 트랜스크립트 중 스윕이 Claude Desktop 및 Cowork 규칙 아래에서 유지한 수. 이들은 files_past_cutoff에 계산되지 않습니다. Claude Code v2.1.248 이상 필요
• session_files_deleted: 세션 파일 스윕이 삭제한 항목 수: 트랜스크립트 및 사이드카, 녹음, 및 도구 결과와 같은 세션별 동반 파일
• artifacts_deleted: 데이터 디렉토리 전체에서 스윕이 삭제한 총 항목(세션 파일 포함). 일부 스윕은 전체 제거된 디렉토리 트리를 하나의 항목으로 계산하고 몇 가지 정리 통과는 카운터에 기여하지 않으므로, 값을 정확한 파일 수보다는 하한으로 취급하세요.
• files_retained_fresh: 검사되고 보존 기간 내에 있기 때문에 제자리에 남겨진 파일. 파일별 스윕만 이들을 계산하므로 값은 하한입니다. 0이 아닌 값은 정상적인 정상 상태입니다.
• files_past_cutoff: 보존 기간보다 오래되었지만 스윕이 삭제하지 못한 파일(예: 권한 오류 또는 열린 파일). 0보다 큰 값은 파일이 구성된 보존 기간을 초과했음을 의미합니다. 0은 없었다는 증거가 아닙니다. 전체 디렉토리 제거 실패는 대신 error_count에 계산되기 때문입니다.
• error_count: 스윕이 파일을 나열하거나 삭제하는 동안 발생한 오류 수

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

내보낸 메트릭 및 이벤트는 다양한 분석을 지원합니다:

사용 모니터링

비용 모니터링

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

• 팀 또는 개인 전체의 사용 추세 추적
• 최적화를 위한 높은 사용 세션 식별
• skill.name, plugin.name 및 agent.name 속성을 통해 특정 스킬, 플러그인 또는 서브에이전트 유형에 지출 귀속

Claude Code는 ANTHROPIC_BASE_URL 뒤의 게이트웨이 또는 프록시가 여러 프레임에 걸쳐 사용량을 점진적으로 스트리밍할 때를 포함하여 각 스트리밍 응답을 비용 및 토큰 메트릭에 정확히 한 번 계산합니다. v2.1.214 이전에는 둘 이상의 프레임에서 사용량을 전달한 스트림이 추가 프레임당 대략 하나의 추가 전체 요청으로 claude_code.cost.usage 및 claude_code.token.usage를 부풀렸습니다.

경고 및 세분화

일반적인 경고 고려 사항:

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

모든 메트릭은 표준 속성으로 세분화할 수 있습니다. model 속성은 claude_code.token.usage, claude_code.cost.usage에서 사용 가능하며, v2.1.172부터 claude_code.lines_of_code.count에서도 사용 가능합니다.

커밋의 모델별 분류는 한 세션이 여러 모델에 걸쳐 있을 수 있으므로 session.id에서 토큰 또는 비용 메트릭에 대해 조인하여만 근사할 수 있습니다. 토큰 또는 비용 측면을 query_source가 "main"인 행으로 필터링하여 보조 및 서브에이전트 요청이 세션의 커밋을 해당 요청을 수행하지 않은 모델에 귀속시키지 않도록 합니다.

재시도 소진 감지

Claude Code는 실패한 API 요청을 내부적으로 재시도하고 포기한 후에만 단일 claude_code.api_error 이벤트를 내보내므로 이벤트 자체가 해당 요청의 최종 신호입니다. 중간 재시도 시도는 별도의 이벤트로 기록되지 않습니다.

이벤트의 attempt 속성은 총 시도 횟수를 기록합니다. CLAUDE_CODE_MAX_RETRIES는 기본값이 10이고 최대 15입니다. v2.1.199 이상에서는 CLAUDE_CODE_RETRY_WATCHDOG을 설정하여 기본값을 높이고 상한을 제거할 수 있습니다.

요청이 일시적 오류에 대한 모든 재시도를 소진하면 attempt는 해당 유효 제한보다 하나 많습니다: 기본값으로는 11이고 감시 기능이 설정되지 않은 경우 16을 초과하지 않습니다. 더 낮은 값은 400 응답과 같은 재시도 불가능한 오류를 나타내거나 자체 더 작은 재시도 예산이 있는 원인을 나타냅니다. 예를 들어 Claude Code는 AWS 또는 Google Cloud 자격 증명 로드 실패를 최대 두 번 재시도합니다.

복구된 세션과 정체된 세션을 구분하려면 session.id로 이벤트를 그룹화하고 오류 후 나중에 api_request 이벤트가 존재하는지 확인합니다.

이벤트 분석

이벤트 데이터는 Claude Code 상호 작용에 대한 자세한 정보를 제공합니다:

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

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

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

감사 보안 이벤트

OpenTelemetry 이벤트는 Claude Code 활동의 감사 데이터 소스입니다. 모든 이벤트는 도구 호출, MCP 활동 및 권한 결정을 해당 이벤트를 트리거한 사용자에게 연결하는 ID 속성을 전달하며, OTLP 로그 내보내기는 이러한 이벤트를 OTLP 수신기가 있는 모든 SIEM(Security Information and Event Management) 플랫폼 또는 SIEM으로 전달하는 OpenTelemetry Collector에 전달할 수 있습니다.

속성 작업을 사용자에게 연결

각 이벤트의 표준 속성에는 인증된 사용자의 ID가 포함됩니다: Claude 계정으로 로그인할 때 user.email, user.account_uuid, user.account_id 및 organization.id, 클라우드 세션에서 세션 자체의 자격 증명이 이들을 전달할 때, 그리고 설치 범위 user.id 및 세션별 session.id. user.id는 설치 범위 식별자이며, Claude 앱 게이트웨이 세션에서는 게이트웨이 발급 토큰의 IdP 주체입니다.

MCP 도구 호출, Bash 명령 및 파일 편집은 따라서 세션을 시작한 개발자에게 귀속됩니다. Claude Code는 별도의 서비스 계정으로 작동하지 않습니다. 각 이벤트에 기록된 ID는 개발자 자신의 Claude 계정이거나 Claude 앱 게이트웨이 세션의 개발자 IdP 신원입니다.

Claude Code가 직접 API 키로 인증하거나 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry에 대해 인증할 때 세션에 Claude 계정이 없으며 user.id 및 session.id만 채워집니다. 이러한 배포에서는 OTEL_RESOURCE_ATTRIBUTES를 사용하여 사용자 ID를 직접 첨부하고, 관리 설정 파일 또는 시작 래퍼를 통해 사용자별로 설정합니다. Claude 앱 게이트웨이 세션은 이 중 어느 것도 필요하지 않습니다: CLI는 표준 속성에 설명된 대로 IdP 신원을 자동으로 스탬프합니다.

export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

MCP 활동 감사

전체 호출 세부 정보로 MCP 서버 활동을 캡처하려면 로그 내보내기를 활성화하고 OTEL_LOG_TOOL_DETAILS=1을 설정합니다. 각 MCP 작업은 표준 ID 속성과 함께 서버 이름, 도구 이름 및 호출 인수를 전달하는 구조화된 이벤트를 생성합니다:

OTEL_LOG_TOOL_DETAILS 없이 이러한 이벤트는 식별 세부 정보를 삭제합니다:

• tool_result: mcp_server_scope를 유지하고 사용자 구성 서버의 경우 tool_name을 리터럴 "mcp_tool"로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 tool_parameters 내부의 mcp_server_name/mcp_tool_name 쌍도 유지하며, tool_decision과 동일한 호스트 작성 예외입니다. Claude Code v2.1.214 이상 필요
• tool_decision: tool_source를 유지하고 사용자 구성 서버의 경우 tool_name을 리터럴 "mcp_tool"로 수정하며, 인수 내용을 생략합니다. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서는 tool_parameters 내부의 mcp_server_name/mcp_tool_name 쌍도 유지합니다. tool_source 및 이름 쌍 모두 Claude Code v2.1.214 이상 필요
• mcp_server_connection: server_name 및 오류 메시지를 생략하지만, is_plugin, plugin_id_hash 및 plugin.name을 유지하며, Anthropic이 아닌 플러그인 이름은 리터럴 "third-party"로 수정되므로 플러그인 제공 서버는 상세 로깅 없이도 구별 가능합니다

보안 질문을 이벤트에 매핑

감지 규칙을 구축할 때 모니터링하려는 신호를 찾고 해당 이벤트 및 속성에 대해 백엔드를 쿼리합니다:

Claude Code는 원본 이벤트 스트림만 내보냅니다. 이상 감지, 기준선 설정, 세션 간 상관 관계 및 경고는 SIEM 또는 관찰성 백엔드의 책임입니다.

SIEM에 이벤트 전송

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT를 SIEM의 OTLP 수신기 또는 SIEM의 기본 수집 API로 전달하는 OpenTelemetry Collector로 지정합니다. 다음 관리 설정 예는 이벤트만 내보내고 MCP 및 Bash 감사를 위해 전체 도구 세부 정보를 활성화합니다:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://siem.example.com:4318/v1/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-siem-token"
  }
}

이벤트가 도착하는지 확인하려면 이 구성에서 실행 중인 세션에서 프롬프트를 제출하고 claude_code.user_prompt 이벤트에 대해 SIEM을 확인합니다. 아무것도 도착하지 않으면 claude --debug를 실행하고 [3P telemetry] 내보내기 오류에 대해 디버그 로그를 확인합니다.

백엔드 고려 사항

메트릭, 로그 및 추적 백엔드 선택은 수행할 수 있는 분석 유형을 결정합니다:

메트릭의 경우

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

이벤트/로그의 경우

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

추적의 경우

분산 추적 저장소 및 스팬 상관 관계를 지원하는 백엔드를 선택합니다:

• 분산 추적 시스템: 스팬 시각화, 요청 워터폴, 지연 시간 분석
• 완전한 기능의 관찰성 플랫폼: 추적 검색 및 메트릭과 로그와의 상관 관계

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

서비스 정보

모든 메트릭 및 이벤트는 다음 리소스 속성과 함께 내보내집니다:

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

수집기 파이프라인 또는 대시보드에서 service.name = claude-code로 필터링하는 경우, Code 탭 세션의 원격 분석도 캡처하기 위해 필터에 claude-code-desktop을 추가하십시오.

ROI 측정 리소스

Claude Code의 투자 수익률 측정에 대한 포괄적인 가이드(원격 측정 설정, 비용 분석, 생산성 메트릭 및 자동화된 보고 포함)는 Claude Code ROI 측정 가이드를 참조하세요. 이 저장소는 즉시 사용 가능한 Docker Compose 구성, Prometheus 및 OpenTelemetry 설정, Linear와 같은 도구와 통합된 생산성 보고서 생성 템플릿을 제공합니다.

보안 및 개인 정보 보호

• OpenTelemetry 내보내기는 선택 사항이며 명시적 구성이 필요합니다. Anthropic의 별도 운영 원격 측정 및 이를 비활성화하는 방법에 대해서는 데이터 사용을 참조하세요
• 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 OTEL_LOG_TOOL_CONTENT 항목을 참조하세요
• OAuth를 통해 인증된 경우 user.email이 원격 측정 속성에 포함되며, 구성한 OTel 엔드포인트로만 전송되고 Anthropic으로는 절대 전송되지 않습니다. 조직에서 이것이 우려 사항인 경우 원격 측정 백엔드와 함께 작업하여 이 필드를 필터링하거나 수정하세요
• 사용자 프롬프트 콘텐츠는 기본적으로 수집되지 않습니다. 프롬프트 길이만 기록됩니다. 프롬프트 콘텐츠를 포함하려면 OTEL_LOG_USER_PROMPTS=1을 설정하세요
• 어시스턴트 응답 텍스트는 기본적으로 수집되지 않습니다. 응답 길이만 기록됩니다. 응답 텍스트를 포함하려면 OTEL_LOG_ASSISTANT_RESPONSES=1을 설정하세요. Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 응답 텍스트는 구성한 OTel 엔드포인트로만 전송되며 Anthropic으로는 전송되지 않습니다. 이 변수가 설정되지 않으면 OTEL_LOG_USER_PROMPTS가 폴백으로 사용되므로 프롬프트 콘텐츠는 원하지만 응답 콘텐츠는 원하지 않는 경우 OTEL_LOG_ASSISTANT_RESPONSES=0을 설정하세요
• 도구 입력 인수 및 매개변수는 기본적으로 기록되지 않습니다. 이를 포함하려면 OTEL_LOG_TOOL_DETAILS=1을 설정하세요. Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 tool_decision 및 tool_result는 인수 콘텐츠가 아닌 호스트 작성 이름인 mcp_server_name/mcp_tool_name 쌍을 전달하며, 플래그가 꺼져 있어도 그렇습니다. 이 예외는 Claude Code v2.1.214 이상이 필요합니다. 이 데이터는 구성한 OTEL 엔드포인트로만 전송되며 Anthropic으로는 절대 전송되지 않습니다. 인수에는 여전히 민감한 값이 포함될 수 있으므로 필요에 따라 이러한 속성을 필터링하거나 수정하도록 원격 측정 백엔드를 구성하세요. 활성화되면:
  • tool_result 및 tool_decision 이벤트는 Bash 명령, MCP 서버 및 도구 이름, 스킬 이름이 포함된 tool_parameters 속성을 포함합니다. full_command와 같은 필드는 잘리지 않은 상태로 내보내집니다
  • tool_result 이벤트는 추가로 파일 경로, URL, 검색 패턴 및 기타 인수가 포함된 tool_input 속성을 포함합니다. 512자를 초과하는 개별 값은 잘리고 전체는 약 4K 문자로 제한됩니다
  • user_prompt 이벤트는 사용자 정의, 플러그인 및 MCP 명령의 축자 command_name을 포함합니다
  • 추적 스팬은 동일한 tool_input 속성 및 file_path와 같은 입력 파생 속성을 포함하며, tool_input과 동일한 잘림이 적용됩니다
• 도구 입력 및 출력 콘텐츠는 기본적으로 추적 스팬에 기록되지 않습니다. 이를 포함하려면 OTEL_LOG_TOOL_CONTENT=1을 설정하세요. 활성화되면 스팬 이벤트는 콘텐츠 제한(기본값 60KB)에서 잘린 전체 도구 입력 및 출력 콘텐츠를 속성당 포함합니다. 여기에는 Read 도구 결과의 원본 파일 콘텐츠 및 Bash 명령 출력이 포함될 수 있습니다. 필요에 따라 이러한 속성을 필터링하거나 수정하도록 원격 측정 백엔드를 구성하세요
• 원본 Anthropic Messages API 요청 및 응답 본문은 기본적으로 기록되지 않습니다. 이를 포함하려면 셸, 사용자 설정 또는 관리 설정에서 OTEL_LOG_RAW_API_BODIES를 설정하세요. 프로젝트 및 로컬 설정에서는 무시됩니다. 본문에는 전체 대화 기록(시스템 프롬프트, 모든 이전 사용자 및 어시스턴트 턴, 도구 결과)이 포함되므로 이를 활성화하면 다른 OTEL_LOG_* 콘텐츠 플래그가 공개할 모든 것에 동의하는 것을 의미합니다. Claude Code는 다른 설정에 관계없이 항상 이러한 본문에서 Claude의 확장 사고 콘텐츠를 수정합니다. 설정한 값은 Claude Code가 본문을 전달하는 방식을 결정합니다:
  • =1일 때 Claude Code는 각 API 호출에 대해 api_request_body 및 api_response_body 로그 이벤트를 내보냅니다. 이벤트의 body 속성은 JSON 직렬화된 페이로드를 전달하며, 콘텐츠 제한(기본값 60KB)에서 잘립니다
  • =file:<dir>일 때 Claude Code는 잘리지 않은 본문을 해당 디렉토리 아래의 .request.json 및 .response.json 파일에 기록하고, 이벤트는 인라인 본문 대신 body_ref 경로를 전달합니다. 로그 수집기 또는 사이드카와 함께 디렉토리를 배포하되 원격 측정 스트림을 통해서는 배포하지 마세요

Amazon Bedrock에서 Claude Code 모니터링

Amazon Bedrock의 Claude Code 사용 모니터링에 대한 자세한 지침은 Claude Code 모니터링 구현 (Amazon Bedrock)을 참조하세요.