Anthropic Claude Code 텔레메트리(베타)

OpenTelemetry(OTLP)를 통해 Claude Code 사용량, 비용 및 도구 활동을 모니터링

개요

Claude Code Telemetry 로그 수집은 Panther 버전 1.127부터 공개 베타이며 모든 고객에게 제공됩니다. 버그 보고 및 기능 요청은 Panther 지원팀과 공유해 주세요.

Claude Code는 Anthropic의 에이전트형 명령줄 코딩 도구입니다. 텔레메트리가 활성화되면 세션, 토큰 및 비용 사용량, 도구 활동, 권한 결정, API/인증 이벤트를 포함한 사용 데이터를 OpenTelemetry(OTel)를 통해 내보냅니다.

Panther는 Claude Code의 OTLP 로그 이벤트를 실시간으로 수집하고 이를 Anthropic.ClaudeTelemetry 스키마로 정규화하며, 보안 및 플랫폼 팀이 개발자 전체 환경에서 도입률, 지출, 위험한 활동을 모니터링할 수 있게 합니다.

사전 요구 사항

• Claude Code가 설치 및 구성되어 있어야 합니다.

• Claude Code 조직에 대한 관리자 액세스 권한(관리형 설정을 배포하기 위해).

Claude Code 텔레메트리를 Panther에 온보딩하는 방법

1단계: Panther에서 OTLP 로그 소스 만들기

1. Panther Console의 왼쪽 탐색 모음에서 로그 소스.

2. 클릭합니다 새로 만들기.

3. “Claude Code”를 검색하고 해당 타일을 클릭합니다.

4. 다음 페이지에서 구성 페이지에서 다음을 입력하세요:

   • 소스 이름: 다음과 같은 설명적인 이름을 입력하세요 Claude Code 텔레메트리.

   • 스키마: 해당 Anthropic.ClaudeTelemetry 스키마가 자동으로 선택됩니다.

5. 다음 인증 섹션:

   • 인증 방식: Bearer(OTLP 소스용으로 미리 선택됨).

   • Bearer 토큰: bearer 토큰 값을 생성하여 안전하게 복사합니다.

6. 클릭합니다 설정.

7. 다음을 기록해 두세요 OTLP 엔드포인트 URL 성공 화면에서 — Claude Code 구성에 필요합니다.

2단계: 관리형 설정을 통해 Claude Code 텔레메트리 구성

개발자 전체 환경에서 Claude Code 텔레메트리를 활성화하는 권장 방법은 Claude Code 관리형 설정 파일을 사용하는 것입니다. 관리자로서 조직 설정 > Claude Code > 관리형 설정 으로 이동하여 다음과 같은 구성을 배포합니다:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "<your_panther_otlp_endpoint_url>",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <your_bearer_token>"
  }
}

바꿉니다 <your_panther_otlp_endpoint_url> 및 <your_bearer_token> 을 1단계의 값으로 설정합니다.

관리형 설정은 조직 내의 모든 Claude Code 설치에 중앙에서 푸시되므로, 텔레메트리를 제어할 수 있는 단일 감사 가능 위치를 제공합니다. 다음을 참조하세요 Claude Code 설정 우선순위 관리형 설정이 사용자 수준 구성과 어떻게 상호작용하는지 확인하세요.

대안: 사용자별 환경 변수

로컬 테스트 또는 아직 관리형 설정이 적용되지 않은 설치에서는 동일한 구성을 셸 환경 변수로 적용할 수 있습니다:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=<your_panther_otlp_endpoint_url>
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your_bearer_token>"

개인정보 보호 제어

Claude Code는 세부적인 개인정보 보호 제어 기능을 제공합니다. 다음과 같이 동일한 env 블록(관리형 설정) 또는 환경 변수로 설정하세요:

• OTEL_LOG_USER_PROMPTS=1: 텔레메트리에 실제 프롬프트 내용을 포함합니다(기본적으로는 마스킹됨).

• OTEL_LOG_TOOL_DETAILS=1: 자세한 도구 매개변수, 훅 구성 및 오류 세부 정보를 포함합니다.

• OTEL_LOG_RAW_API_BODIES=file:<directory>: 지정된 디렉터리의 파일에 전체 API 요청/응답 본문을 기록합니다.

3단계: 통합 테스트

1. 관리형 설정을 받은 머신(또는 env 변수가 설정된 로컬 셸)에서 Claude Code를 실행합니다:

   claude "Hello, can you help me write a simple Python script?"

