모니터링

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

빠른 시작

# 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

​

관리자 구성

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

​

구성 세부 정보

​

일반적인 구성 변수

​

mTLS 인증

​

메트릭 카디널리티 제어

​

추적 (베타)

​

스팬 계층 구조

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

​

스팬 속성

​

동적 헤더

​

설정 구성

{
  "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: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리 (문자열 배열)

​

메트릭

​

메트릭 세부 정보

​

세션 카운터

• 모든 표준 속성
• start_type: 세션이 시작된 방식. "fresh", "resume" 또는 "continue" 중 하나

​

코드 라인 카운터

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

​

풀 요청 카운터

• 모든 표준 속성

​

커밋 카운터

• 모든 표준 속성

​

비용 카운터

• 모든 표준 속성
• model: 모델 식별자 (예: “claude-sonnet-4-6”)
• 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: 소유 플러그인이 설치된 마켓플레이스. 공식 마켓플레이스 플러그인에만 내보내집니다. 그 외에는 없음

​

토큰 카운터

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

​

코드 편집 도구 결정 카운터

• 모든 표준 속성
• 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로 활성화)
• command_name: 프롬프트가 명령을 호출할 때 명령 이름. compact 또는 debug와 같은 기본 제공 및 번들 명령 이름은 그대로 내보내집니다. reset과 같은 별칭은 정규 이름이 아닌 입력한 대로 내보냅니다. 사용자 정의, 플러그인 및 MCP 명령 이름은 OTEL_LOG_TOOL_DETAILS=1이 설정되지 않으면 custom 또는 mcp로 축소됩니다
• command_source: 명령이 있을 때 명령의 출처: builtin, custom 또는 mcp. 플러그인 제공 명령은 custom으로 보고합니다

​

도구 결과 이벤트

• 모든 표준 속성
• 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" 또는 "reject"
• 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 도구의 경우)
• tool_parameters (OTEL_LOG_TOOL_DETAILS=1일 때): 도구별 매개변수를 포함하는 JSON 문자열:
  • Bash 도구의 경우: bash_command, full_command, timeout, description, dangerouslyDisableSandbox 및 git_commit_id (git commit 명령이 성공할 때 커밋 SHA) 포함
  • MCP 도구의 경우: mcp_server_name, mcp_tool_name 포함
  • Skill 도구의 경우: skill_name 포함
  • Task 도구의 경우: subagent_type 포함
• 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: 캐시 생성에 사용된 토큰 수
• request_id: 응답의 request-id 헤더의 Anthropic API 요청 ID (예: "req_011..."). API가 반환할 때만 표시됩니다.
• speed: 빠른 모드가 활성화되었는지 여부를 나타내는 "fast" 또는 "normal"
• query_source: 요청을 발급한 하위 시스템 (예: "repl_main_thread", "compact" 또는 하위 에이전트 이름)
• effort: 요청에 적용된 노력 수준: "low", "medium", "high", "xhigh" 또는 "max". 모델이 노력을 지원하지 않을 때는 없음

​

API 오류 이벤트

• 모든 표준 속성
• event.name: "api_error"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• model: 사용된 모델 (예: “claude-sonnet-4-6”)
• error: 오류 메시지
• status_code: HTTP 상태 코드 (숫자). HTTP가 아닌 오류 (예: 연결 실패)의 경우 없음
• duration_ms: 요청 지속 시간 (밀리초)
• attempt: 초기 요청을 포함한 총 시도 횟수 (1은 재시도가 발생하지 않았음을 의미)
• request_id: 응답의 request-id 헤더의 Anthropic API 요청 ID (예: "req_011..."). API가 반환할 때만 표시됩니다.
• speed: 빠른 모드가 활성화되었는지 여부를 나타내는 "fast" 또는 "normal"
• query_source: 요청을 발급한 하위 시스템 (예: "repl_main_thread", "compact" 또는 하위 에이전트 이름)
• effort: 요청에 적용된 노력 수준. 모델이 노력을 지원하지 않을 때는 없음

​

API 요청 본문 이벤트

• 모든 표준 속성
• 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 응답 본문 이벤트

• 모든 표준 속성
• 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가 반환할 때만 표시됩니다.

​

도구 결정 이벤트

• 모든 표준 속성
• 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"
• source: 결정 출처:
  • "config": 프로젝트 설정, 사용자의 개인 설정의 허용 규칙, 엔터프라이즈 관리 정책, --allowedTools 또는 --disallowedTools 플래그, 활성 권한 모드, 같은 대화형 CLI 세션의 이전 프롬프트에서의 세션 범위 부여 또는 도구가 본질적으로 안전하기 때문에 프롬프트 없이 자동으로 결정됨. 이벤트는 이러한 출처 중 어느 것이 일치했는지 나타내지 않습니다.
  • "hook": PreToolUse 또는 PermissionRequest 훅이 결정을 반환함.
  • "user_permanent": 사용자가 권한 프롬프트에서 “예, 그리고 … 다시 묻지 마세요”를 선택하여 개인 설정에 허용 규칙을 저장했을 때 내보내집니다. 대화형 CLI에서는 해당 선택 자체에 대해서만 내보내집니다. 나중에 저장된 규칙과 일치하는 호출은 대신 "config"을 내보냅니다. Agent SDK 또는 비대화형 -p 세션에서는 초기 선택과 나중의 규칙 일치 모두 "user_permanent"를 내보냅니다. 수락으로 처리됨.
  • "user_temporary": 사용자가 권한 프롬프트에서 “예”를 선택했거나 파일 편집 또는 읽기 프롬프트에서 “이 세션 중” 옵션 중 하나를 선택했을 때 내보내집니다. 대화형 CLI에서는 선택 자체에 대해서만 내보내집니다. 나중에 해당 세션 범위 부여와 일치하는 호출은 대신 "config"을 내보냅니다. Agent SDK 또는 비대화형 -p 세션에서는 선택과 나중의 일치 모두 "user_temporary"를 내보냅니다. 수락으로 처리됨.
  • "user_abort": 사용자가 답변 없이 권한 프롬프트를 닫았을 때 내보내집니다. 거부로 처리됨.
  • "user_reject": 사용자가 프롬프트될 때 “아니오”를 선택했거나 호출이 개인 설정의 거부 규칙과 일치했을 때 내보내집니다. 거부로 처리됨.

