97 97
98## 구성 세부 정보98## 구성 세부 정보
99 99
100### 일반적인 구성 변수100### 공통 구성 변수
101 101
102이러한 변수는 모든 배포에 대한 내보내기, 엔드포인트 및 내보내기 동작을 구성합니다.102이 변수들은 모든 배포에 대해 익스포터, 엔드포인트 및 내보내기 동작을 구성합니다.
103 103
104`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 엔드포인트 또는 프로토콜 변수를 설정하면 Claude Code는 해당 신호에 대해 일반 변수 대신 이를 사용합니다. `OTEL_EXPORTER_OTLP_METRICS_HEADERS`와 같은 신호별 헤더 변수를 설정하면 Claude Code는 해당 신호에 대해 일반 `OTEL_EXPORTER_OTLP_HEADERS`와 병합합니다.104`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 엔드포인트 또는 프로토콜 변수를 설정하면 Claude Code는 해당 신호에 대해 일반 변수 대신 이를 사용합니다. `OTEL_EXPORTER_OTLP_METRICS_HEADERS`와 같은 신호별 헤더 변수를 설정하면 Claude Code는 해당 신호에 대해 이를 일반 `OTEL_EXPORTER_OTLP_HEADERS`와 병합합니다.
105 105
106관리되는 설정이 있는 머신에서는 [관리되는 설정이 OTLP 대상을 잠그는 방법](#how-managed-settings-lock-the-otlp-destination)을 참조하여 Claude Code가 제거하는 항목을 확인하세요.106관리형 설정이 있는 머신에서 Claude Code가 제거하는 항목은 [관리형 설정이 OTLP 대상을 잠그는 방식](#how-managed-settings-lock-the-otlp-destination)을 참조하세요.
107 107
108| 환경 변수 | 설명 | 예제 값 |108| 환경 변수 | 설명 | 예시 값 |
109| - | - | - |109| - | - | - |
110| `CLAUDE_CODE_ENABLE_TELEMETRY` | 원격 분석 수집 활성화(필수) | `1` |110| `CLAUDE_CODE_ENABLE_TELEMETRY` | 텔레메트리 수집을 활성화합니다(필수) | `1` |
111| `OTEL_METRICS_EXPORTER` | 메트릭 내보내기 유형, 쉼표로 구분. 비활성화하려면 `none` 사용 | `console`, `otlp`, `prometheus`, `none` |111| `OTEL_METRICS_EXPORTER` | 메트릭 익스포터 유형(쉼표로 구분). 비활성화하려면 `none` 사용 | `console`, `otlp`, `prometheus`, `none` |
112| `OTEL_LOGS_EXPORTER` | 로그/이벤트 내보내기 유형, 쉼표로 구분. 비활성화하려면 `none` 사용 | `console`, `otlp`, `none` |112| `OTEL_LOGS_EXPORTER` | 로그/이벤트 익스포터 유형(쉼표로 구분). 비활성화하려면 `none` 사용 | `console`, `otlp`, `none` |
113| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 내보내기용 프로토콜, 모든 신호에 적용. Claude Code에는 기본 프로토콜이 없으므로 활성화하는 각 `otlp` 내보내기에 대해 이 또는 신호별 프로토콜 변수를 설정하세요 | `grpc`, `http/json`, `http/protobuf` |113| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 익스포터용 프로토콜로, 모든 신호에 적용됩니다. Claude Code에는 기본 프로토콜이 없으므로 활성화하는 각 `otlp` 익스포터에 대해 이 변수 또는 신호별 프로토콜 변수를 설정해야 합니다 | `grpc`, `http/json`, `http/protobuf` |
114| `OTEL_EXPORTER_OTLP_ENDPOINT` | 모든 신호에 대한 OTLP 수집기 엔드포인트 | `http://localhost:4317` |114| `OTEL_EXPORTER_OTLP_ENDPOINT` | 모든 신호에 대한 OTLP 수집기 엔드포인트 | `http://localhost:4317` |
115| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | 메트릭용 프로토콜, 일반 설정 재정의 | `grpc`, `http/json`, `http/protobuf` |115| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | 메트릭용 프로토콜로, 일반 설정을 재정의합니다 | `grpc`, `http/json`, `http/protobuf` |
116| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP 메트릭 엔드포인트, 일반 설정 재정의 | `http://localhost:4318/v1/metrics` |116| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP 메트릭 엔드포인트로, 일반 설정을 재정의합니다 | `http://localhost:4318/v1/metrics` |
117| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | 로그용 프로토콜, 일반 설정 재정의 | `grpc`, `http/json`, `http/protobuf` |117| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | 로그용 프로토콜로, 일반 설정을 재정의합니다 | `grpc`, `http/json`, `http/protobuf` |
118| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP 로그 엔드포인트, 일반 설정 재정의 | `http://localhost:4318/v1/logs` |118| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP 로그 엔드포인트로, 일반 설정을 재정의합니다 | `http://localhost:4318/v1/logs` |
119| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP용 인증 헤더 | `Authorization=Bearer token` |119| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP용 인증 헤더 | `Authorization=Bearer token` |
120| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | 메트릭용 인증 헤더, 일반 헤더와 병합 | `Authorization=Bearer token` |120| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | 메트릭용 인증 헤더로, 일반 헤더와 병합됩니다 | `Authorization=Bearer token` |
121| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | 로그용 인증 헤더, 일반 헤더와 병합 | `Authorization=Bearer token` |121| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | 로그용 인증 헤더로, 일반 헤더와 병합됩니다 | `Authorization=Bearer token` |
122| `OTEL_METRIC_EXPORT_INTERVAL` | 내보내기 간격(밀리초)(기본값: 60000) | `5000`, `60000` |122| `OTEL_METRIC_EXPORT_INTERVAL` | 밀리초 단위의 내보내기 간격(기본값: 60000) | `5000`, `60000` |
123| `OTEL_LOGS_EXPORT_INTERVAL` | 로그 내보내기 간격(밀리초)(기본값: 5000) | `1000`, `10000` |123| `OTEL_LOGS_EXPORT_INTERVAL` | 밀리초 단위의 로그 내보내기 간격(기본값: 5000) | `1000`, `10000` |
124| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 콘텐츠 로깅 활성화(기본값: 비활성화) | `1`로 활성화 |124| `OTEL_LOG_USER_PROMPTS` | 사용자 프롬프트 내용의 로깅을 활성화합니다(기본값: 비활성화) | 활성화하려면 `1` |
125| `OTEL_LOG_ASSISTANT_RESPONSES` | `assistant_response` 이벤트에서 어시스턴트 응답 텍스트 로깅 활성화(기본값: 비활성화). 설정하지 않으면 `OTEL_LOG_USER_PROMPTS`의 값으로 폴백합니다 | `1`로 활성화, `0`으로 편집됨 유지 |125| `OTEL_LOG_ASSISTANT_RESPONSES` | `assistant_response` 이벤트에서 어시스턴트 응답 텍스트의 로깅을 활성화합니다(기본값: 비활성화). 설정하지 않으면 `OTEL_LOG_USER_PROMPTS`의 값을 따릅니다 | 활성화하려면 `1`, 마스킹 상태를 유지하려면 `0` |
126| `OTEL_LOG_TOOL_DETAILS` | 도구 이벤트 및 추적 범위 속성에서 도구 매개변수 및 입력 인수 로깅 활성화: Bash 명령, MCP 서버 및 도구 이름, 스킬 이름, 사용자 작성 워크플로우 이름 및 도구 입력. 또한 `user_prompt` 이벤트에서 사용자 정의, 플러그인 및 MCP 명령 이름을 활성화하고, [비용 및 토큰 카운터](#cost-counter)에서 실제 에이전트, 스킬, 플러그인 및 MCP 서버 및 도구 이름을 활성화합니다(기본값: 비활성화). Claude Desktop의 기본 제공 서버의 경우, Claude Desktop이 소유한 세션에서 플래그가 꺼져 있어도 `mcp_server_name`/`mcp_tool_name`이 `tool_decision`/`tool_result`에서 내보내집니다. 예외는 Claude Code v2.1.214 이상 필요 | `1`로 활성화 |126| `OTEL_LOG_TOOL_DETAILS` | 도구 이벤트 및 트레이스 스팬 속성에서 도구 매개변수와 입력 인수의 로깅을 활성화합니다: Bash 명령, MCP 서버 및 도구 이름, 스킬 이름, 사용자가 작성한 워크플로 이름, 도구 입력. 또한 `user_prompt` 이벤트의 사용자 지정, 플러그인 및 MCP 명령 이름과 [비용 및 토큰 카운터](#cost-counter)의 실제 에이전트, 스킬, 플러그인, MCP 서버 및 도구 이름을 활성화합니다(기본값: 비활성화). Claude Desktop의 내장 서버의 경우, Claude Desktop이 소유한 세션에서는 플래그가 꺼져 있어도 `tool_decision`/`tool_result`에서 `mcp_server_name`/`mcp_tool_name`이 출력됩니다. 이 예외는 Claude Code v2.1.214 이상이 필요합니다 | 활성화하려면 `1` |
127| `OTEL_LOG_TOOL_CONTENT` | [`tool.output` 범위 이벤트](#tool-output-span-event)에서 도구 콘텐츠 로깅 활성화(기본값: 비활성화). 범위 속성은 [자체 게이트](#new-context-gates) 아래에서 도구 콘텐츠를 전달합니다. [추적](#traces-beta) 필요. 콘텐츠는 콘텐츠 제한(기본값 60KB)에서 잘립니다 | `1`로 활성화 |127| `OTEL_LOG_TOOL_CONTENT` | [`tool.output` 스팬 이벤트](#tool-output-span-event)에서 도구 콘텐츠의 로깅을 활성화합니다(기본값: 비활성화). 스팬 속성은 [자체 게이트](#new-context-gates)에 따라 도구 콘텐츠를 포함합니다. [트레이싱](#traces-beta)이 필요합니다. 콘텐츠는 콘텐츠 한도(기본값 60 KB)에서 잘립니다 | 활성화하려면 `1` |
128| `OTEL_LOG_MANAGED_SETTINGS` | 편집된 관리 설정 및 편집 전 설정의 SHA-256 다이제스트를 [관리 설정 해결됨](#managed-settings-resolved-event) 이벤트에 추가합니다(기본값: 비활성화). 프로젝트 또는 로컬 설정의 값은 이를 켜지 않습니다. Claude Code v2.1.274 이상 필요 | `1`로 활성화 |128| `OTEL_LOG_MANAGED_SETTINGS` | 마스킹된 관리형 설정과 마스킹 전 설정의 SHA-256 다이제스트를 [관리형 설정 확인](#managed-settings-resolved-event) 이벤트에 추가합니다(기본값: 비활성화). 프로젝트 또는 로컬 설정의 값으로는 켜지지 않습니다. Claude Code v2.1.274 이상이 필요합니다 | 활성화하려면 `1` |
129| `OTEL_LOG_RAW_API_BODIES` | 전체 Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 내보냅니다(기본값: 비활성화). 본문에는 전체 대화 기록이 포함됩니다. 이를 활성화하면 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS` 및 `OTEL_LOG_TOOL_CONTENT`가 드러낼 모든 것에 동의하는 것을 의미합니다 | 콘텐츠 제한(기본값 60KB)에서 잘린 인라인 본문의 경우 `1`, 또는 이벤트의 `body_ref` 포인터가 있는 디스크의 잘리지 않은 본문의 경우 `file:<dir>` |129| `OTEL_LOG_RAW_API_BODIES` | 전체 Anthropic Messages API 요청 및 응답 JSON을 `api_request_body` / `api_response_body` 로그 이벤트로 출력합니다(기본값: 비활성화). 본문에는 전체 대화 기록이 포함됩니다. 이를 활성화하면 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, `OTEL_LOG_TOOL_CONTENT`가 노출하는 모든 내용에 동의하는 것으로 간주됩니다 | 콘텐츠 한도(기본값 60 KB)에서 잘린 인라인 본문의 경우 `1`, 이벤트에 `body_ref` 포인터가 포함된 디스크상의 잘리지 않은 본문의 경우 `file:<dir>` |
130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠 제한: 모델 응답, 도구 콘텐츠, 시스템 프롬프트 및 원본 API 본문과 같은 콘텐츠 포함 속성의 최대 길이(잘림 마커 포함, UTF-16 코드 단위)(기본값: 61440, 즉 60KB). 기본값은 속성 값을 64KB로 제한하는 백엔드용으로 크기가 조정됩니다. 백엔드가 더 큰 값을 허용하는 경우에만 높이거나, 텔레메트리 볼륨을 줄이려면 낮추세요. OpenTelemetry SDK 속성 제한인 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 또는 해당 logrecord 및 범위 변형이 더 낮게 설정된 경우, Claude Code는 `[TRUNCATED ...]` 마커가 SDK 제한 내에 유지되도록 더 작은 값에서 잘립니다 | `262144` |130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 콘텐츠 한도: 모델 응답, 도구 콘텐츠, 시스템 프롬프트, 원시 API 본문 등 콘텐츠를 포함하는 속성의 최대 길이로, 잘림 표시를 포함하며 UTF-16 코드 단위로 측정됩니다(기본값: 61440, 즉 60 KB). 기본값은 속성 값을 64 KB로 제한하는 백엔드에 맞춰져 있습니다. 백엔드가 더 큰 값을 허용하는 경우에만 늘리고, 텔레메트리 양을 줄이려면 낮추세요. OpenTelemetry SDK 속성 한도인 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 또는 그 logrecord 및 span 변형 중 하나가 더 낮게 설정되어 있으면, Claude Code는 `[TRUNCATED ...]` 표시가 SDK 한도 내에 머물도록 그 더 작은 값에서 자릅니다 | `262144` |
131| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | 메트릭 시간성 선호도(기본값: `delta`). 백엔드가 누적 시간성을 예상하는 경우 `cumulative`로 설정 | `delta`, `cumulative` |131| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | 메트릭 시간성(temporality) 기본 설정(기본값: `delta`). 백엔드가 누적 시간성을 기대하는 경우 `cumulative`로 설정하세요 | `delta`, `cumulative` |
132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 헤더 새로 고침 간격(기본값: 1740000ms / 29분) | `900000` |132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 동적 헤더 새로 고침 간격(기본값: 1740000ms / 29분) | `900000` |
133 133
134`http/protobuf` 및 `http/json` 프로토콜의 경우, Claude Code는 각 내보내기 요청을 `Content-Length` 헤더와 함께 보냅니다.134`http/protobuf` 및 `http/json` 프로토콜의 경우 Claude Code는 각 내보내기 요청을 `Content-Length` 헤더와 함께 전송합니다.
135 135
136### mTLS 인증136### mTLS 인증
137 137
138OTLP 내보내기용 클라이언트 인증서를 구성하는 방법은 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 재정의를 통해 설정된 해당 신호에 사용되는 OTLP 프로토콜에 따라 다릅니다. 동일한 구성이 메트릭, 로그 및 추적에 적용됩니다.138OTLP 익스포터의 클라이언트 인증서를 구성하는 방법은 해당 신호에 사용 중인 OTLP 프로토콜에 따라 달라지며, 이 프로토콜은 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 재정의를 통해 설정됩니다. 동일한 구성이 메트릭, 로그, 트레이스에 적용됩니다.
139 139
140| 프로토콜 | 클라이언트 인증서 변수 | 수집기의 CA 신뢰 |140| 프로토콜 | 클라이언트 인증서 변수 | 수집기의 CA를 신뢰하는 방법 |
141| :- | :- | :- |141| :- | :- | :- |
142| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY` 및 선택적으로 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. [네트워크 구성](https://code.claude.com/docs/ko/network-config.md#mtls-authentication) 참조 | `NODE_EXTRA_CA_CERTS` |142| `http/protobuf`, `http/json` | `CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY`, 그리고 선택적으로 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`. [네트워크 구성](https://code.claude.com/docs/ko/network-config.md#mtls-authentication)을 참조하세요 | `NODE_EXTRA_CA_CERTS` |
143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 및 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, 또는 신호별로 다른 인증서를 사용하기 위한 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`와 같은 신호별 변형 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |143| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 및 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, 또는 신호마다 다른 인증서를 사용하려면 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`와 같은 신호별 변형 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |
144 144
145`grpc`의 경우, OpenTelemetry SDK는 표준 OTLP 변수를 직접 읽으므로 신호별 메트릭 변수를 설정하는 기존 구성은 계속 작동합니다. 관리되는 설정이 있는 머신에서는 Claude Code가 시작 시 [개발자가 설정한 신호별 자격 증명 및 엔드포인트를 제거할 수 있습니다](#how-managed-settings-lock-the-otlp-destination).145`grpc`의 경우 OpenTelemetry SDK가 표준 OTLP 변수를 직접 읽으므로, 신호별 메트릭 변수를 설정하는 기존 구성은 계속 작동합니다. 관리형 설정이 있는 머신에서는 Claude Code가 시작 시 [개발자가 설정한 신호별 자격 증명과 엔드포인트를 제거할 수 있습니다](#how-managed-settings-lock-the-otlp-destination).
146 146
147### 메트릭 카디널리티 제어147### 메트릭 카디널리티 제어
148 148
149다음 환경 변수는 카디널리티를 관리하기 위해 메트릭에 포함되는 속성을 제어합니다:149다음 환경 변수는 카디널리티를 관리하기 위해 메트릭에 포함되는 속성을 제어합니다.
150 150
151| 환경 변수 | 설명 | 기본값 | 비활성화 예제 |151| 환경 변수 | 설명 | 기본값 | 비활성화 예시 |
152| - | - | - | - |152| - | - | - | - |
153| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭에 session.id 및 클라우드 세션의 경우 ccr.session.id 속성 포함 | `true` | `false` |153| `OTEL_METRICS_INCLUDE_SESSION_ID` | 메트릭에 session.id 속성과, 클라우드 세션의 경우 ccr.session.id 속성을 포함합니다 | `true` | `false` |
154| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭에 app.version 속성 포함 | `false` | `true` |154| `OTEL_METRICS_INCLUDE_VERSION` | 메트릭에 app.version 속성을 포함합니다 | `false` | `true` |
155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭에 user.account\_uuid 및 user.account\_id 속성 포함 | `true` | `false` |155| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭에 user.account\_uuid 및 user.account\_id 속성을 포함합니다 | `true` | `false` |
156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭에 app.entrypoint 속성 포함 | `false` | `true` |156| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 메트릭에 app.entrypoint 속성을 포함합니다 | `false` | `true` |
157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `OTEL_RESOURCE_ATTRIBUTES`의 키를 메트릭 데이터포인트의 속성으로 포함 | `true` | `false` |157| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `OTEL_RESOURCE_ATTRIBUTES`의 키를 메트릭 데이터 포인트의 속성으로 포함합니다 | `true` | `false` |
158| `OTEL_METRICS_INCLUDE_REPOSITORY` | 메트릭 및 이벤트에 `vcs.*` [저장소 ID 속성](#repository-attributes) 포함. Claude Code v2.1.269 이상 필요 | `false` | `true` |158| `OTEL_METRICS_INCLUDE_REPOSITORY` | 메트릭과 이벤트에 `vcs.*` [저장소 식별 속성](#repository-attributes)을 포함합니다. Claude Code v2.1.269 이상이 필요합니다 | `false` | `true` |
159 159
160낮은 카디널리티는 일반적으로 더 나은 성능과 낮은 저장소 비용을 의미하지만 분석을 위한 덜 세분화된 데이터를 의미합니다.160일반적으로 카디널리티가 낮을수록 성능이 향상되고 스토리지 비용이 줄어들지만, 분석용 데이터의 세분성은 떨어집니다.
161 161
162### 추적(베타)162### 트레이스(베타)
163 163
164분산 추적은 각 사용자 프롬프트를 트리거하는 API 요청 및 도구 실행에 연결하는 범위를 내보내므로 추적 백엔드에서 전체 요청을 단일 추적으로 볼 수 있습니다.164분산 트레이싱은 각 사용자 프롬프트를 그 프롬프트가 트리거한 API 요청 및 도구 실행과 연결하는 스팬을 내보내므로, 트레이싱 백엔드에서 전체 요청을 하나의 트레이스로 볼 수 있습니다.
165 165
166추적은 기본적으로 꺼져 있습니다. 활성화하려면 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 및 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`을 모두 설정한 다음 `OTEL_TRACES_EXPORTER`를 설정하여 범위를 보낼 위치를 선택하세요. 추적은 엔드포인트, 프로토콜, 헤더 및 [mTLS](#mtls-authentication)에 대한 [일반 OTLP 구성](#common-configuration-variables)을 재사용합니다. 관리되는 설정이 있는 머신에서는 Claude Code가 시작 시 [개발자가 설정한 신호별 자격 증명 및 엔드포인트를 제거할 수 있습니다](#how-managed-settings-lock-the-otlp-destination).166트레이싱은 기본적으로 꺼져 있습니다. 활성화하려면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`과 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`을 모두 설정한 다음, `OTEL_TRACES_EXPORTER`를 설정하여 스팬을 보낼 위치를 선택하세요. 트레이스는 엔드포인트, 프로토콜, 헤더 및 [mTLS](#mtls-authentication)에 대해 [공통 OTLP 구성](#common-configuration-variables)을 재사용합니다. 관리형 설정이 있는 머신에서는 Claude Code가 시작 시 [개발자가 설정한 신호별 자격 증명과 엔드포인트를 제거할 수 있습니다](#how-managed-settings-lock-the-otlp-destination).
167 167
168| 환경 변수 | 설명 | 예제 값 |168| 환경 변수 | 설명 | 예시 값 |
169| - | - | - |169| - | - | - |
170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | 범위 추적 활성화(필수). `ENABLE_ENHANCED_TELEMETRY_BETA`도 허용됨 | `1` |170| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | 스팬 트레이싱을 활성화합니다(필수). `ENABLE_ENHANCED_TELEMETRY_BETA`도 허용됩니다 | `1` |
171| `OTEL_TRACES_EXPORTER` | 추적 내보내기 유형, 쉼표로 구분. 비활성화하려면 `none` 사용 | `console`, `otlp`, `none` |171| `OTEL_TRACES_EXPORTER` | 트레이스 익스포터 유형(쉼표로 구분). 비활성화하려면 `none` 사용 | `console`, `otlp`, `none` |
172| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | 추적용 프로토콜, `OTEL_EXPORTER_OTLP_PROTOCOL` 재정의 | `grpc`, `http/json`, `http/protobuf` |172| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | 트레이스용 프로토콜로, `OTEL_EXPORTER_OTLP_PROTOCOL`을 재정의합니다 | `grpc`, `http/json`, `http/protobuf` |
173| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | OTLP 추적 엔드포인트, `OTEL_EXPORTER_OTLP_ENDPOINT` 재정의 | `http://localhost:4318/v1/traces` |173| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | OTLP 트레이스 엔드포인트로, `OTEL_EXPORTER_OTLP_ENDPOINT`를 재정의합니다 | `http://localhost:4318/v1/traces` |
174| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | 추적용 인증 헤더, `OTEL_EXPORTER_OTLP_HEADERS`와 병합 | `Authorization=Bearer token` |174| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | 트레이스용 인증 헤더로, `OTEL_EXPORTER_OTLP_HEADERS`와 병합됩니다 | `Authorization=Bearer token` |
175| `OTEL_TRACES_EXPORT_INTERVAL` | 범위 배치 내보내기 간격(밀리초)(기본값: 5000) | `1000`, `10000` |175| `OTEL_TRACES_EXPORT_INTERVAL` | 밀리초 단위의 스팬 배치 내보내기 간격(기본값: 5000) | `1000`, `10000` |
176 176
177범위는 기본적으로 사용자 프롬프트 텍스트, 도구 입력 세부 정보 및 도구 콘텐츠를 편집합니다. `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1` 및 `OTEL_LOG_TOOL_CONTENT=1`을 설정하여 포함하세요.177스팬은 기본적으로 사용자 프롬프트 텍스트, 도구 입력 세부 정보 및 도구 콘텐츠를 마스킹합니다. 이를 포함하려면 `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1`, `OTEL_LOG_TOOL_CONTENT=1`을 설정하세요.
178 178
179추적이 활성화되면 Bash 및 PowerShell 하위 프로세스는 활성 도구 실행 범위의 W3C 추적 컨텍스트를 포함하는 `TRACEPARENT` 환경 변수를 자동으로 상속합니다. 이를 통해 `TRACEPARENT`를 읽는 모든 하위 프로세스는 자신의 범위를 동일한 추적 아래에 부모로 지정할 수 있으므로 Claude가 실행하는 스크립트 및 명령을 통한 엔드투엔드 분산 추적이 가능합니다.179트레이싱이 활성화되어 있으면 Bash 및 PowerShell 하위 프로세스는 활성 도구 실행 스팬의 W3C 트레이스 컨텍스트를 담은 `TRACEPARENT` 환경 변수를 자동으로 상속합니다. 이를 통해 `TRACEPARENT`를 읽는 모든 하위 프로세스가 자체 스팬을 같은 트레이스 아래에 둘 수 있어, Claude가 실행하는 스크립트와 명령 전반에 걸쳐 엔드투엔드 분산 트레이싱이 가능해집니다.
180 180
181추적이 활성화되고 Claude Code가 Anthropic API에 직접 연결된 경우, 각 모델 요청은 `claude_code.llm_request` 범위의 컨텍스트로 설정된 W3C `traceparent` 헤더를 전달하고, API의 `traceresponse` 헤더는 범위 링크로 기록됩니다. 이들은 함께 Claude Code의 클라이언트 측 범위를 호환 가능한 중개자를 통해 서버 측 추적에 연결합니다. 아웃바운드 HTTP MCP 요청은 동일한 방식으로 `traceparent`를 전달합니다. 헤더는 타사 제공자에게 전송되지 않습니다.181트레이싱이 활성화되어 있고 Claude Code가 Anthropic API에 직접 연결된 경우, 각 모델 요청에는 `claude_code.llm_request` 스팬의 컨텍스트로 설정된 W3C `traceparent` 헤더가 포함되며, API의 `traceresponse` 헤더는 스팬 링크로 기록됩니다. 이 둘이 함께 규격을 준수하는 모든 중개자를 거쳐 Claude Code의 클라이언트 측 스팬을 서버 측 트레이스에 연결합니다. 아웃바운드 HTTP MCP 요청도 같은 방식으로 `traceparent`를 포함합니다. 이 헤더는 서드파티 제공업체에는 전송되지 않습니다.
182 182
183기본적으로 모델 및 HTTP MCP 요청의 `traceparent` 헤더는 `ANTHROPIC_BASE_URL`이 설정되지 않았거나 Anthropic API를 가리킬 때만 전송됩니다. 일부 프록시는 인식되지 않는 헤더를 거부하기 때문입니다. 하위 프로세스 `TRACEPARENT` 변수는 일관성을 위해 동일한 스위치로 제어됩니다. 사용자 정의 `ANTHROPIC_BASE_URL` 프록시를 통해 Claude Code를 실행하고 추적 컨텍스트를 전파하려면 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`을 설정하세요.183일부 프록시는 인식되지 않는 헤더를 거부하므로, 기본적으로 모델 및 HTTP MCP 요청의 `traceparent` 헤더는 `ANTHROPIC_BASE_URL`이 설정되지 않았거나 Anthropic API를 가리킬 때만 전송됩니다. 일관성을 위해 하위 프로세스의 `TRACEPARENT` 변수도 같은 스위치로 제어됩니다. 사용자 지정 `ANTHROPIC_BASE_URL` 프록시를 통해 Claude Code를 실행하면서 트레이스 컨텍스트를 전파하려면 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`을 설정하세요.
184 184
185Agent SDK 및 `-p`로 시작된 비대화형 세션에서 Claude Code는 각 상호작용 범위를 시작할 때 자신의 환경에서 `TRACEPARENT` 및 `TRACESTATE`를 읽습니다. 이를 통해 임베딩 프로세스는 활성 W3C 추적 컨텍스트를 하위 프로세스에 전달할 수 있으므로 Claude Code의 범위가 호출자의 분산 추적의 자식으로 나타납니다. 대화형 세션은 CI 또는 컨테이너 환경의 주변 값을 실수로 상속하는 것을 피하기 위해 인바운드 `TRACEPARENT`를 무시합니다.185Agent SDK 및 `-p`로 시작된 비대화형 세션에서 Claude Code는 각 상호작용 스팬을 시작할 때 자체 환경에서 `TRACEPARENT`와 `TRACESTATE`도 읽습니다. 이를 통해 임베딩 프로세스가 활성 W3C 트레이스 컨텍스트를 하위 프로세스에 전달하여 Claude Code의 스팬이 호출자의 분산 트레이스의 자식으로 나타나게 할 수 있습니다. 대화형 세션은 CI 또는 컨테이너 환경의 주변 값을 실수로 상속하지 않도록 인바운드 `TRACEPARENT`를 무시합니다.
186 186
187인바운드 추적 컨텍스트는 [이벤트](#events)에도 적용됩니다. `TRACEPARENT`가 설정된 Agent SDK 및 `-p` 세션에서 각 OTLP 이벤트 로그 레코드는 추적 내보내기가 구성되지 않은 경우에도 로깅 백엔드가 이벤트를 추적의 나머지와 상관시킬 수 있도록 애플리케이션의 추적에 조인하는 `trace_id` 및 `span_id` 값을 전달합니다.187인바운드 트레이스 컨텍스트는 [이벤트](#events)에도 적용됩니다. `TRACEPARENT`가 설정된 Agent SDK 및 `-p` 세션에서는 트레이스 익스포터가 구성되지 않은 경우에도 각 OTLP 이벤트 로그 레코드에 애플리케이션의 트레이스와 연결하는 `trace_id` 및 `span_id` 값이 포함되므로, 로깅 백엔드에서 이벤트를 트레이스의 나머지 부분과 연관시킬 수 있습니다.
188 188
189상호작용이 활성화되는 동안 내보낸 레코드는 권한 프롬프트 콜백이나 시작 중에 버퍼링되고 나중에 내보낸 레코드와 같이 범위의 비동기 컨텍스트 외부에서 Claude Code가 내보낸 경우에도 상호작용 범위의 ID를 전달합니다. 활성 상호작용 범위가 없는 상태에서 내보낸 레코드는 인바운드 `TRACEPARENT` ID를 직접 전달합니다.189상호작용이 활성 상태일 때 출력된 레코드는 Claude Code가 스팬의 비동기 컨텍스트 밖에서 출력하더라도(예: 권한 프롬프트 콜백에서, 또는 시작 중에 버퍼링되었다가 나중에 내보내진 레코드의 경우) 상호작용 스팬의 ID를 포함합니다. 활성 상호작용 스팬이 없을 때 출력된 레코드는 인바운드 `TRACEPARENT` ID를 직접 포함합니다.
190 190
191#### 범위 계층 구조191#### 스팬 계층 구조
192 192
193각 사용자 프롬프트는 `claude_code.interaction` 루트 범위를 시작합니다. API 호출, 도구 호출 및 훅 실행은 자식으로 기록됩니다. 도구 범위는 자체 두 개의 자식 범위를 가집니다: 하나는 권한 결정을 기다리는 데 소요된 시간이고 다른 하나는 실행 자체입니다. Agent 도구 또는 레거시 Task 도구가 하위 에이전트를 생성하면 하위 에이전트의 API 및 도구 범위는 부모의 `claude_code.tool` 범위 아래에 중첩됩니다.193각 사용자 프롬프트는 `claude_code.interaction` 루트 스팬을 시작합니다. API 호출, 도구 호출 및 훅 실행은 그 자식으로 기록됩니다. 도구 스팬에는 자체 자식 스팬이 두 개 있습니다. 하나는 권한 결정을 기다리는 데 소요된 시간에 대한 것이고, 다른 하나는 실행 자체에 대한 것입니다. Agent 도구 또는 레거시 Task 도구가 서브에이전트를 생성하면, 서브에이전트의 API 및 도구 스팬은 부모의 `claude_code.tool` 스팬 아래에 중첩됩니다.
194 194
195```text theme={null}195```text theme={null}
196claude_code.interaction196claude_code.interaction
202 └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans202 └── (Agent tool) subagent claude_code.llm_request / claude_code.tool spans
203```203```
204 204
205Agent SDK 및 `claude -p` 세션에서 `TRACEPARENT`가 환경에 설정되면 `claude_code.interaction` 자체가 호출자의 범위의 자식이 됩니다.205Agent SDK 및 `claude -p` 세션에서는 환경에 `TRACEPARENT`가 설정되어 있으면 `claude_code.interaction` 자체가 호출자 스팬의 자식이 됩니다.
206 206
207`PreToolUse` 훅이 [도구 호출을 나중으로 연기](https://code.claude.com/docs/ko/hooks.md#defer-a-tool-call-for-later)할 때, Claude Code는 이를 연기한 턴의 추적 컨텍스트를 저장합니다. 세션을 재개하고 도구가 다시 실행되면 도구의 범위는 턴의 `claude_code.interaction` 범위의 자식으로 이전 턴의 추적에 조인합니다.207`PreToolUse` 훅이 [도구 호출을 연기](https://code.claude.com/docs/ko/hooks.md#defer-a-tool-call-for-later)하면 Claude Code는 연기한 턴의 트레이스 컨텍스트를 저장합니다. 세션을 재개하여 도구가 다시 실행되면, 도구의 스팬은 해당 턴의 `claude_code.interaction` 스팬의 자식으로서 그 이전 턴의 트레이스에 합류합니다.
208 208
209#### 범위 속성209#### 스팬 속성
210 210
211모든 범위는 [표준 속성](#standard-attributes)과 이름과 일치하는 `span.type` 속성을 전달합니다. 아래 표는 각 범위에 설정된 추가 속성을 나열합니다. `llm_request`, `tool.execution` 및 `hook` 범위는 실패를 기록할 때 OpenTelemetry 상태 `ERROR`를 설정합니다. 다른 범위는 항상 상태 `UNSET`으로 끝납니다.211모든 스팬은 [표준 속성](#standard-attributes)과 함께 이름에 해당하는 `span.type` 속성을 포함합니다. 아래 표에는 각 스팬에 설정되는 추가 속성이 나열되어 있습니다. `llm_request`, `tool.execution`, `hook` 스팬은 실패를 기록할 때 OpenTelemetry 상태를 `ERROR`로 설정하며, 다른 스팬은 항상 `UNSET` 상태로 종료됩니다.
212 212
213**`claude_code.interaction`**213**`claude_code.interaction`**
214 214
215| 속성 | 설명 | 게이트 |215| 속성 | 설명 | 게이트 |
216| - | - | - |216| - | - | - |
217| `user_prompt` | 프롬프트 텍스트. 게이트가 설정되지 않으면 값은 `<REDACTED>`입니다 | `OTEL_LOG_USER_PROMPTS` |217| `user_prompt` | 프롬프트 텍스트. 게이트가 설정되지 않으면 값은 `<REDACTED>`입니다 | `OTEL_LOG_USER_PROMPTS` |
218| `user_prompt_length` | 프롬프트 길이(문자) | |218| `user_prompt_length` | 문자 단위의 프롬프트 길이 | |
219| `interaction.sequence` | 상호작용의 1 기반 카운터, [`event.sequence`](#event-correlation-attributes)에 설명된 대로 Claude Code 프로세스당 계산되며 세션당이 아님 | |219| `interaction.sequence` | 1부터 시작하는 상호작용 카운터로, [`event.sequence`](#event-correlation-attributes)에서 설명한 대로 세션이 아닌 Claude Code 프로세스 단위로 계산됩니다 | |
220| `parent.source` | 범위가 추적 부모를 얻은 방법: 인바운드 `TRACEPARENT`에서 부모가 될 때 `env`, 자신의 추적을 시작할 때 `none`. Claude Code v2.1.268 이상 필요 | |220| `parent.source` | 스팬이 트레이스 부모를 얻은 방식: 인바운드 `TRACEPARENT` 아래에 부모가 지정된 경우 `env`, 자체 트레이스를 시작한 경우 `none`. Claude Code v2.1.268 이상이 필요합니다 | |
221| `interaction.duration_ms` | 턴의 벽시계 지속 시간 | |221| `interaction.duration_ms` | 턴의 실제 경과 시간 | |
222 222
223**`claude_code.llm_request`**223**`claude_code.llm_request`**
224 224
225| 속성 | 설명 | 게이트 |225| 속성 | 설명 | 게이트 |
226| - | - | - |226| - | - | - |
227| `model` | 모델 식별자 | |227| `model` | 모델 식별자 | |
228| `gen_ai.system` | 항상 `anthropic`. OpenTelemetry GenAI 의미론적 규칙 | |228| `gen_ai.system` | 항상 `anthropic`. OpenTelemetry GenAI 시맨틱 규칙 | |
229| `gen_ai.request.model` | `model`과 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |229| `gen_ai.request.model` | `model`과 같은 값. OpenTelemetry GenAI 시맨틱 규칙 | |
230| `query_source` | `repl_main_thread` 또는 하위 에이전트 이름과 같이 요청을 발급한 하위 시스템 | `ENABLE_BETA_TRACING_DETAILED` |230| `query_source` | 요청을 발행한 하위 시스템(예: `repl_main_thread` 또는 서브에이전트 이름) | `ENABLE_BETA_TRACING_DETAILED` |
231| `query_source_safe` | `query_source`의 제한된 형식, 상세 베타 추적 활성 여부와 관계없이 내보내짐, `repl_main_thread` 또는 `agent.builtin.general-purpose`와 같은 값. `:`는 `.`이 되고 사용자 명명 에이전트는 `agent.custom`으로 나타납니다. Claude Code v2.1.268 이상 필요 | |231| `query_source_safe` | 상세 베타 트레이싱의 활성화 여부와 관계없이 출력되는 `query_source`의 제한된 형태로, `repl_main_thread` 또는 `agent.builtin.general-purpose`와 같은 값을 가집니다. `:`는 `.`이 되며, 사용자가 이름을 지정한 에이전트는 `agent.custom`으로 표시됩니다. Claude Code v2.1.268 이상이 필요합니다 | |
232| `agent_id` | 요청을 발급한 하위 에이전트 또는 팀원의 식별자. 주 세션에서는 없음 | |232| `agent_id` | 요청을 발행한 서브에이전트 또는 팀원의 식별자. 메인 세션에는 없습니다 | |
233| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 주 세션 및 직접 생성된 에이전트에서는 없음 | |233| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 메인 세션 및 메인 세션에서 직접 생성된 에이전트에는 없습니다 | |
234| `workflow.run_id` | 이 에이전트를 생성한 [Workflow](https://code.claude.com/docs/ko/workflows.md) 도구 실행의 실행 식별자, `wf_` 접두사. 워크플로우에 의해 생성되지 않은 에이전트에서는 없음 | |234| `workflow.run_id` | 이 에이전트를 생성한 [Workflow](https://code.claude.com/docs/ko/workflows.md) 도구 실행의 실행 식별자로, 접두사 `wf_`가 붙습니다. 워크플로에 의해 생성되지 않은 에이전트에는 없습니다 | |
235| `workflow.name` | 이 에이전트를 생성한 워크플로우의 이름. 사용자 작성 이름은 게이트가 설정되지 않으면 `custom`으로 대체됨 | `OTEL_LOG_TOOL_DETAILS` |235| `workflow.name` | 이 에이전트를 생성한 워크플로의 이름. 게이트가 설정되지 않으면 사용자가 작성한 이름은 `custom`으로 대체됩니다 | `OTEL_LOG_TOOL_DETAILS` |
236| `speed` | `fast` 또는 `normal` | |236| `speed` | `fast` 또는 `normal` | |
237| `effort` | 요청에 적용된 [노력 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level): `low`, `medium`, `high`, `xhigh` 또는 `max`. 예를 들어 노력을 지원하지 않는 모델에서 Claude Code가 노력 수준을 보내지 않을 때 없음. Claude Code v2.1.274 이상 필요 | |237| `effort` | 요청에 적용된 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level): `low`, `medium`, `high`, `xhigh` 또는 `max`. Claude Code가 effort 수준을 보내지 않는 경우(예: effort를 지원하지 않는 모델)에는 없습니다. Claude Code v2.1.274 이상이 필요합니다 | |
238| `llm_request.context` | 부모 범위에 따라 `interaction`, `tool` 또는 `standalone` | |238| `llm_request.context` | 부모 스팬에 따라 `interaction`, `tool` 또는 `standalone` | |
239| `duration_ms` | 재시도를 포함한 벽시계 지속 시간 | |239| `duration_ms` | 재시도를 포함한 실제 경과 시간 | |
240| `ttft_ms` | 첫 번째 토큰까지의 시간(밀리초) | |240| `ttft_ms` | 밀리초 단위의 첫 토큰까지의 시간 | |
241| `first_content_ms` | 요청 시작부터 성공한 시도의 첫 번째 콘텐츠 블록까지의 시간(밀리초). 비스트리밍 경로로 폴백한 요청에서는 없음. Claude Code v2.1.268 이상 필요 | |241| `first_content_ms` | 요청 시작부터 성공한 시도의 첫 콘텐츠 블록까지의 시간(밀리초). 비스트리밍 경로로 폴백된 요청에는 없습니다. Claude Code v2.1.268 이상이 필요합니다 | |
242| `input_tokens` | API 사용 블록의 입력 토큰 수. 프롬프트 캐시에서 읽거나 프롬프트 캐시에 기록된 토큰은 제외되며, 이는 `cache_read_tokens` 및 `cache_creation_tokens`에 보고됩니다 | |242| `input_tokens` | API 사용량 블록의 입력 토큰 수. 프롬프트 캐시에서 읽거나 캐시에 쓴 토큰은 제외되며, 이는 `cache_read_tokens` 및 `cache_creation_tokens`에 보고됩니다 | |
243| `output_tokens` | 출력 토큰 수 | |243| `output_tokens` | 출력 토큰 수 | |
244| `cache_read_tokens` | 프롬프트 캐시에서 읽은 토큰 | |244| `cache_read_tokens` | 프롬프트 캐시에서 읽은 토큰 | |
245| `cache_creation_tokens` | 프롬프트 캐시에 기록된 토큰 | |245| `cache_creation_tokens` | 프롬프트 캐시에 쓴 토큰 | |
246| `request_id` | API 요청 ID. `request_id` [이벤트 상관 속성](#event-correlation-attributes)과 동일한 값 | |246| `request_id` | API 요청 ID. `request_id` [이벤트 상관 속성](#event-correlation-attributes)과 같은 값 | |
247| `gen_ai.response.id` | `request_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |247| `gen_ai.response.id` | `request_id`와 같은 값. OpenTelemetry GenAI 시맨틱 규칙 | |
248| `client_request_id` | 최종 시도의 클라이언트 생성 `x-client-request-id` | |248| `client_request_id` | 최종 시도의 클라이언트 생성 `x-client-request-id` | |
249| `attempt` | 이 요청에 대해 수행된 총 시도 | |249| `attempt` | 이 요청에 대해 이루어진 총 시도 횟수 | |
250| `success` | `true` 또는 `false` | |250| `success` | `true` 또는 `false` | |
251| `status_code` | 요청이 실패했을 때 HTTP 상태 코드 | |251| `status_code` | 요청이 실패한 경우의 HTTP 상태 코드 | |
252| `error` | 요청이 실패했을 때 오류 메시지 | |252| `error` | 요청이 실패한 경우의 오류 메시지 | |
253| `error_class` | 요청이 실패했을 때 짧은 오류 클래스 토큰, `api_timeout` 또는 `server_overload`와 같음. Claude Code v2.1.268 이상 필요 | |253| `error_class` | 요청이 실패한 경우의 짧은 오류 클래스 토큰(예: `api_timeout` 또는 `server_overload`). Claude Code v2.1.268 이상이 필요합니다 | |
254| `response.has_tool_call` | 응답에 도구 사용 블록이 포함되었을 때 `true` | |254| `response.has_tool_call` | 응답에 도구 사용 블록이 포함된 경우 `true` | |
255| `stop_reason` | API 응답 `stop_reason`, `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` 또는 `refusal`과 같음 | |255| `stop_reason` | API 응답의 `stop_reason`(예: `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` 또는 `refusal`) | |
256| `gen_ai.response.finish_reasons` | `stop_reason`과 동일한 값, 문자열 배열로 래핑됨. OpenTelemetry GenAI 의미론적 규칙 | |256| `gen_ai.response.finish_reasons` | `stop_reason`과 같은 값을 문자열 배열로 감싼 것. OpenTelemetry GenAI 시맨틱 규칙 | |
257 257
258각 재시도 시도는 `attempt` 및 `client_request_id` 속성이 있는 `gen_ai.request.attempt` 범위 이벤트로도 기록됩니다.258각 재시도도 `attempt` 및 `client_request_id` 속성을 가진 `gen_ai.request.attempt` 스팬 이벤트로 기록됩니다.
259 259
260**`claude_code.tool`**260**`claude_code.tool`**
261 261
262| 속성 | 설명 | 게이트 |262| 속성 | 설명 | 게이트 |
263| - | - | - |263| - | - | - |
264| `tool_name` | 도구 이름 | |264| `tool_name` | 도구 이름 | |
265| `tool_name_safe` | 사용자 선택 이름을 포함하지 않는 `tool_name` 형식. 기본 제공 도구 이름은 그대로 전달됩니다. MCP 도구 이름은 `mcp_other`로 나타나며, `browser_*`라는 `playwright` 도구와 같이 몇 가지 고정된 모양과 일치하는 도구 이름은 그대로 전달됩니다. Claude Code v2.1.268 이상 필요 | |265| `tool_name_safe` | 사용자가 선택한 이름을 포함하지 않는 `tool_name`의 형태. 내장 도구 이름은 그대로 전달됩니다. MCP 도구 이름은 `mcp_other`로 표시되지만, `browser_*`라는 이름의 `playwright` 도구처럼 몇 가지 고정된 형태와 일치하는 도구 이름은 그대로 전달됩니다. Claude Code v2.1.268 이상이 필요합니다 | |
266| `bash_command_class` | Bash 도구의 경우: 고정 목록의 명령 첫 번째 프로그램 범주, `vcs` 또는 `package_manager`와 같음. 목록 외부의 프로그램의 경우 `other`, 줄을 구문 분석할 수 없을 때 `unparsed`. Claude Code v2.1.268 이상 필요 | |266| `bash_command_class` | Bash 도구의 경우: 고정된 목록에서 가져온 명령의 첫 번째 프로그램의 범주(예: `vcs` 또는 `package_manager`). 목록에 없는 프로그램은 `other`, 줄을 파싱할 수 없는 경우 `unparsed` Claude Code v2.1.268 이상이 필요합니다 | |
267| `bash_argv0` | Bash 도구의 경우: 동일한 고정 목록에 있을 때 명령의 첫 번째 프로그램, `git` 또는 `npm`과 같음. 목록 외부의 모든 프로그램의 경우 `other`. Claude Code v2.1.268 이상 필요 | |267| `bash_argv0` | Bash 도구의 경우: 명령의 첫 번째 프로그램이 같은 고정 목록에 있을 때 그 프로그램(예: `git` 또는 `npm`). 목록에 없는 모든 프로그램은 `other`. Claude Code v2.1.268 이상이 필요합니다 | |
268| `duration_ms` | 권한 대기 및 실행을 포함한 벽시계 지속 시간 | |268| `duration_ms` | 권한 대기 및 실행을 포함한 실제 경과 시간 | |
269| `result_tokens` | 도구 결과의 대략적인 토큰 크기 | |269| `result_tokens` | 도구 결과의 대략적인 토큰 크기 | |
270| `agent_id` | 도구를 실행한 하위 에이전트 또는 팀원의 식별자. 주 세션에서는 없음 | |270| `agent_id` | 도구를 실행한 서브에이전트 또는 팀원의 식별자. 메인 세션에는 없습니다 | |
271| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 주 세션 및 직접 생성된 에이전트에서는 없음 | |271| `parent_agent_id` | 이 에이전트를 생성한 에이전트의 식별자. 메인 세션 및 메인 세션에서 직접 생성된 에이전트에는 없습니다 | |
272| `workflow.run_id` | 이 에이전트를 생성한 Workflow 도구 실행의 실행 식별자, `wf_` 접두사. 워크플로우에 의해 생성되지 않은 에이전트에서는 없음 | |272| `workflow.run_id` | 이 에이전트를 생성한 Workflow 도구 실행의 실행 식별자로, 접두사 `wf_`가 붙습니다. 워크플로에 의해 생성되지 않은 에이전트에는 없습니다 | |
273| `workflow.name` | 이 에이전트를 생성한 워크플로우의 이름. 사용자 작성 이름은 게이트가 설정되지 않으면 `custom`으로 대체됨 | `OTEL_LOG_TOOL_DETAILS` |273| `workflow.name` | 이 에이전트를 생성한 워크플로의 이름. 게이트가 설정되지 않으면 사용자가 작성한 이름은 `custom`으로 대체됩니다 | `OTEL_LOG_TOOL_DETAILS` |
274| `tool_use_id` | 이 호출에 대한 모델의 `tool_use` 블록 ID. [tool\_result](#tool-result-event) 및 [tool\_decision](#tool-decision-event) 이벤트 및 훅 페이로드의 `tool_use_id`와 일치하므로 범위를 해당 레코드에 조인할 수 있습니다 | |274| `tool_use_id` | 이 호출에 대한 모델의 `tool_use` 블록 id. [tool\_result](#tool-result-event) 및 [tool\_decision](#tool-decision-event) 이벤트와 훅 페이로드의 `tool_use_id`와 일치하므로, 스팬을 해당 레코드와 연결할 수 있습니다 | |
275| `gen_ai.tool.call.id` | `tool_use_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |275| `gen_ai.tool.call.id` | `tool_use_id`와 같은 값. OpenTelemetry GenAI 시맨틱 규칙 | |
276| `file_path` | Read, Edit 및 Write 도구의 대상 파일 경로 | `OTEL_LOG_TOOL_DETAILS` |276| `file_path` | Read, Edit, Write 도구의 대상 파일 경로 | `OTEL_LOG_TOOL_DETAILS` |
277| `full_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |277| `full_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |
278| `skill_name` | Skill 도구의 스킬 이름 | `OTEL_LOG_TOOL_DETAILS` |278| `skill_name` | Skill 도구의 스킬 이름 | `OTEL_LOG_TOOL_DETAILS` |
279| `subagent_type` | Agent 도구 또는 레거시 Task 도구의 하위 에이전트 유형 | `OTEL_LOG_TOOL_DETAILS` |279| `subagent_type` | Agent 도구 또는 레거시 Task 도구의 서브에이전트 유형 | `OTEL_LOG_TOOL_DETAILS` |
280 280
281**`claude_code.tool`의 `tool.output` 범위 이벤트**281**`claude_code.tool`의 `tool.output` 스팬 이벤트**
282 282
283`OTEL_LOG_TOOL_CONTENT=1`을 설정하면 Read 및 Bash 호출은 `claude_code.tool` 범위에 `tool.output` 범위 이벤트를 기록할 수 있습니다. Edit 및 Write 호출은 `OTEL_LOG_TOOL_DETAILS=1`도 설정할 때만 하나를 기록합니다. 해당 변수는 해당 두 도구로 범위가 지정되지 않으므로 구성 표의 [행](#common-configuration-variables)에서 다른 곳에 추가하는 인수를 확인하세요.283`OTEL_LOG_TOOL_CONTENT=1`을 설정하면 Read 및 Bash 호출이 `claude_code.tool` 스팬에 `tool.output` 스팬 이벤트를 기록할 수 있습니다. Edit 및 Write 호출은 `OTEL_LOG_TOOL_DETAILS=1`도 설정한 경우에만 이를 기록합니다. 이 변수는 이 두 도구에만 국한되지 않으므로, 다른 곳에서 추가되는 인수는 [구성 표의 해당 행](#common-configuration-variables)을 확인하세요.
284 284
285MCP 도구, WebFetch 및 WebSearch도 Claude Code v2.1.283 이상에서 이 이벤트를 기록합니다.285Claude Code v2.1.283 이상에서는 MCP 도구, WebFetch, WebSearch도 이 이벤트를 기록합니다.
286 286
287Claude Code는 도구 호출의 성공적인 반환에서 이 이벤트를 작성하므로 오류를 발생시키는 호출은 도구에 관계없이 아무것도 기록하지 않습니다. 반환하는 호출 중에서 다음에 대해 `tool.output` 이벤트를 기록하지 않습니다:287Claude Code는 도구 호출이 성공적으로 반환될 때 이 이벤트를 기록하므로, 도구와 관계없이 오류를 발생시킨 호출은 아무것도 기록하지 않습니다. 반환된 호출 중에서도 다음의 경우에는 `tool.output` 이벤트를 기록하지 않습니다.
288 288
289* Read, Edit, Write, Bash, WebFetch, WebSearch 및 MCP 도구 이외의 도구에 대한 호출289* Read, Edit, Write, Bash, WebFetch, WebSearch 및 MCP 도구 이외의 도구 호출
290* 이미지, PDF 또는 콘텐츠가 변경되지 않은 파일의 재읽기와 같이 파일 텍스트 이외의 것을 반환하는 Read290* 이미지, PDF 또는 내용이 변경되지 않은 파일의 재읽기처럼 파일 텍스트 이외의 것을 반환하는 Read
291* `OTEL_LOG_TOOL_DETAILS=1`도 설정하지 않으면 Edit 또는 Write 호출291* `OTEL_LOG_TOOL_DETAILS=1`도 설정하지 않은 경우의 Edit 또는 Write 호출
292* 대기 중인 메시지가 Claude에 전달될 수 있도록 Claude Code가 실행 중에 백그라운드로 옮긴 WebFetch 또는 WebSearch 호출. 나중에 도착하는 결과도 기록되지 않습니다. Claude Code가 호출을 옮기는 시점은 터미널의 경우 [Claude Code가 대기열에 넣은 항목을 보내는 시점](https://code.claude.com/docs/ko/interactive-mode.md#when-claude-code-sends-what-you-queued)을, Agent SDK 세션의 경우 [`priority` 필드](https://code.claude.com/docs/ko/agent-sdk/typescript#sdkusermessage)를 참조하세요292* 대기 중인 메시지가 Claude에 전달될 수 있도록 Claude Code가 실행 중에 백그라운드로 이동한 WebFetch 또는 WebSearch 호출. 나중에 도착하는 결과도 기록되지 않습니다. Claude Code가 호출을 이동하는 시점은 터미널의 경우 [대기열에 넣은 항목을 Claude Code가 보내는 시점](https://code.claude.com/docs/ko/interactive-mode.md#when-claude-code-sends-what-you-queued)을, Agent SDK 세션의 경우 [`priority` 필드](https://code.claude.com/docs/ko/agent-sdk/typescript#sdkusermessage)를 참조하세요
293 293
294이벤트는 각각 콘텐츠 제한(기본값 60KB)에서 잘린 이러한 속성을 전달합니다. `Gated by`는 `OTEL_LOG_TOOL_CONTENT=1` 위에 속성이 필요한 변수의 이름을 지정하고, Edit 및 Write의 경우 해당 변수는 속성이 아닌 이벤트 자체를 게이트합니다.294이 이벤트에는 다음 속성이 포함되며, 각각 콘텐츠 한도(기본값 60 KB)에서 잘립니다. `게이트`는 `OTEL_LOG_TOOL_CONTENT=1`에 더해 속성에 필요한 변수를 나타내며, Edit 및 Write의 경우 해당 변수는 속성이 아니라 이벤트 자체를 제어합니다.
295 295
296| 속성 | 설명 | 게이트 |296| 속성 | 설명 | 게이트 |
297| - | - | - |297| - | - | - |
298| `content` | Read 도구가 반환한 텍스트 또는 Write 호출이 작성하도록 요청한 텍스트 | Write 도구의 경우 `OTEL_LOG_TOOL_DETAILS` |298| `content` | Read 도구가 반환한 텍스트 또는 Write 호출이 쓰도록 요청받은 텍스트 | Write 도구의 경우 `OTEL_LOG_TOOL_DETAILS` |
299| `output` | Bash 도구의 경우 명령의 결합된 출력, stderr이 stdout에 인터리브됨. MCP 도구, WebFetch 또는 WebSearch의 경우 도구가 반환한 결과: 줄바꿈으로 조인된 텍스트 블록, 이미지 또는 문서가 `[image]`와 같은 자리 표시자로 대체됨 | |299| `output` | Bash 도구의 경우 stderr가 stdout에 섞인 명령의 결합 출력. MCP 도구, WebFetch 또는 WebSearch의 경우 도구가 반환한 결과로, 텍스트 블록은 줄바꿈으로 연결되고 이미지나 문서는 `[image]`와 같은 자리 표시자로 대체됩니다 | |
300| `diff` | Edit 도구가 적용한 구조화된 패치 | `OTEL_LOG_TOOL_DETAILS` |300| `diff` | Edit 도구가 적용한 구조화된 패치 | `OTEL_LOG_TOOL_DETAILS` |
301| `file_path` | Read, Edit 및 Write 도구의 대상 파일 경로, 동일한 이름의 범위 속성 반복 | `OTEL_LOG_TOOL_DETAILS` |301| `file_path` | Read, Edit, Write 도구의 대상 파일 경로로, 같은 이름의 스팬 속성을 반복합니다 | `OTEL_LOG_TOOL_DETAILS` |
302| `bash_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |302| `bash_command` | Bash 도구의 명령 문자열 | `OTEL_LOG_TOOL_DETAILS` |
303 303
304부모 범위의 `tool_name` 속성은 이벤트가 어느 도구에서 왔는지 알려줍니다. 콘텐츠 제한에서 잘린 속성에는 `<attribute>_truncated` 및 `<attribute>_original_length`가 함께 제공됩니다.304부모 스팬의 `tool_name` 속성으로 이벤트가 어느 도구에서 왔는지 알 수 있습니다. 콘텐츠 한도에서 잘린 속성에는 `<attribute>_truncated` 및 `<attribute>_original_length`가 함께 포함됩니다.
305 305
306**`claude_code.tool.blocked_on_user`**306**`claude_code.tool.blocked_on_user`**
307 307
308| 속성 | 설명 | 게이트 |308| 속성 | 설명 | 게이트 |
309| - | - | - |309| - | - | - |
310| `duration_ms` | 권한 결정을 기다리는 데 소요된 시간 | |310| `duration_ms` | 권한 결정을 기다리는 데 소요된 시간 | |
311| `decision` | `accept`, `reject` 또는 `cancelled`. `cancelled`는 Claude Code가 도구 호출에 대한 권한 결정을 더 이상 기다리지 않고 도구를 실행하지 않았음을 의미합니다 | |311| `decision` | `accept`, `reject` 또는 `cancelled`. `cancelled`는 Claude Code가 도구 호출에 대한 권한 결정 대기를 중단하고 도구를 실행하지 않았음을 의미합니다 | |
312| `source` | `accept` 또는 `reject`의 경우 결정의 출처로, `config`, `hook` 또는 `user_temporary`와 같으며 각 의미는 [도구 결정 이벤트](#tool-decision-event)에 설명되어 있습니다. `cancelled`의 경우 결정이 내려지기 전에 대기를 종료한 원인으로, `user_abort`와 같습니다 | |312| `source` | `accept` 또는 `reject`의 경우 결정이 나온 출처(예: `config`, `hook` 또는 `user_temporary`)로, 의미는 [도구 결정 이벤트](#tool-decision-event)에 설명되어 있습니다. `cancelled`의 경우 결정이 내려지기 전에 대기를 종료시킨 원인(예: `user_abort`) | |
313 313
314`source`가 `user_abort`인 `cancelled` 결정은 권한 프롬프트 또는 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 검사가 보류 중인 동안 즉시 전달해야 하는 메시지가 턴을 중단했음을 의미합니다. 예를 들어 자동 모드 검사 중에 사용자가 대기열에 메시지를 넣어 두었다가 [즉시 보낸](https://code.claude.com/docs/ko/interactive-mode.md#when-claude-code-sends-what-you-queued) 경우입니다.314`source`가 `user_abort`인 `cancelled` 결정은 권한 프롬프트 또는 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 검사가 보류 중인 동안 즉시 전달이 필요한 메시지가 턴을 중단시켰음을 의미합니다. 예를 들어 자동 모드 검사 중에 사용자가 대기열에 메시지를 넣어 두었다가 [즉시 보낸](https://code.claude.com/docs/ko/interactive-mode.md#when-claude-code-sends-what-you-queued) 경우입니다.
315 315
316**`claude_code.tool.execution`**316**`claude_code.tool.execution`**
317 317
318| 속성 | 설명 | 게이트 |318| 속성 | 설명 | 게이트 |
319| - | - | - |319| - | - | - |
320| `duration_ms` | 도구 본문을 실행하는 데 소요된 시간 | |320| `duration_ms` | 도구 본체를 실행하는 데 소요된 시간 | |
321| `tool_use_id` | 부모 `claude_code.tool` 범위와 동일한 값 | |321| `tool_use_id` | 부모 `claude_code.tool` 스팬과 같은 값 | |
322| `gen_ai.tool.call.id` | `tool_use_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙 | |322| `gen_ai.tool.call.id` | `tool_use_id`와 같은 값. OpenTelemetry GenAI 시맨틱 규칙 | |
323| `success` | `true` 또는 `false` | |323| `success` | `true` 또는 `false` | |
324| `error` | 실행이 실패했을 때 오류 범주 문자열, `Error:ENOENT` 또는 `ShellError`와 같음. 게이트가 설정되면 대신 전체 오류 메시지를 포함합니다 | `OTEL_LOG_TOOL_DETAILS` |324| `error` | 실행이 실패한 경우의 오류 범주 문자열(예: `Error:ENOENT` 또는 `ShellError`). 게이트가 설정되면 대신 전체 오류 메시지를 포함합니다 | `OTEL_LOG_TOOL_DETAILS` |
325| `error_class` | 문자, 숫자 및 밑줄 외의 문자가 `_`로 대체된 식별자 형식의 오류 범주, `Error_ENOENT` 또는 `ShellError`와 같음. `error`가 전체 메시지를 전달할 때에도 범주를 전달합니다. Claude Code v2.1.268 이상 필요 | |325| `error_class` | 문자, 숫자, 밑줄 이외의 문자를 `_`로 대체한 식별자 형태의 오류 범주(예: `Error_ENOENT` 또는 `ShellError`). `error`가 전체 메시지를 포함하는 경우에도 범주를 담습니다. Claude Code v2.1.268 이상이 필요합니다 | |
326 326
327**`claude_code.hook`**327**`claude_code.hook`**
328 328
329이 범위는 상세 베타 추적이 활성화되었을 때만 나타나며, 이는 `ENABLE_BETA_TRACING_DETAILED=1` 및 `BETA_TRACING_ENDPOINT`가 필요합니다. 이 쌍은 또한 [로그 및 추적이 가는 위치를 변경합니다](https://code.claude.com/docs/ko/env-vars.md#variables). 쌍을 셸, 사용자 설정 또는 관리 설정에 설정하세요. 두 변수 모두 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서 무시됩니다. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 단독으로는 이를 생성하지 않습니다.329이 스팬은 상세 베타 트레이싱이 활성화된 경우에만 나타나며, 이를 위해서는 `ENABLE_BETA_TRACING_DETAILED=1`과 `BETA_TRACING_ENDPOINT`가 필요합니다. 이 두 변수는 [로그와 트레이스가 전송되는 위치도 변경합니다](https://code.claude.com/docs/ko/env-vars.md#variables). 이 두 변수는 셸, 사용자 설정 또는 관리형 설정에서 설정하세요. 두 변수 모두 [프로젝트 및 로컬 설정](https://code.claude.com/docs/ko/settings-reference.md#variables-claude-code-ignores-in-env)에서는 무시됩니다. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`만으로는 이 스팬이 생성되지 않습니다.
330 330
331대화형 CLI 세션에서 상세 베타 추적은 또한 조직이 기능에 대해 허용 목록에 있어야 합니다. Agent SDK 및 비대화형 `-p` 세션은 허용 목록이 필요하지 않습니다.331대화형 CLI 세션에서 상세 베타 트레이싱을 사용하려면 조직이 해당 기능의 허용 목록에 등록되어 있어야 합니다. Agent SDK 및 비대화형 `-p` 세션에는 허용 목록 등록이 필요하지 않습니다.
332 332
333| 속성 | 설명 | 게이트 |333| 속성 | 설명 | 게이트 |
334| - | - | - |334| - | - | - |
335| `hook_event` | 훅 이벤트 유형, `PreToolUse`와 같음 | |335| `hook_event` | 훅 이벤트 유형(예: `PreToolUse`) | |
336| `hook_name` | 전체 훅 이름, `PreToolUse:Write`와 같음 | |336| `hook_name` | 전체 훅 이름(예: `PreToolUse:Write`) | |
337| `num_hooks` | 실행된 일치하는 훅 명령 수 | |337| `num_hooks` | 실행된 일치하는 훅 명령의 수 | |
338| `hook_definitions` | JSON 직렬화된 훅 구성 | `OTEL_LOG_TOOL_DETAILS` |338| `hook_definitions` | JSON으로 직렬화된 훅 구성 | `OTEL_LOG_TOOL_DETAILS` |
339| `duration_ms` | 모든 일치하는 훅의 벽시계 지속 시간 | |339| `duration_ms` | 일치하는 모든 훅의 실제 경과 시간 | |
340| `num_success` | 성공적으로 완료된 훅 수 | |340| `num_success` | 성공적으로 완료된 훅 수 | |
341| `num_blocking` | 차단 결정을 반환한 훅 수 | |341| `num_blocking` | 차단 결정을 반환한 훅 수 | |
342| `num_non_blocking_error` | 차단 없이 실패한 훅 수 | |342| `num_non_blocking_error` | 차단하지 않고 실패한 훅 수 | |
343| `num_cancelled` | 완료 전에 취소된 훅 수 | |343| `num_cancelled` | 완료 전에 취소된 훅 수 | |
344 344
345**상세 베타 추적의 콘텐츠 속성**345**상세 베타 트레이싱의 콘텐츠 속성**
346 346
347> [!NOTE]347> [!NOTE]
348>348>
349> `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input` 및 `response.model_output`과 같은 추가 콘텐츠 포함 속성은 상세 베타 추적이 활성화되었을 때만 내보내집니다. 이들은 안정적인 범위 스키마의 일부가 아닙니다.349> `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input`, `response.model_output`과 같은 추가 콘텐츠 속성은 상세 베타 트레이싱이 활성화된 경우에만 출력됩니다. 이들은 안정적인 스팬 스키마의 일부가 아닙니다.
350 350
351이러한 속성은 아래 범위에 나타나며, `Gated by`는 상세 베타 추적 외에 속성에 필요한 변수의 이름을 지정합니다. 콘텐츠 제한(기본값 60KB)보다 긴 값은 잘립니다.351이 속성들은 아래 스팬에 나타나며, `게이트`는 상세 베타 트레이싱에 더해 속성에 필요한 변수를 나타냅니다. 콘텐츠 한도(기본값 60 KB)보다 긴 값은 잘립니다.
352 352
353| 속성 | 범위 | 설명 | 게이트 |353| 속성 | 스팬 | 설명 | 게이트 |
354| - | - | - | - |354| - | - | - | - |
355| `new_context` | `claude_code.interaction` | 사용자 프롬프트 | `OTEL_LOG_USER_PROMPTS` |355| `new_context` | `claude_code.interaction` | 사용자 프롬프트 | `OTEL_LOG_USER_PROMPTS` |
356| `new_context` | `claude_code.llm_request` | 요청과 함께 전송된 새 사용자 메시지 및 도구 결과 | `OTEL_LOG_USER_PROMPTS` |356| `new_context` | `claude_code.llm_request` | 요청과 함께 전송된 새 사용자 메시지 및 도구 결과 | `OTEL_LOG_USER_PROMPTS` |
357| `system_reminders` | `claude_code.llm_request` | 요청의 새 메시지 중 [시스템 리마인더](https://code.claude.com/docs/ko/glossary.md#system-reminder)의 텍스트 | `OTEL_LOG_USER_PROMPTS` |357| `system_reminders` | `claude_code.llm_request` | 요청의 새 메시지 중 [시스템 리마인더](https://code.claude.com/docs/ko/glossary.md#system-reminder)의 텍스트 | `OTEL_LOG_USER_PROMPTS` |
358| `system_prompt_preview` | `claude_code.llm_request` | 요청과 함께 전송된 전체 시스템 프롬프트의 처음 500자 | `OTEL_LOG_USER_PROMPTS` |358| `system_prompt_preview` | `claude_code.llm_request` | 요청과 함께 전송된 전체 시스템 프롬프트의 처음 500자 | `OTEL_LOG_USER_PROMPTS` |
359| `user_system_prompt` | `claude_code.llm_request` | `systemPrompt` SDK 옵션 또는 `--system-prompt` 및 `--append-system-prompt` 플래그를 통해 제공하는 시스템 프롬프트 텍스트만 해당. 요청당이 아닌 세션당 한 번 내보내짐 | `OTEL_LOG_USER_PROMPTS` |359| `user_system_prompt` | `claude_code.llm_request` | `systemPrompt` SDK 옵션 또는 `--system-prompt` 및 `--append-system-prompt` 플래그를 통해 제공한 시스템 프롬프트 텍스트만 포함합니다. 요청마다가 아니라 세션당 한 번 출력됩니다 | `OTEL_LOG_USER_PROMPTS` |
360| `response.model_output` | `claude_code.llm_request` | 요청에 대한 모델 응답의 텍스트 | `OTEL_LOG_USER_PROMPTS` |360| `response.model_output` | `claude_code.llm_request` | 요청에 대한 모델 응답의 텍스트 | `OTEL_LOG_USER_PROMPTS` |
361| `new_context` | `claude_code.tool` | 도구에 관계없이 해당 도구 호출의 결과 | `OTEL_LOG_TOOL_CONTENT` |361| `new_context` | `claude_code.tool` | 도구와 관계없이 도구 호출의 결과 | `OTEL_LOG_TOOL_CONTENT` |
362| `tool_input` | `claude_code.tool` | 도구 호출의 직렬화된 입력 | `OTEL_LOG_TOOL_DETAILS` |362| `tool_input` | `claude_code.tool` | 도구 호출의 직렬화된 입력 | `OTEL_LOG_TOOL_DETAILS` |
363 363
364`OTEL_LOG_USER_PROMPTS=1`을 설정한 상세 베타 추적에서 Claude Code는 콘텐츠 제한에서 잘린 전체 시스템 프롬프트를 전달하는 `claude_code.system_prompt` 이벤트도 내보냅니다. 이 이벤트는 세션이 각각의 고유한 시스템 프롬프트를 처음 보낼 때 도착하며, 압축 후에 다시 도착합니다.364`OTEL_LOG_USER_PROMPTS=1`이 설정된 상세 베타 트레이싱에서 Claude Code는 콘텐츠 한도에서 잘린 전체 시스템 프롬프트를 담은 `claude_code.system_prompt` 이벤트도 출력합니다. 이 이벤트는 세션이 각각의 고유한 시스템 프롬프트를 처음 전송할 때, 그리고 압축 후에 다시 도착합니다.
365 365
366### 동적 헤더366### 동적 헤더
367 367
368동적 인증이 필요한 엔터프라이즈 환경의 경우 헤더를 동적으로 생성하도록 스크립트를 구성할 수 있습니다. 동적 헤더는 `http/protobuf` 및 `http/json` 프로토콜에만 적용됩니다. `grpc` 프로토콜을 사용하면 Claude Code는 정적 헤더 변수인 `OTEL_EXPORTER_OTLP_HEADERS` 및 신호별 변형만 사용합니다.368동적 인증이 필요한 엔터프라이즈 환경에서는 스크립트를 구성하여 헤더를 동적으로 생성할 수 있습니다. 동적 헤더는 `http/protobuf` 및 `http/json` 프로토콜에만 적용됩니다. `grpc` 프로토콜에서 Claude Code는 정적 헤더 변수인 `OTEL_EXPORTER_OTLP_HEADERS`와 그 신호별 변형만 사용합니다.
369 369
370#### 설정 구성370#### 설정 구성
371 371
372`.claude/settings.json`에 추가하고 경로를 자신의 스크립트로 바꾸세요:372경로를 자신의 스크립트로 바꾸어 `.claude/settings.json`에 추가합니다.
373 373
374```json theme={null}374```json theme={null}
375{375{
377}377}
378```378```
379 379
380값은 공백을 포함한 경로를 포함한 실행 가능한 파일의 경로이거나 인수가 있는 셸 명령줄일 수 있습니다. Windows에서 값은 항상 셸을 통해 실행되므로 공백을 포함하는 경로를 JSON 값 내에 인용하세요.380값은 공백이 포함된 경로를 포함한 실행 파일의 경로이거나, 인수가 있는 셸 명령줄일 수 있습니다. Windows에서는 값이 항상 셸을 통해 실행되므로, 공백이 포함된 경로는 JSON 값 안에서 따옴표로 감싸세요.
381 381
382#### 스크립트 요구 사항382#### 스크립트 요구 사항
383 383
384스크립트는 HTTP 헤더를 나타내는 문자열 키-값 쌍이 있는 유효한 JSON을 출력해야 합니다:384스크립트는 HTTP 헤더를 나타내는 문자열 키-값 쌍으로 구성된 유효한 JSON을 출력해야 합니다.
385 385
386```bash theme={null}386```bash theme={null}
387#!/bin/bash387#!/bin/bash
389echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"389echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"
390```390```
391 391
392헬퍼가 실패하거나 이러한 요구 사항을 충족하지 않는 출력을 인쇄하면 내보내기가 실패하고 헬퍼가 다시 작동할 때까지 원격 분석 백엔드는 세션에서 아무것도 받지 않습니다. Claude Code는 다음에서 실패를 보고합니다:392헬퍼가 실패하거나 이 요구 사항을 충족하지 않는 출력을 내보내면, 내보내기가 실패하고 헬퍼가 다시 작동할 때까지 텔레메트리 백엔드는 해당 세션에서 아무것도 받지 못합니다. Claude Code는 다음 위치에서 실패를 보고합니다.
393 393
394* 대화형 세션의 경고 알림, [`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/ko/errors#otelheadershelper-failed), 헬퍼가 처음 실패할 때 세션당 한 번 표시394* 대화형 세션의 경고 알림 [`otelHeadersHelper failed; telemetry is not being exported`](https://code.claude.com/docs/ko/errors#otelheadershelper-failed)로, 헬퍼가 처음 실패할 때 세션당 한 번 표시됩니다
395* `/status` 출력395* `/status` 출력
396* [`--debug`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 실행하거나 세션에서 `/debug`를 실행한 후 디버그 로그396* [`--debug`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 실행하거나 세션에서 `/debug`를 실행한 후의 디버그 로그
397* `-p`로 시작된 비대화형 세션의 stderr397* `-p`로 시작된 비대화형 세션의 stderr
398 398
399#### 새로 고침 동작399#### 새로 고침 동작
400 400
401헤더 헬퍼 스크립트는 시작 시 및 토큰 새로 고침을 지원하기 위해 주기적으로 실행됩니다. 기본적으로 스크립트는 29분마다 실행됩니다. `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 환경 변수로 간격을 사용자 정의하세요.401헤더 헬퍼 스크립트는 토큰 새로 고침을 지원하기 위해 시작 시 실행되고 이후 주기적으로 실행됩니다. 기본적으로 스크립트는 29분마다 실행됩니다. `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 환경 변수로 간격을 사용자 지정할 수 있습니다.
402 402
403### 다중 팀 조직 지원403### 다중 팀 조직 지원
404 404
405여러 팀 또는 부서가 있는 조직은 `OTEL_RESOURCE_ATTRIBUTES` 환경 변수를 사용하여 다양한 그룹을 구분하기 위한 사용자 정의 속성을 추가할 수 있습니다:405여러 팀이나 부서가 있는 조직은 `OTEL_RESOURCE_ATTRIBUTES` 환경 변수를 사용하여 서로 다른 그룹을 구분하는 사용자 지정 속성을 추가할 수 있습니다.
406 406
407```bash theme={null}407```bash theme={null}
408# Add custom attributes for team identification408# Add custom attributes for team identification
409export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"409export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
410```410```
411 411
412이러한 사용자 정의 속성은 모든 메트릭 및 이벤트에 포함되므로 다음을 수행할 수 있습니다:412이러한 사용자 지정 속성은 모든 메트릭과 이벤트에 포함되므로 다음과 같은 작업을 할 수 있습니다.
413 413
414* 팀 또는 부서별로 메트릭 필터링414* 팀 또는 부서별로 메트릭 필터링
415* 비용 센터당 비용 추적415* 비용 센터별 비용 추적
416* 팀별 대시보드 생성416* 팀별 대시보드 생성
417* 특정 팀에 대한 경고 설정417* 특정 팀에 대한 알림 설정
418 418
419Claude Code는 OTLP 리소스 블록에서 보내는 것 외에도 모든 메트릭 데이터포인트 및 이벤트 레코드에 이러한 값을 속성으로 첨부합니다. 대부분의 메트릭 백엔드는 데이터포인트 속성을 쿼리 가능한 레이블로 노출하므로 사용자 정의 키로 메트릭을 직접 그룹화하고 필터링할 수 있습니다. `vcs.*` [저장소 속성](#repository-attributes)을 제외하고 사용자 정의 키는 `user.id` 또는 `session.id`와 같은 [표준 속성](#standard-attributes)을 재정의하지 않습니다: 키가 충돌하면 Claude Code는 기본 제공 값을 유지합니다.419Claude Code는 이 값들을 OTLP 리소스 블록으로 전송할 뿐 아니라 모든 메트릭 데이터 포인트와 이벤트 레코드에 속성으로 첨부합니다. 대부분의 메트릭 백엔드는 데이터 포인트 속성을 쿼리 가능한 레이블로 노출하므로, 사용자 지정 키로 메트릭을 직접 그룹화하고 필터링할 수 있습니다. `vcs.*` [저장소 속성](#repository-attributes)을 제외하고, 사용자 지정 키는 `user.id`나 `session.id`와 같은 [표준 속성](#standard-attributes)을 재정의하지 않습니다. 키가 충돌하면 Claude Code는 내장 값을 유지합니다.
420 420
421각 사용자 정의 키는 모든 메트릭 시리즈의 레이블이 되므로 높은 카디널리티 값은 메트릭 백엔드의 저장소 비용을 증가시킵니다. 리소스 블록에만 사용자 정의 속성을 보내고 데이터포인트 레이블에서 생략하려면 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`를 설정하세요. [메트릭 카디널리티 제어](#metrics-cardinality-control)를 참조하세요.421각 사용자 지정 키는 모든 메트릭 시리즈의 레이블이 되므로, 카디널리티가 높은 값은 메트릭 백엔드의 스토리지 비용을 증가시킵니다. 사용자 지정 속성을 리소스 블록으로만 전송하고 데이터 포인트 레이블에서는 생략하려면 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`를 설정하세요. [메트릭 카디널리티 제어](#metrics-cardinality-control)를 참조하세요.
422 422
423> [!WARNING]423> [!WARNING]
424>424>
425> `OTEL_RESOURCE_ATTRIBUTES` 환경 변수는 엄격한 형식 요구 사항이 있는 쉼표로 구분된 키=값 쌍을 사용합니다:425> `OTEL_RESOURCE_ATTRIBUTES` 환경 변수는 엄격한 형식 요구 사항이 있는 쉼표로 구분된 key=value 쌍을 사용합니다.
426>426>
427> * **공백 허용 안 함**: 값에 공백이 포함될 수 없습니다. 예를 들어 `user.organizationName=My Company`는 유효하지 않습니다427> * **공백 허용 안 됨**: 값에 공백을 포함할 수 없습니다. 예를 들어 `user.organizationName=My Company`는 유효하지 않습니다
428> * **형식**: 쉼표로 구분된 키=값 쌍이어야 합니다: `key1=value1,key2=value2`428> * **형식**: 쉼표로 구분된 key=value 쌍이어야 합니다: `key1=value1,key2=value2`
429> * **허용된 문자**: 제어 문자, 공백, 큰따옴표, 쉼표, 세미콜론 및 백슬래시를 제외한 US-ASCII 문자만429> * **허용 문자**: 제어 문자, 공백, 큰따옴표, 쉼표, 세미콜론, 백슬래시를 제외한 US-ASCII 문자만 허용됩니다
430> * **특수 문자**: 허용된 범위 외의 문자는 퍼센트 인코딩되어야 합니다430> * **특수 문자**: 허용 범위를 벗어난 문자는 퍼센트 인코딩해야 합니다
431>431>
432> 공백이 필요한 값의 경우 대신 밑줄이나 camelCase를 사용하세요. 다음 예제는 각 형식으로 `org.name`을 설정합니다:432> 공백이 필요한 값에는 대신 밑줄이나 camelCase를 사용하세요. 다음 예시는 각 형식으로 `org.name`을 설정합니다.
433>433>
434> ```bash theme={null}434> ```bash theme={null}
435> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"435> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
436> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"436> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"
437> ```437> ```
438>438>
439> 허용된 문자만이 아닌 모든 문자를 퍼센트 인코딩할 수 있습니다. 이 예제는 공백과 아포스트로피를 모두 인코딩합니다:439> 제외된 문자뿐 아니라 어떤 문자든 퍼센트 인코딩할 수 있습니다. 이 예시는 공백과 아포스트로피를 모두 인코딩합니다.
440>440>
441> ```bash theme={null}441> ```bash theme={null}
442> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"442> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
443> ```443> ```
444>444>
445> 값을 따옴표로 감싸면 공백이 이스케이프되지 않습니다. 예를 들어 `org.name="My Company"`는 `My Company`가 아닌 따옴표를 포함한 리터럴 값 `"My Company"`를 생성합니다.445> 값을 따옴표로 감싸도 공백이 이스케이프되지 않습니다. 예를 들어 `org.name="My Company"`는 `My Company`가 아니라 따옴표가 포함된 리터럴 값 `"My Company"`가 됩니다.
446 446
447### Desktop SSH 세션에 텔레메트리 귀속447### Desktop SSH 세션에 텔레메트리 귀속
448 448
449[Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#ssh-sessions)이 어느 원격 머신에서 실행되었는지 확인하려면 사용자 정의 속성에 각 머신의 이름을 지정하세요. 메트릭과 이벤트에는 세션이 실행된 머신의 이름이 포함되지 않습니다.449[Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#ssh-sessions)이 어느 원격 머신에서 실행되었는지 확인하려면 사용자 지정 속성으로 각 머신의 이름을 지정하세요. 메트릭과 이벤트에는 세션이 실행된 머신의 이름이 포함되지 않습니다.
450 450
451각 원격 머신에서 [세션이 읽는 관리형 설정 파일](https://code.claude.com/docs/ko/desktop.md#managed-settings)의, 텔레메트리를 켜는 `env` 블록에 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)를 추가하세요. 각 머신의 파일에 이름을 직접 작성합니다. Claude Code는 값을 확장하지 않으므로 `host.name=$(hostname)`은 해당 문자 그대로 전달됩니다.451각 원격 머신에서 [세션이 읽는 관리형 설정 파일](https://code.claude.com/docs/ko/desktop.md#managed-settings)의 텔레메트리를 켜는 `env` 블록에 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)를 추가합니다. 각 머신의 파일에 이름을 직접 적으세요. Claude Code는 값을 확장하지 않으므로 `host.name=$(hostname)`은 그 문자 그대로 도착합니다.
452 452
453다음 예제는 머신 이름을 `build-7`로 지정합니다:453다음 예시는 머신 이름을 `build-7`로 지정합니다.
454 454
455```json theme={null}455```json theme={null}
456{456{
465}465}
466```466```
467 467
468다른 곳에서 이 변수를 설정하지 않으면 `host.name`은 Desktop SSH 세션과 해당 머신의 CLI에서 리소스 블록에 도착합니다. 사용자 정의 속성이 나타나는 다른 위치는 [다중 팀 조직 지원](#multi-team-organization-support)을 참조하세요.468다른 어떤 것도 이 변수를 설정하지 않으면, `host.name`은 Desktop SSH 세션과 해당 머신의 CLI 모두에서 리소스 블록에 포함되어 도착합니다. 사용자 지정 속성이 나타나는 다른 위치는 [다중 팀 조직 지원](#multi-team-organization-support)을 참조하세요.
469 469
470이름이 도착하지 않으면 다음 원인 중 하나에 해당하는지 확인하세요:470이름이 도착하지 않으면 다음 원인 중 하나인지 확인하세요.
471 471
472* **Desktop을 실행하는 컴퓨터에 설정한 경우**: Desktop은 해당 컴퓨터에서 설정한 값을 SSH 세션에 전달하지 않습니다472* **Desktop을 실행하는 컴퓨터에서 설정한 경우**: Desktop은 그곳에서 설정한 값을 SSH 세션에 전달하지 않습니다
473* **로그인 파일에서 export한 경우**: `/etc/profile`과 같은 파일은 로그인 셸만 읽습니다. 해당 파일에서 `export`한 값은 로그인 셸에서 시작한 Claude Code에는 전달됩니다. Desktop은 로그인 셸을 통해 Claude Code를 시작하지 않으므로 Desktop SSH 세션에는 전달되지 않습니다.473* **`/etc/profile` 또는 로그인 셸만 읽는 다른 파일에서 export한 경우**: 로그인 셸에서 `claude`를 실행하면 이름이 도착하지만 Desktop SSH 세션에서는 도착하지 않습니다. Desktop은 로그인 셸을 통해 Claude Code를 시작하지 않습니다. 대신 원격 머신의 [관리형 설정 파일](https://code.claude.com/docs/ko/desktop.md#managed-settings)에서 `env` 아래에 변수를 설정하세요.
474* **값 안에 공백이 있는 경우**: 이 경우 Claude Code는 어떤 키도 이벤트나 데이터포인트에 복사하지 않으며 오류도 보고하지 않습니다. [값에서 공백을 제거하세요](#multi-team-organization-support).474* **값 안에 공백이 있는 경우**: 이때 Claude Code는 어떤 키도 이벤트나 데이터 포인트에 복사하지 않으며 오류도 보고하지 않습니다. [값에서 공백을 제거하세요](#multi-team-organization-support).
475* **다른 곳에서 이미 변수를 설정한 경우**: 데스크톱 앱이 시작하는 세션에서는 실행 환경에 이미 설정된 변수가 [설정 파일보다 우선합니다](https://code.claude.com/docs/ko/settings-reference.md#how-env-values-interact-with-your-shell). [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)에는 무시된 각 변수의 이름이 표시됩니다. 타사 Desktop 배포가 제공하는 환경에서 [OTLP 엔드포인트를 지정하는](#how-managed-settings-lock-the-otlp-destination) 경우, 해당 환경에는 Desktop 자체의 `OTEL_RESOURCE_ATTRIBUTES`가 포함됩니다.475* **다른 무언가가 이미 변수를 설정한 경우**: 데스크톱 앱이 시작하는 세션에서는 실행 환경에 이미 설정된 변수가 [설정 파일보다 우선합니다](https://code.claude.com/docs/ko/settings-reference.md#how-env-values-interact-with-your-shell). [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)에 무시된 각 변수의 이름이 표시됩니다. 서드파티 Desktop 배포가 제공하는 환경에서 [OTLP 엔드포인트를 지정](#how-managed-settings-lock-the-otlp-destination)하는 경우, 해당 환경에는 Desktop 자체의 `OTEL_RESOURCE_ATTRIBUTES`가 포함됩니다.
476 476
477### 예제 구성477### 구성 예시
478 478
479`claude`를 실행하기 전에 이러한 환경 변수를 설정하세요. 아래의 각 시나리오는 완전한 구성을 보여주며, 각 변수는 [일반적인 구성 변수](#common-configuration-variables) 아래에 설명되어 있습니다. 구성이 적용되었는지 확인하려면 세션을 시작한 후 백엔드에서 `claude_code.session.count` 메트릭을 확인하세요. [빠른 시작](#quick-start)은 로그 전용 검증 및 아무것도 도착하지 않을 때 확인할 사항을 다룹니다.479`claude`를 실행하기 전에 이 환경 변수들을 설정하세요. 아래의 각 시나리오는 완전한 구성을 보여 주며, 각 변수는 [공통 구성 변수](#common-configuration-variables)에 설명되어 있습니다. 구성이 적용되었는지 확인하려면 세션을 시작한 후 백엔드에서 `claude_code.session.count` 메트릭을 확인하세요. 로그 전용 확인 방법과 아무것도 도착하지 않을 때 확인할 사항은 [빠른 시작](#quick-start)에서 다룹니다.
480 480
481콘솔 디버깅을 위해 1초 내보내기 간격:4811초 내보내기 간격으로 콘솔 디버깅을 하는 경우:
482 482
483```bash theme={null}483```bash theme={null}
484export CLAUDE_CODE_ENABLE_TELEMETRY=1484export CLAUDE_CODE_ENABLE_TELEMETRY=1
486export OTEL_METRIC_EXPORT_INTERVAL=1000486export OTEL_METRIC_EXPORT_INTERVAL=1000
487```487```
488 488
489OTLP over gRPC:489gRPC를 통한 OTLP의 경우:
490 490
491```bash theme={null}491```bash theme={null}
492export CLAUDE_CODE_ENABLE_TELEMETRY=1492export CLAUDE_CODE_ENABLE_TELEMETRY=1
495export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317495export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
496```496```
497 497
498Prometheus, `http://localhost:9464/metrics`에서 스크래핑:498`http://localhost:9464/metrics`에서 스크레이핑하는 Prometheus의 경우:
499 499
500```bash theme={null}500```bash theme={null}
501export CLAUDE_CODE_ENABLE_TELEMETRY=1501export CLAUDE_CODE_ENABLE_TELEMETRY=1
502export OTEL_METRICS_EXPORTER=prometheus502export OTEL_METRICS_EXPORTER=prometheus
503```503```
504 504
505[자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments-reference.md#pass-through-session-child-metrics)에서 세션은 러너의 기본 용량 1에서만 포트 9464를 바인딩합니다. 더 높은 용량에서 러너는 대신 자신의 `/metrics` 엔드포인트에서 세션 카운터 및 게이지를 다시 노출합니다.505[자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments-reference.md#pass-through-session-child-metrics)에서는 러너의 기본 용량이 1일 때만 세션이 포트 9464에 바인딩됩니다. 용량이 더 크면 러너가 대신 자체 `/metrics` 엔드포인트에서 세션 카운터와 게이지를 다시 노출합니다.
506 506
507여러 내보내기로 메트릭을 보내려면:507여러 익스포터로 메트릭을 보내려면:
508 508
509```bash theme={null}509```bash theme={null}
510export CLAUDE_CODE_ENABLE_TELEMETRY=1510export CLAUDE_CODE_ENABLE_TELEMETRY=1
512export OTEL_EXPORTER_OTLP_PROTOCOL=http/json512export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
513```513```
514 514
515메트릭 및 로그를 다양한 엔드포인트 또는 백엔드로 보내려면:515메트릭과 로그를 서로 다른 엔드포인트 또는 백엔드로 보내려면:
516 516
517```bash theme={null}517```bash theme={null}
518export CLAUDE_CODE_ENABLE_TELEMETRY=1518export CLAUDE_CODE_ENABLE_TELEMETRY=1
524export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317524export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317
525```525```
526 526
527이벤트 또는 로그 없이 메트릭만 내보내려면:527이벤트나 로그 없이 메트릭만 내보내려면:
528 528
529```bash theme={null}529```bash theme={null}
530export CLAUDE_CODE_ENABLE_TELEMETRY=1530export CLAUDE_CODE_ENABLE_TELEMETRY=1
533export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317533export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
534```534```
535 535
536메트릭 없이 이벤트 및 로그만 내보내려면:536메트릭 없이 이벤트와 로그만 내보내려면:
537 537
538```bash theme={null}538```bash theme={null}
539export CLAUDE_CODE_ENABLE_TELEMETRY=1539export CLAUDE_CODE_ENABLE_TELEMETRY=1
1403* `pre_tokens`: 압축 전 대략적인 토큰 수1403* `pre_tokens`: 압축 전 대략적인 토큰 수
1404* `post_tokens`: 압축 후 대략적인 토큰 수1404* `post_tokens`: 압축 후 대략적인 토큰 수
1405* `error`: 압축이 실패한 경우의 오류 메시지1405* `error`: 압축이 실패한 경우의 오류 메시지
1406* `precompute_reuse`: `trigger`가 `"manual"`인 경우 또는 `trigger`를 `"auto"`로 보고하는 [유휴 압축](https://code.claude.com/docs/ko/settings-reference.md#idlecompaction)의 경우에만 설정됩니다. 자동 압축은 컨텍스트 윈도우가 가득 차기 전에 백그라운드에서 요약을 미리 준비할 수 있으며, 이 속성은 압축이 준비된 요약을 재사용했는지 여부를 기록합니다. `"hit"`는 재사용되었음을 의미하고, `"miss_custom_instructions"`, `"miss_hook"`, `"miss_not_ready"`는 대신 새 요약을 계산한 이유를 나타냅니다1406* `precompute_reuse`: `trigger`가 `"manual"`인 경우, 또는 대화형 터미널 세션의 [유휴 압축](https://code.claude.com/docs/ko/settings-reference.md#idlecompaction)에서 `trigger`가 `"auto"`인 경우에만 설정됩니다. 자동 압축은 컨텍스트 윈도우가 가득 차기 전에 백그라운드에서 요약을 준비할 수 있으며, 이 속성은 압축이 준비된 요약을 재사용했는지 여부를 기록합니다. `"hit"`는 재사용되었음을 의미하며, `"miss_custom_instructions"`, `"miss_hook"`, `"miss_not_ready"`는 대신 새 요약을 계산한 이유를 나타냅니다
1407 1407
1408#### 서브에이전트 완료 이벤트1408#### 서브에이전트 완료 이벤트
1409 1409