2. Panther Console에서 Claude Code 로그 소스로 이동하여 다음을 확인합니다:

   • 소스 상태 가 "Healthy"로 표시됩니다.

   • 최근 이벤트가 다음에 표시됩니다. 이벤트 섹션.

   • 이벤트 처리가 올바르게 작동하고 있습니다.

지원되는 로그 유형

Anthropic.ClaudeTelemetry

스키마: Anthropic.ClaudeTelemetry
description: |
  도구에 의해 생성된 Claude Code/Cowork 텔레메트리 이벤트입니다. 채워지는
  속성 집합은 이벤트 유형(`attributes.event_name`)에 따라 다릅니다. 각 이벤트의 세부 정보는
  Claude Code 모니터링 문서를 참조하세요.
referenceURL: https://code.claude.com/docs/en/monitoring-usage
필드:
  - name: timeUnixNano
    필수: true
    설명: UNIX 에포크 이후 나노초 단위의 이벤트 시간.
    유형: timestamp
    시간 형식:
      - unix_ns
    이벤트 시간 여부: true
  - name: observedTimeUnixNano
    설명: 이벤트가 관찰된 시간, UNIX 에포크 이후 나노초 단위.
    유형: timestamp
    시간 형식:
      - unix_ns
  - name: body
    필수: true
    설명: 완전한 정규화 이벤트 이름. 예: "claude_code.user_prompt".
    유형: string
  - name: droppedAttributesCount
    설명: 제한으로 인해 삭제된 속성 수.
    유형: bigint
  - 이름: attributes
    description: |
      이벤트 속성입니다. 채워지는 하위 집합은 이벤트 유형에 따라
      (`attributes.event_name`) 다릅니다. 자세한 이벤트별 속성 목록은 Claude Code 모니터링 문서를 참조하세요.
      각 이벤트의 속성 목록을 참조하세요.
    유형: object
    필드:
      # --- 표준 속성 (사용 가능한 경우 모든 이벤트에 있음) ---
      - name: event_name
        설명: 짧은 이벤트 이름. 예: "user_prompt", "tool_result", "api_request".
        유형: string
      - name: event_timestamp
        설명: 이벤트 타임스탬프(ISO 8601 / RFC3339).
        유형: timestamp
        시간 형식:
          - rfc3339
      - name: event_sequence
        설명: 세션 내 이벤트 순서를 정하는 단조 증가 카운터.
        유형: bigint
      - 이름: session_id
        설명: 고유한 세션 식별자(session.id에서 가져옴).
        유형: string
        지표:
          - trace_id
      - name: prompt_id
        설명: 사용자 프롬프트와 이를 트리거한 모든 이벤트를 연결하는 UUID(prompt.id에서 가져옴).
        유형: string
        지표:
          - trace_id
      - 이름: app_version
        설명: Claude Code 버전(app.version에서 가져옴).
        유형: string
      - name: app_entrypoint
        설명: 세션이 시작된 방식. 예: cli, sdk-cli, sdk-ts, sdk-py, claude-vscode(app.entrypoint에서 가져옴).
        유형: string
      - 이름: organization_id
        설명: 인증된 경우 조직 UUID(organization.id에서 가져옴).
        유형: string
      - 이름: user_id
        설명: 기기별 무작위 익명 식별자(user.id에서 가져옴).
        유형: string
        지표:
          - actor_id
      - name: user_account_id
        설명: Anthropic admin-API 태그 형식의 계정 ID. 예: user_01...(user.account_id에서 가져옴).
        유형: string
      - name: user_account_uuid
        설명: 인증된 경우 계정 UUID(user.account_uuid에서 가져옴).
        유형: string
      - name: user_email
        설명: OAuth로 인증한 경우 사용자 이메일(user.email에서 가져옴).
        유형: string
        지표:
          - email
      - name: terminal_type
        설명: 터미널 유형. 예: iTerm.app, vscode, cursor, tmux(terminal.type에서 가져옴).
        유형: string
      - name: workspace_host_paths
        설명: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉터리(workspace.host_paths에서 가져옴).
        유형: array
        요소:
          유형: string
      # --- user_prompt ---
      - name: prompt
        설명: 프롬프트 내용. OTEL_LOG_USER_PROMPTS=1이 아니면 마스킹됩니다.
        유형: string
      - name: prompt_length
        설명: 프롬프트 길이.
        유형: bigint
      - name: command_name
        설명: 프롬프트가 명령을 호출할 때의 명령 이름(예: compact); OTEL_LOG_TOOL_DETAILS=1이 아니면 custom/plugin/mcp는 축약됩니다.
        유형: string
      - name: command_source
        설명: 명령의 출처. builtin, custom, mcp 중 하나.
        유형: string
      # --- tool_result / tool_decision ---
      - name: tool_name
        설명: 도구 이름. 예: Read, Edit, Write, Bash.
        유형: string
      - name: tool_use_id
        설명: 이 도구 호출의 고유 식별자입니다. 훅에 전달된 tool_use_id와 일치합니다.
        유형: string
      - 이름: success
        설명: 작업이 성공했는지 여부("true"/"false"). tool_result, auth, at_mention, compaction에 사용됩니다.
        유형: boolean
      - name: duration_ms
        설명: 밀리초 단위의 지속 시간. tool_result, api_request, api_error, mcp_server_connection, compaction에 사용됩니다.
        유형: bigint
      - name: error_type
        설명: 도구 실패 시의 오류 범주 문자열. 예: "Error:ENOENT", "ShellError".
        유형: string
      - name: decision
        설명: 권한 결정. "accept" 또는 "reject"(tool_decision).
        유형: string
      - name: decision_type
        설명: 확인된 결정 유형. tool_result에서는 항상 "accept"입니다.
        유형: string
      - name: decision_source
        설명: 권한 결정의 출처. 예: config, hook, user_permanent, user_temporary, user_abort, user_reject.
        유형: string
      - name: source
        설명: tool_decision의 출처(config, hook, user_permanent, user_temporary, user_abort, user_reject).
        유형: string
      - name: mcp_server_scope
        설명: MCP 서버 범위 식별자(MCP 도구용).
        유형: string
      - name: tool_input_size_bytes
        설명: JSON 직렬화된 도구 입력의 크기(바이트).
        유형: bigint
      - name: tool_result_size_bytes
        설명: 도구 결과의 크기(바이트).
        유형: bigint
      - name: tool_parameters
        설명: 도구별 매개변수의 JSON 문자열(OTEL_LOG_TOOL_DETAILS=1일 때).
        유형: json
        내장 JSON: true
      - name: tool_input
        설명: JSON 직렬화된 도구 인수(OTEL_LOG_TOOL_DETAILS=1일 때).
        유형: json
        내장 JSON: true
      # --- api_request / api_error / api_refusal / api_retries_exhausted ---
      - name: model
        설명: 사용된 모델. 예: claude-sonnet-4-6.
        유형: string
      - name: cost_usd
        설명: 예상 USD 비용(api_request).
        유형: float
      - name: cost_usd_micros
        설명: 예상 USD 백만분율 비용(api_request).
        유형: bigint
      - name: input_tokens
        설명: 입력 토큰 수.
        유형: bigint
      - name: output_tokens
        설명: 출력 토큰 수.
        유형: bigint
      - name: cache_read_tokens
        설명: 캐시에서 읽은 토큰 수.
        유형: bigint
      - name: cache_creation_tokens
        설명: 캐시 생성에 사용된 토큰 수.
        유형: bigint
      - 이름: request_id
        설명: 응답의 request-id 헤더에서 가져온 Anthropic API 요청 ID. 예: req_011...
        유형: string
      - name: speed
        설명: 빠른 모드가 활성화되었는지 나타내는 "fast" 또는 "normal".
        유형: string
      - name: query_source
        설명: 요청을 보낸 하위 시스템. 예: repl_main_thread, compact, 또는 서브에이전트 이름.
        유형: string
      - name: effort
        설명: 요청에 적용된 노력 수준. 예: low, medium, high, xhigh, max.
        유형: string
      - 이름: error
        설명: 오류 메시지(api_error, api_retries_exhausted, compaction, OTEL_LOG_TOOL_DETAILS=1일 때 mcp_server_connection).
        유형: string
      - name: status_code
        설명: HTTP 상태 코드. api_error/api_retries_exhausted에서는 숫자, auth에서는 문자열.
        유형: bigint
      - name: attempt
        설명: 최초 요청을 포함한 전체 시도 횟수(api_error).
        유형: bigint
      - name: total_attempts
        설명: 전체 시도 횟수(api_retries_exhausted).
        유형: bigint
      - name: total_retry_duration_ms
        설명: 모든 시도에 걸친 총 벽시계 시간(api_retries_exhausted).
        유형: bigint
      - name: server_fallback_hop
        설명: API의 서버 측 모델 폴백이 이 거부를 이미 다른 모델에서 재시도하여 사용자는 보지 못했을 때는 "True"이고, 요청이 거부로 종료되었을 때는 false입니다(api_refusal).
        유형: boolean
      - name: has_category
        설명: API 응답에 stop_details.category(cyber, bio, frontier_llm, reasoning_extraction)가 포함되었을 때 True이며, server_fallback_hop이 true이면 존재하지 않습니다(api_refusal).
        유형: boolean
      - name: has_explanation
        설명: API 응답에 stop_details.explanation이 포함되었을 때 True이며, server_fallback_hop이 true이면 존재하지 않습니다(api_refusal).
        유형: boolean
      - 이름: category
        설명: stop_details.category 값. cyber, bio, frontier_llm, reasoning_extraction 중 하나입니다. OTEL_LOG_TOOL_DETAILS=1이고 has_category가 true일 때만 존재합니다(api_refusal).
        유형: string
      - name: agent_name
        설명: 요청의 에이전트 귀속(agent.name에서 가져옴).
        유형: string
      - name: skill_name
        설명: 스킬 귀속 / 활성화된 스킬 이름(skill.name에서 가져옴).
        유형: string
      - name: skill_source
        설명: 스킬이 로드된 위치. 예: bundled, userSettings, projectSettings, plugin(skill.source에서 가져옴).
        유형: string
      - name: skill_kind
        설명: 스킬이 워크플로 스킬일 때는 "workflow"(skill.kind에서 가져옴).
        유형: string
      - name: invocation_trigger
        설명: 스킬이 트리거된 방식. 예: user-slash, claude-proactive, nested-skill.
        유형: string
      - name: plugin_name
        설명: 플러그인 이름. OTEL_LOG_TOOL_DETAILS=1이 아니면 서드파티 플러그인은 "third-party"(plugin.name에서 가져옴).
        유형: string
      - name: plugin_version
        설명: 플러그인 버전(plugin.version에서 가져옴).
        유형: string
      - name: plugin_scope
        설명: 플러그인 출처. 예: official, org, user-local, default-bundle(plugin.scope에서 가져옴).
        유형: string
      - name: plugin_id
        설명: <name>@<marketplace> 형식의 플러그인 식별자(hook_plugin_metrics).
        유형: string
      - name: plugin_id_hash
        설명: 이름을 노출하지 않고 전체 카운팅을 수행하기 위한 플러그인 이름 + 마켓플레이스의 결정론적 해시.
        유형: string
      - name: marketplace_name
        설명: 플러그인이 설치된 마켓플레이스(marketplace.name에서 가져옴).
        유형: string
      - name: marketplace_is_official
        설명: 마켓플레이스가 Anthropic 공식 마켓플레이스인지 여부(marketplace.is_official에서 가져옴).
        유형: boolean
      - name: install_trigger
        설명: 플러그인이 설치된 방식. "cli" 또는 "ui"(install.trigger에서 가져옴).
        유형: string
      - name: enabled_via
        설명: 플러그인이 활성화된 방식. 예: default-enable, org-policy, seed-mount, user-install.
        유형: string
      - name: has_hooks
        설명: 플러그인이 훅을 제공하는지 여부.
        유형: boolean
      - name: has_mcp
        설명: 플러그인이 MCP 서버를 제공하는지 여부.
        유형: boolean
      - name: host_owned_mcp
        설명: SDK 호스트가 이 플러그인의 MCP 연결을 관리하는지 여부.
        유형: boolean
      - name: skill_path_count
        설명: 플러그인이 선언한 스킬 디렉터리 수.
        유형: bigint
      - name: command_path_count
        설명: 플러그인이 선언한 명령 디렉터리 수.
        유형: bigint
      - name: agent_path_count
        설명: 플러그인이 선언한 에이전트 디렉터리 수.
        유형: bigint
      - name: safe_mode
        설명: 세션이 --safe-mode로 시작되었는지 여부.
        유형: boolean
      - name: mcp_server_name
        설명: api_request에 대한 MCP 서버 이름 귀속(mcp_server.name에서 가져옴).
        유형: string
      - name: mcp_tool_name
        설명: api_request에 대한 MCP 도구 이름 귀속(mcp_tool.name에서 가져옴).
        유형: string
      # --- api_request_body / api_response_body ---
      - name: body_ref
        설명: 잘리지 않은 본문이 있는 파일의 절대 경로(file mode, OTEL_LOG_RAW_API_BODIES=file:<dir>).
        유형: string
      - name: body_length
        설명: 잘리지 않은 본문의 길이(file mode에서는 UTF-8 바이트, inline에서는 UTF-16 코드 단위).
        유형: bigint
      - name: body_truncated
        설명: 인라인 잘림이 발생했을 때 "true"입니다. file mode와 잘림이 없을 때는 존재하지 않습니다.
        유형: boolean
      # --- permission_mode_changed ---
      - name: from_mode
        설명: 이전 권한 모드. 예: default, plan, acceptEdits, auto, bypassPermissions.
        유형: string
      - name: to_mode
        설명: 새 권한 모드.
        유형: string
      - name: trigger
        설명: 변경/압축을 유발한 원인. 예: shift_tab, exit_plan_mode, auto_gate_denied, auto_opt_in(permission_mode_changed); auto, manual(compaction).
        유형: string
      # --- auth ---
      - 이름: action
        설명: "login" 또는 "logout"(auth).
        유형: string
      - name: auth_method
        설명: 인증 방법. 예: oauth(auth).
        유형: string
      - name: error_category
        설명: 작업 실패 시의 범주형 오류 유형. 원시 메시지는 절대 포함되지 않습니다(auth).
        유형: string
      # --- mcp_server_connection ---
      - 이름: status
        설명: "connected", "failed", 또는 "disconnected"(mcp_server_connection).
        유형: string
      - name: transport_type
        설명: MCP 서버 전송 방식. 예: stdio, sse, http.
        유형: string
      - name: server_scope
        설명: MCP 서버가 구성된 범위. 예: user, project, local.
        유형: string
      - name: error_code
        설명: MCP 연결(또는 내부 오류)이 발생했을 때의 오류 코드.
        유형: string
      - name: is_plugin
        설명: MCP 서버가 플러그인에 의해 제공되는지 여부.
        유형: boolean
      - name: server_name
        설명: 구성된 MCP 서버 이름(OTEL_LOG_TOOL_DETAILS=1일 때).
        유형: string
      # --- internal_error ---
      - name: error_name
        설명: 오류 클래스 이름. 예: TypeError, SyntaxError(internal_error).
        유형: string
      # --- at_mention ---
      - name: mention_type
        설명: 해결된 멘션 유형. 예: file, directory, agent, mcp_resource.
        유형: string
      # --- hook_registered / hook_execution_start / hook_execution_complete / hook_plugin_metrics ---
      - name: hook_event
        설명: 훅 이벤트 유형. 예: PreToolUse, PostToolUse, UserPromptSubmit, PermissionRequest.
        유형: string
      - name: hook_type
        설명: 훅 구현 유형. 예: command, prompt, mcp_tool, http, agent(hook_registered).
        유형: string
      - name: hook_source
        설명: 훅이 정의된 위치. 예: userSettings, projectSettings, localSettings, policySettings, pluginHook, merged.
        유형: string
      - name: hook_name
        설명: matcher를 포함한 전체 훅 이름. 예: PreToolUse:Write.
        유형: string
      - name: hook_matcher
        설명: 훅 구성의 matcher 문자열(OTEL_LOG_TOOL_DETAILS=1일 때).
        유형: string
      - name: hook_definitions
        설명: JSON 직렬화된 훅 구성(상세 베타 추적 + OTEL_LOG_TOOL_DETAILS=1).
        유형: string
      - name: num_hooks
        설명: 일치하는 훅 명령 수.
        유형: bigint
      - name: num_success
        설명: 성공적으로 완료된 훅 수.
        유형: bigint
      - name: num_blocking
        설명: 차단 결정을 반환한 훅 수.
        유형: bigint
      - name: num_non_blocking_error
        설명: 차단 없이 실패한 훅 수.
        유형: bigint
      - name: num_cancelled
        설명: 완료 전에 취소된 훅 수.
        유형: bigint
      - name: total_duration_ms
        설명: 일치하는 모든 훅의 벽시계 시간 기준 지속 시간.
        유형: bigint
      - name: managed_only
        설명: 관리 정책 훅만 허용될 때 "true"입니다.
        유형: boolean
      # --- compaction ---
      - name: pre_tokens
        설명: 압축 전의 대략적인 토큰 수.
        유형: bigint
      - name: post_tokens
        설명: 압축 후의 대략적인 토큰 수.
        유형: bigint
      - name: precompute_reuse
        설명: /compact가 준비된 요약을 재사용했는지 여부; hit, miss_custom_instructions, miss_hook, miss_not_ready(수동 압축만).
        유형: string
      # --- feedback_survey ---
      - 이름: event_type
        설명: 설문 수명 주기 이벤트. 예: appeared, responded, transcript_prompt_appeared.
        유형: string
      - name: appearance_id
        설명: 하나의 설문 인스턴스에 대해 발행된 이벤트를 연결하는 고유 ID.
        유형: string
      - name: survey_type
        설명: 이벤트를 생성한 설문 유형. 예: session.
        유형: string
      - 이름: response
        설명: responded 이벤트에서 사용자의 선택.
        유형: string
      - name: enabled_via_override
        설명: CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL이 설정되어 있으면 True입니다.
        유형: boolean