​

권한 모드 변경 이벤트

• 모든 표준 속성
• 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 또는 브리지에서 전환이 시작될 때는 없음

​

인증 이벤트

• 모든 표준 속성
• 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 서버 연결 이벤트

• 모든 표준 속성
• 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: 연결이 실패했을 때 오류 코드
• server_name (OTEL_LOG_TOOL_DETAILS=1일 때): 구성된 서버 이름
• error (OTEL_LOG_TOOL_DETAILS=1일 때): 연결이 실패했을 때 전체 오류 메시지

​

내부 오류 이벤트

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

​

플러그인 설치됨 이벤트

• 모든 표준 속성
• 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일 때만 포함됩니다

​

플러그인 로드됨 이벤트

• 모든 표준 속성
• 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", "org", "user-local" 또는 "default-bundle"
• enabled_via: 플러그인이 활성화된 방식: "default-enable", "org-policy", "seed-mount" 또는 "user-install"
• plugin_id_hash: 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 플릿 전체에서 로드된 서로 다른 타사 플러그인 수를 세는 것을 허용합니다 (이름 기록 없이)
• has_hooks: 플러그인이 훅을 제공하는지 여부
• has_mcp: 플러그인이 MCP 서버를 제공하는지 여부
• skill_path_count: 플러그인이 선언하는 스킬 디렉토리 수
• command_path_count: 플러그인이 선언하는 명령 디렉토리 수
• agent_path_count: 플러그인이 선언하는 에이전트 디렉토리 수

​

스킬 활성화됨 이벤트

• 모든 표준 속성
• 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")
• plugin.name (OTEL_LOG_TOOL_DETAILS=1이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인의 이름
• marketplace.name (OTEL_LOG_TOOL_DETAILS=1이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인이 설치된 마켓플레이스

​

@ 멘션 이벤트

• 모든 표준 속성
• event.name: "at_mention"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• mention_type: 멘션의 유형 ("file", "directory", "agent", "mcp_resource")
• success: 멘션이 성공적으로 해석되었는지 여부 ("true" 또는 "false")

​

API 재시도 소진됨 이벤트

• 모든 표준 속성
• 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"

​

훅 등록됨 이벤트

• 모든 표준 속성
• 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"
• 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"일 때): 플러그인 이름 및 마켓플레이스의 결정론적 해시 (구성된 내보내기로만 전송됨). 이름을 기록하지 않고 기여하는 서로 다른 플러그인을 세는 것을 허용합니다

​

훅 실행 시작 이벤트

• 모든 표준 속성
• 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"
• hook_definitions: JSON 직렬화된 훅 구성. 상세 베타 추적과 OTEL_LOG_TOOL_DETAILS=1이 모두 활성화되어 있을 때만 포함됨

​

훅 실행 완료 이벤트

• 모든 표준 속성
• 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"
• hook_definitions: JSON 직렬화된 훅 구성. 상세 베타 추적과 OTEL_LOG_TOOL_DETAILS=1이 모두 활성화되어 있을 때만 포함됨

​

압축 이벤트

• 모든 표준 속성
• event.name: "compaction"
• event.timestamp: ISO 8601 타임스탬프
• event.sequence: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
• trigger: "auto" 또는 "manual"
• success: "true" 또는 "false"
• duration_ms: 압축 지속 시간
• pre_tokens: 압축 전 대략적인 토큰 수
• post_tokens: 압축 후 대략적인 토큰 수
• error: 압축이 실패했을 때 오류 메시지

​

피드백 설문 이벤트

• 모든 표준 속성
• 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 설문 이벤트에 표시됩니다. 이 속성을 필터링하여 플릿 전체에서 재정의가 적용되었는지 확인합니다

​

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

​

사용 모니터링

​

비용 모니터링

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

​

경고 및 세분화

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

​

재시도 소진 감지

​

이벤트 분석

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

​

감사 보안 이벤트

​

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

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

​

MCP 활동 감사

​

보안 질문을 이벤트에 매핑

​

SIEM에 이벤트 전송

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

​

백엔드 고려 사항

​

메트릭의 경우

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

​

이벤트/로그의 경우

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

​

추적의 경우

• 분산 추적 시스템 (예: Jaeger, Zipkin, Grafana Tempo): 스팬 시각화, 요청 워터폴, 지연 시간 분석
• 완전한 기능의 관찰성 플랫폼 (예: 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 측정 리소스

​

보안 및 개인 정보 보호

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

​

Amazon Bedrock에서 Claude Code 모니터링