> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/data-onboarding/supported-logs/claude-code.md). # Anthropic Claude Code 원격 측정(베타) ## 개요 {% hint style="info" %} Claude Code Telemetry 로그 수집은 Panther 버전 1.127부터 공개 베타이며 모든 고객에게 제공됩니다. 버그 보고 및 기능 요청은 Panther 지원팀과 공유해 주세요. {% endhint %} 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 [관리형 설정](https://code.claude.com/docs/en/monitoring-usage#quick-start) 파일을 사용하는 것입니다. 관리자로서 **조직 설정** > **Claude Code** > **관리형 설정** 으로 이동하여 다음과 같은 구성을 배포합니다: ```json { "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/json", "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "", "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer " } } ``` 바꿉니다 `` 및 `` 을 1단계의 값으로 설정합니다. 관리형 설정은 조직 내의 모든 Claude Code 설치에 중앙에서 푸시되므로, 텔레메트리를 제어할 수 있는 단일 감사 가능 위치를 제공합니다. 다음을 참조하세요 [Claude Code 설정 우선순위](https://code.claude.com/docs/en/monitoring-usage#quick-start) 관리형 설정이 사용자 수준 구성과 어떻게 상호작용하는지 확인하세요. #### 대안: 사용자별 환경 변수 로컬 테스트 또는 아직 관리형 설정이 적용되지 않은 설치에서는 동일한 구성을 셸 환경 변수로 적용할 수 있습니다: ```bash 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= export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " ``` #### 개인정보 보호 제어 Claude Code는 세부적인 개인정보 보호 제어 기능을 제공합니다. 다음과 같이 동일한 `env` 블록(관리형 설정) 또는 환경 변수로 설정하세요: * **`OTEL_LOG_USER_PROMPTS=1`**: 텔레메트리에 실제 프롬프트 내용을 포함합니다(기본적으로는 마스킹됨). * **`OTEL_LOG_TOOL_DETAILS=1`**: 자세한 도구 매개변수, 훅 구성 및 오류 세부 정보를 포함합니다. * **`OTEL_LOG_RAW_API_BODIES=file:`**: 지정된 디렉터리의 파일에 전체 API 요청/응답 본문을 기록합니다. ### 3단계: 통합 테스트 1. 관리형 설정을 받은 머신(또는 env 변수가 설정된 로컬 셸)에서 Claude Code를 실행합니다: ```bash claude "Hello, can you help me write a simple Python script?" ``` 2. Panther Console에서 Claude Code 로그 소스로 이동하여 다음을 확인합니다: * **소스 상태** 가 "Healthy"로 표시됩니다. * 최근 이벤트가 다음에 표시됩니다. **이벤트** 섹션. * 이벤트 처리가 올바르게 작동하고 있습니다. ## 지원되는 로그 유형 ### Anthropic.ClaudeTelemetry ```yaml 스키마: 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 설명: @ 형식의 플러그인 식별자(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:). 유형: 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 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.panther.com/ko/data-onboarding/supported-logs/claude-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.