> ## 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.

# 모니터링

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

OpenTelemetry(OTel)를 통해 원격 측정 데이터를 내보내 조직 전체에서 Claude Code 사용, 비용 및 도구 활동을 추적합니다. Claude Code는 표준 메트릭 프로토콜을 통해 메트릭을 시계열 데이터로 내보내고, 로그/이벤트 프로토콜을 통해 이벤트를 내보내며, 선택적으로 [추적 프로토콜](#traces-beta)을 통해 분산 추적을 내보냅니다. 메트릭, 로그 및 추적 백엔드를 구성하여 모니터링 요구 사항과 일치하도록 합니다.

## 빠른 시작

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

```bash theme={null}
# 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
```

<Note>
  기본 내보내기 간격은 메트릭의 경우 60초, 로그의 경우 5초입니다. 설정 중에 디버깅 목적으로 더 짧은 간격을 사용할 수 있습니다. 프로덕션 사용을 위해 이를 재설정하는 것을 잊지 마세요.
</Note>

전체 구성 옵션은 [OpenTelemetry 사양](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)을 참조하세요.

## 관리자 구성

관리자는 [관리 설정 파일](/ko/settings#settings-files)을 통해 모든 사용자에 대한 OpenTelemetry 설정을 구성할 수 있습니다. 이를 통해 조직 전체에서 원격 측정 설정을 중앙에서 제어할 수 있습니다. 설정이 적용되는 방식에 대한 자세한 내용은 [설정 우선순위](/ko/settings#settings-precedence)를 참조하세요.

관리 설정 구성 예:

```json theme={null}
{
  "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"
  }
}
```

<Note>
  관리 설정은 MDM(Mobile Device Management) 또는 기타 장치 관리 솔루션을 통해 배포할 수 있습니다. 관리 설정 파일에 정의된 환경 변수는 높은 우선순위를 가지며 사용자가 재정의할 수 없습니다.
</Note>

## 구성 세부 정보

### 일반적인 구성 변수

| 환경 변수                                               | 설명                                                                                                                                                                                                                                             | 예제 값                                                                        |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `CLAUDE_CODE_ENABLE_TELEMETRY`                      | 원격 측정 수집 활성화 (필수)                                                                                                                                                                                                                              | `1`                                                                         |
| `OTEL_METRICS_EXPORTER`                             | 메트릭 내보내기 유형 (쉼표로 구분). `none`을 사용하여 비활성화                                                                                                                                                                                                        | `console`, `otlp`, `prometheus`, `none`                                     |
| `OTEL_LOGS_EXPORTER`                                | 로그/이벤트 내보내기 유형 (쉼표로 구분). `none`을 사용하여 비활성화                                                                                                                                                                                                     | `console`, `otlp`, `none`                                                   |
| `OTEL_EXPORTER_OTLP_PROTOCOL`                       | OTLP 내보내기 프로토콜 (모든 신호에 적용)                                                                                                                                                                                                                     | `grpc`, `http/json`, `http/protobuf`                                        |
| `OTEL_EXPORTER_OTLP_ENDPOINT`                       | 모든 신호에 대한 OTLP 수집기 엔드포인트                                                                                                                                                                                                                       | `http://localhost:4317`                                                     |
| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`               | 메트릭 프로토콜 (일반 설정 재정의)                                                                                                                                                                                                                           | `grpc`, `http/json`, `http/protobuf`                                        |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`               | OTLP 메트릭 엔드포인트 (일반 설정 재정의)                                                                                                                                                                                                                     | `http://localhost:4318/v1/metrics`                                          |
| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`                  | 로그 프로토콜 (일반 설정 재정의)                                                                                                                                                                                                                            | `grpc`, `http/json`, `http/protobuf`                                        |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`                  | OTLP 로그 엔드포인트 (일반 설정 재정의)                                                                                                                                                                                                                      | `http://localhost:4318/v1/logs`                                             |
| `OTEL_EXPORTER_OTLP_HEADERS`                        | OTLP용 인증 헤더                                                                                                                                                                                                                                    | `Authorization=Bearer token`                                                |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY`             | mTLS 인증용 클라이언트 키                                                                                                                                                                                                                               | 클라이언트 키 파일 경로                                                               |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE`     | mTLS 인증용 클라이언트 인증서                                                                                                                                                                                                                             | 클라이언트 인증서 파일 경로                                                             |
| `OTEL_METRIC_EXPORT_INTERVAL`                       | 내보내기 간격 (밀리초 단위, 기본값: 60000)                                                                                                                                                                                                                   | `5000`, `60000`                                                             |
| `OTEL_LOGS_EXPORT_INTERVAL`                         | 로그 내보내기 간격 (밀리초 단위, 기본값: 5000)                                                                                                                                                                                                                 | `1000`, `10000`                                                             |
| `OTEL_LOG_USER_PROMPTS`                             | 사용자 프롬프트 콘텐츠 로깅 활성화 (기본값: 비활성화)                                                                                                                                                                                                                | `1`로 활성화                                                                    |
| `OTEL_LOG_TOOL_DETAILS`                             | 도구 이벤트 및 추적 스팬 속성에서 도구 매개변수 및 입력 인수 로깅 활성화: Bash 명령, MCP 서버 및 도구 이름, 스킬 이름 및 도구 입력. 또한 `user_prompt` 이벤트에서 사용자 정의, 플러그인 및 MCP 명령 이름을 활성화합니다 (기본값: 비활성화)                                                                                        | `1`로 활성화                                                                    |
| `OTEL_LOG_TOOL_CONTENT`                             | 스팬 이벤트에서 도구 입력 및 출력 콘텐츠 로깅 활성화 (기본값: 비활성화). [추적](#traces-beta)이 필요합니다. 콘텐츠는 60KB에서 잘립니다                                                                                                                                                        | `1`로 활성화                                                                    |
| `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`가 공개할 모든 것에 동의하는 것을 의미합니다 | `1`로 60KB에서 잘린 인라인 본문, 또는 `file:<dir>`로 디스크의 잘리지 않은 본문과 이벤트의 `body_ref` 포인터 |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | 메트릭 시간성 선호도 (기본값: `delta`). 백엔드가 누적 시간성을 예상하는 경우 `cumulative`로 설정                                                                                                                                                                              | `delta`, `cumulative`                                                       |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`       | 동적 헤더 새로 고침 간격 (기본값: 1740000ms / 29분)                                                                                                                                                                                                          | `900000`                                                                    |

### 메트릭 카디널리티 제어

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

| 환경 변수                               | 설명                                               | 기본값     | 비활성화 예  |
| ----------------------------------- | ------------------------------------------------ | ------- | ------- |
| `OTEL_METRICS_INCLUDE_SESSION_ID`   | 메트릭에 session.id 속성 포함                            | `true`  | `false` |
| `OTEL_METRICS_INCLUDE_VERSION`      | 메트릭에 app.version 속성 포함                           | `false` | `true`  |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | 메트릭에 user.account\_uuid 및 user.account\_id 속성 포함 | `true`  | `false` |

이러한 변수는 메트릭의 카디널리티를 제어하는 데 도움이 되며, 이는 메트릭 백엔드의 저장소 요구 사항 및 쿼리 성능에 영향을 미칩니다. 낮은 카디널리티는 일반적으로 더 나은 성능과 낮은 저장소 비용을 의미하지만 분석을 위한 세분화된 데이터는 적습니다.

### 추적 (베타)

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

추적은 기본적으로 꺼져 있습니다. 활성화하려면 `CLAUDE_CODE_ENABLE_TELEMETRY=1` 및 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`을 모두 설정한 다음 `OTEL_TRACES_EXPORTER`를 설정하여 스팬을 보낼 위치를 선택합니다. 추적은 엔드포인트, 프로토콜 및 헤더에 대해 [일반적인 OTLP 구성](#common-configuration-variables)을 재사용합니다.

| 환경 변수                                 | 설명                                                    | 예제 값                                 |
| ------------------------------------- | ----------------------------------------------------- | ------------------------------------ |
| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | 스팬 추적 활성화 (필수). `ENABLE_ENHANCED_TELEMETRY_BETA`도 허용됨 | `1`                                  |
| `OTEL_TRACES_EXPORTER`                | 추적 내보내기 유형 (쉼표로 구분). `none`을 사용하여 비활성화                | `console`, `otlp`, `none`            |
| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`  | 추적 프로토콜 (`OTEL_EXPORTER_OTLP_PROTOCOL` 재정의)           | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`  | OTLP 추적 엔드포인트 (`OTEL_EXPORTER_OTLP_ENDPOINT` 재정의)     | `http://localhost:4318/v1/traces`    |
| `OTEL_TRACES_EXPORT_INTERVAL`         | 스팬 배치 내보내기 간격 (밀리초 단위, 기본값: 5000)                     | `1000`, `10000`                      |

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

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

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

#### 스팬 계층 구조

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

```text theme={null}
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 스팬
```

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

#### 스팬 속성

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

**`claude_code.interaction`**

| 속성                        | 설명                                         | 게이트 대상                  |
| ------------------------- | ------------------------------------------ | ----------------------- |
| `user_prompt`             | 프롬프트 텍스트. 게이트가 설정되지 않으면 값은 `<REDACTED>`입니다 | `OTEL_LOG_USER_PROMPTS` |
| `user_prompt_length`      | 프롬프트 길이 (문자 단위)                            |                         |
| `interaction.sequence`    | 이 세션의 상호 작용 1 기반 카운터                       |                         |
| `interaction.duration_ms` | 턴의 벽시계 지속 시간                               |                         |

**`claude_code.llm_request`**

| 속성                               | 설명                                                                                                         | 게이트 대상 |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------ |
| `model`                          | 모델 식별자                                                                                                     |        |
| `gen_ai.system`                  | 항상 `anthropic`. OpenTelemetry GenAI 의미론적 규칙                                                                |        |
| `gen_ai.request.model`           | `model`과 동일한 값. OpenTelemetry GenAI 의미론적 규칙                                                                |        |
| `query_source`                   | 요청을 발급한 하위 시스템 (예: `repl_main_thread` 또는 하위 에이전트 이름)                                                       |        |
| `speed`                          | `fast` 또는 `normal`                                                                                         |        |
| `llm_request.context`            | 부모 스팬에 따라 `interaction`, `tool` 또는 `standalone`                                                            |        |
| `duration_ms`                    | 재시도를 포함한 벽시계 지속 시간                                                                                         |        |
| `ttft_ms`                        | 첫 번째 토큰까지의 시간 (밀리초)                                                                                        |        |
| `input_tokens`                   | API 사용 블록의 입력 토큰 수                                                                                         |        |
| `output_tokens`                  | 출력 토큰 수                                                                                                    |        |
| `cache_read_tokens`              | 프롬프트 캐시에서 읽은 토큰                                                                                            |        |
| `cache_creation_tokens`          | 프롬프트 캐시에 기록된 토큰                                                                                            |        |
| `request_id`                     | `request-id` 응답 헤더의 Anthropic API 요청 ID                                                                    |        |
| `gen_ai.response.id`             | `request_id`와 동일한 값. OpenTelemetry GenAI 의미론적 규칙                                                           |        |
| `client_request_id`              | 최종 시도의 클라이언트 생성 `x-client-request-id`                                                                      |        |
| `attempt`                        | 이 요청에 대해 수행된 총 시도                                                                                          |        |
| `success`                        | `true` 또는 `false`                                                                                          |        |
| `status_code`                    | 요청이 실패했을 때 HTTP 상태 코드                                                                                      |        |
| `error`                          | 요청이 실패했을 때 오류 메시지                                                                                          |        |
| `response.has_tool_call`         | 응답에 도구 사용 블록이 포함되었을 때 `true`                                                                               |        |
| `stop_reason`                    | API 응답 `stop_reason` (예: `end_turn`, `tool_use`, `max_tokens`, `stop_sequence`, `pause_turn` 또는 `refusal`) |        |
| `gen_ai.response.finish_reasons` | `stop_reason`과 동일한 값 (문자열 배열로 래핑됨). OpenTelemetry GenAI 의미론적 규칙                                            |        |

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

**`claude_code.tool`**

| 속성              | 설명                              | 게이트 대상                  |
| --------------- | ------------------------------- | ----------------------- |
| `tool_name`     | 도구 이름                           |                         |
| `duration_ms`   | 권한 대기 및 실행을 포함한 벽시계 지속 시간       |                         |
| `result_tokens` | 도구 결과의 대략적인 토큰 크기               |                         |
| `file_path`     | Read, Edit 및 Write 도구의 대상 파일 경로 | `OTEL_LOG_TOOL_DETAILS` |
| `full_command`  | Bash 도구의 명령 문자열                 | `OTEL_LOG_TOOL_DETAILS` |
| `skill_name`    | Skill 도구의 스킬 이름                 | `OTEL_LOG_TOOL_DETAILS` |
| `subagent_type` | Task 도구의 하위 에이전트 유형             | `OTEL_LOG_TOOL_DETAILS` |

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

**`claude_code.tool.blocked_on_user`**

| 속성            | 설명                              | 게이트 대상 |
| ------------- | ------------------------------- | ------ |
| `duration_ms` | 권한 결정 대기 시간                     |        |
| `decision`    | `accept` 또는 `reject`            |        |
| `source`      | 결정 출처 (`tool_decision` 이벤트와 일치) |        |

**`claude_code.tool.execution`**

| 속성            | 설명                                                                                   | 게이트 대상                  |
| ------------- | ------------------------------------------------------------------------------------ | ----------------------- |
| `duration_ms` | 도구 본문 실행 시간                                                                          |                         |
| `success`     | `true` 또는 `false`                                                                    |                         |
| `error`       | 실행이 실패했을 때 오류 범주 문자열 (예: `Error:ENOENT` 또는 `ShellError`). 게이트가 설정되면 전체 오류 메시지를 포함합니다 | `OTEL_LOG_TOOL_DETAILS` |

**`claude_code.hook`**

이 스팬은 상세 베타 추적이 활성화되어 있을 때만 내보내지며, 이는 위의 추적 내보내기 구성 외에 `ENABLE_BETA_TRACING_DETAILED=1` 및 `BETA_TRACING_ENDPOINT`가 필요합니다. 대화형 CLI 세션에서는 조직이 이 기능에 대해 허용 목록에 있어야 합니다. Agent SDK 및 비대화형 `-p` 세션은 게이트되지 않습니다. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`만 설정되어 있을 때는 내보내지지 않습니다.

| 속성                       | 설명                              | 게이트 대상                  |
| ------------------------ | ------------------------------- | ----------------------- |
| `hook_event`             | 훅 이벤트 유형 (예: `PreToolUse`)      |                         |
| `hook_name`              | 전체 훅 이름 (예: `PreToolUse:Write`) |                         |
| `num_hooks`              | 실행된 일치하는 훅 명령 수                 |                         |
| `hook_definitions`       | JSON 직렬화된 훅 구성                  | `OTEL_LOG_TOOL_DETAILS` |
| `duration_ms`            | 모든 일치하는 훅의 벽시계 지속 시간            |                         |
| `num_success`            | 성공적으로 완료된 훅 수                   |                         |
| `num_blocking`           | 차단 결정을 반환한 훅 수                  |                         |
| `num_non_blocking_error` | 차단 없이 실패한 훅 수                   |                         |
| `num_cancelled`          | 완료 전에 취소된 훅 수                   |                         |

<Note>
  `new_context`, `system_prompt_preview`, `user_system_prompt`, `tool_input` 및 `response.model_output`과 같은 추가 콘텐츠 포함 속성은 상세 베타 추적이 활성화되어 있을 때만 내보내집니다. 이들은 안정적인 스팬 스키마의 일부가 아닙니다. `user_system_prompt`는 추가로 `OTEL_LOG_USER_PROMPTS=1`이 필요합니다. 이는 `systemPrompt` SDK 옵션 또는 `--system-prompt` 및 `--append-system-prompt` 플래그를 통해 제공하는 시스템 프롬프트 텍스트만 포함하며 60KB에서 잘리고 요청당이 아닌 세션당 한 번 내보내집니다.
</Note>

### 동적 헤더

동적 인증이 필요한 엔터프라이즈 환경의 경우 스크립트를 구성하여 헤더를 동적으로 생성할 수 있습니다:

#### 설정 구성

`.claude/settings.json`에 추가:

```json theme={null}
{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
```

#### 스크립트 요구 사항

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

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

#### 새로 고침 동작

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

### 다중 팀 조직 지원

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

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

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

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

<Warning>
  **OTEL\_RESOURCE\_ATTRIBUTES에 대한 중요한 형식 요구 사항:**

  `OTEL_RESOURCE_ATTRIBUTES` 환경 변수는 쉼표로 구분된 key=value 쌍을 사용하며 엄격한 형식 요구 사항이 있습니다:

  * **공백 허용 안 함**: 값에 공백이 포함될 수 없습니다. 예를 들어 `user.organizationName=My Company`는 유효하지 않습니다
  * **형식**: 쉼표로 구분된 키=값 쌍이어야 합니다: `key1=value1,key2=value2`
  * **허용된 문자**: 제어 문자, 공백, 큰따옴표, 쉼표, 세미콜론 및 백슬래시를 제외한 US-ASCII 문자만 허용됩니다
  * **특수 문자**: 허용된 범위 외의 문자는 퍼센트 인코딩되어야 합니다

  **예:**

  ```bash theme={null}
  # ❌ 유효하지 않음 - 공백 포함
  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"
  ```

  참고: 값을 따옴표로 감싸도 공백이 이스케이프되지 않습니다. 예를 들어 `org.name="My Company"`는 `My Company`가 아닌 리터럴 값 `"My Company"` (따옴표 포함)를 생성합니다.
</Warning>

### 예제 구성

`claude`를 실행하기 전에 이러한 환경 변수를 설정합니다. 각 블록은 다양한 내보내기 또는 배포 시나리오에 대한 완전한 구성을 보여줍니다:

```bash theme={null}
# 콘솔 디버깅 (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
```

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

### 표준 속성

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

| 속성                  | 설명                                                                    | 제어 대상                                           |
| ------------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| `session.id`        | 고유 세션 식별자                                                             | `OTEL_METRICS_INCLUDE_SESSION_ID` (기본값: true)   |
| `app.version`       | 현재 Claude Code 버전                                                     | `OTEL_METRICS_INCLUDE_VERSION` (기본값: false)     |
| `organization.id`   | 조직 UUID (인증된 경우)                                                      | 사용 가능할 때 항상 포함됨                                 |
| `user.account_uuid` | 계정 UUID (인증된 경우)                                                      | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |
| `user.account_id`   | Anthropic 관리 API와 일치하는 태그 형식의 계정 ID (인증된 경우) (예: `user_01BWBeN28...`) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (기본값: true) |
| `user.id`           | 익명 장치/설치 식별자 (Claude Code 설치당 생성됨)                                    | 항상 포함됨                                          |
| `user.email`        | 사용자 이메일 주소 (OAuth를 통해 인증된 경우)                                         | 사용 가능할 때 항상 포함됨                                 |
| `terminal.type`     | 터미널 유형 (예: `iTerm.app`, `vscode`, `cursor`, `tmux`)                   | 감지될 때 항상 포함됨                                    |

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

* `prompt.id`: 사용자 프롬프트를 다음 프롬프트까지의 모든 후속 이벤트와 상관시키는 UUID입니다. [이벤트 상관 속성](#event-correlation-attributes)을 참조하세요.
* `workspace.host_paths`: 데스크톱 앱에서 선택한 호스트 작업 공간 디렉토리 (문자열 배열)

### 메트릭

Claude Code는 다음 메트릭을 내보냅니다:

| 메트릭 이름                                | 설명                 | 단위     |
| ------------------------------------- | ------------------ | ------ |
| `claude_code.session.count`           | 시작된 CLI 세션 수       | count  |
| `claude_code.lines_of_code.count`     | 수정된 코드 라인 수        | count  |
| `claude_code.pull_request.count`      | 생성된 풀 요청 수         | count  |
| `claude_code.commit.count`            | 생성된 git 커밋 수       | count  |
| `claude_code.cost.usage`              | Claude Code 세션의 비용 | USD    |
| `claude_code.token.usage`             | 사용된 토큰 수           | tokens |
| `claude_code.code_edit_tool.decision` | 코드 편집 도구 권한 결정 수   | count  |
| `claude_code.active_time.total`       | 총 활성 시간 (초)        | s      |

### 메트릭 세부 정보

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

#### 세션 카운터

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

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `start_type`: 세션이 시작된 방식. `"fresh"`, `"resume"` 또는 `"continue"` 중 하나

#### 코드 라인 카운터

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

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `type`: (`"added"`, `"removed"`)

#### 풀 요청 카운터

Claude Code를 통해 풀 요청을 생성할 때 증가합니다.

**속성**:

* 모든 [표준 속성](#standard-attributes)

#### 커밋 카운터

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

**속성**:

* 모든 [표준 속성](#standard-attributes)

#### 비용 카운터

각 API 요청 후 증가합니다.

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `model`: 모델 식별자 (예: "claude-sonnet-4-6")
* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"` 또는 `"auxiliary"` 중 하나
* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외에는 없음
* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 모델이 노력을 지원하지 않을 때는 없음

#### 토큰 카운터

각 API 요청 후 증가합니다.

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)
* `model`: 모델 식별자 (예: "claude-sonnet-4-6")
* `query_source`: 요청을 발급한 하위 시스템의 범주. `"main"`, `"subagent"` 또는 `"auxiliary"` 중 하나
* `speed`: 요청이 빠른 모드를 사용했을 때 `"fast"`. 그 외에는 없음
* `effort`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level). [비용 카운터](#cost-counter)의 세부 정보를 참조하세요.

#### 코드 편집 도구 결정 카운터

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

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `tool_name`: 도구 이름 (`"Edit"`, `"Write"`, `"NotebookEdit"`)
* `decision`: 사용자 결정 (`"accept"`, `"reject"`)
* `source`: 결정 출처 - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` 또는 `"user_reject"`
* `language`: 편집된 파일의 프로그래밍 언어 (예: `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). 인식되지 않는 파일 확장자의 경우 `"unknown"`을 반환합니다.

#### 활성 시간 카운터

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

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `type`: 키보드 상호 작용의 경우 `"user"`, 도구 실행 및 AI 응답의 경우 `"cli"`

### 이벤트

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

#### 이벤트 상관 속성

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

| 속성          | 설명                                             |
| ----------- | ---------------------------------------------- |
| `prompt.id` | 단일 사용자 프롬프트 처리 중에 생성된 모든 이벤트를 연결하는 UUID v4 식별자 |

단일 프롬프트로 트리거된 모든 활동을 추적하려면 특정 `prompt.id` 값으로 이벤트를 필터링합니다. 이는 user\_prompt 이벤트, 모든 api\_request 이벤트 및 해당 프롬프트 처리 중에 발생한 모든 tool\_result 이벤트를 반환합니다.

<Note>
  `prompt.id`는 각 프롬프트가 고유 ID를 생성하여 계속 증가하는 시계열 수를 만들기 때문에 의도적으로 메트릭에서 제외됩니다. 이벤트 수준 분석 및 감사 추적에만 사용합니다.
</Note>

#### 사용자 프롬프트 이벤트

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

**이벤트 이름**: `claude_code.user_prompt`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`으로 보고합니다

#### 도구 결과 이벤트

도구가 실행을 완료할 때 기록됩니다.

**이벤트 이름**: `claude_code.tool_result`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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 요청 이벤트

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

**이벤트 이름**: `claude_code.api_request`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`: 요청에 적용된 [노력 수준](/ko/model-config#adjust-effort-level): `"low"`, `"medium"`, `"high"`, `"xhigh"` 또는 `"max"`. 모델이 노력을 지원하지 않을 때는 없음

#### API 오류 이벤트

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

**이벤트 이름**: `claude_code.api_error`

**속성**:

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

#### API 요청 본문 이벤트

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

**이벤트 이름**: `claude_code.api_request_body`

**속성**:

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

#### API 응답 본문 이벤트

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

**이벤트 이름**: `claude_code.api_response_body`

**속성**:

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

#### 도구 결정 이벤트

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

**이벤트 이름**: `claude_code.tool_decision`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` 또는 `"user_reject"`

#### 권한 모드 변경 이벤트

권한 모드가 변경될 때 기록됩니다 (예: `Shift+Tab` 순환, 계획 모드 종료 또는 자동 모드 게이트 확인).

**이벤트 이름**: `claude_code.permission_mode_changed`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `event.name`: `"permission_mode_changed"`
* `event.timestamp`: ISO 8601 타임스탬프
* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
* `from_mode`: 이전 권한 모드 (예: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"` 또는 `"bypassPermissions"`)
* `to_mode`: 새 권한 모드
* `trigger`: 변경을 야기한 것. `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` 또는 `"auto_opt_in"` 중 하나. SDK 또는 브리지에서 전환이 시작될 때는 없음

#### 인증 이벤트

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

**이벤트 이름**: `claude_code.auth`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `event.name`: `"auth"`
* `event.timestamp`: ISO 8601 타임스탬프
* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
* `action`: `"login"` 또는 `"logout"`
* `success`: `"true"` 또는 `"false"`
* `auth_method`: 인증 방법 (예: `"oauth"`)
* `error_category`: 작업이 실패했을 때 범주별 오류 종류. 원본 오류 메시지는 포함되지 않습니다
* `status_code`: 작업이 HTTP 오류로 실패했을 때 HTTP 상태 코드 (문자열)

#### MCP 서버 연결 이벤트

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

**이벤트 이름**: `claude_code.mcp_server_connection`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`일 때): 연결이 실패했을 때 전체 오류 메시지

#### 내부 오류 이벤트

Claude Code가 예상치 못한 내부 오류를 포착할 때 기록됩니다. 오류 클래스 이름과 errno 스타일 코드만 기록됩니다. 오류 메시지 및 스택 추적은 포함되지 않습니다. 이 이벤트는 Bedrock, Vertex 또는 Foundry에 대해 실행하거나 `DISABLE_ERROR_REPORTING`이 설정되어 있을 때는 내보내지지 않습니다.

**이벤트 이름**: `claude_code.internal_error`

**속성**:

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

#### 플러그인 설치됨 이벤트

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

**이벤트 이름**: `claude_code.plugin_installed`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`일 때만 포함됩니다

#### 스킬 활성화됨 이벤트

스킬이 호출될 때 기록됩니다.

**이벤트 이름**: `claude_code.skill_activated`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `event.name`: `"skill_activated"`
* `event.timestamp`: ISO 8601 타임스탬프
* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
* `skill.name`: 스킬의 이름. 사용자 정의 및 타사 플러그인 스킬의 경우 `OTEL_LOG_TOOL_DETAILS=1`이 아니면 값은 자리 표시자 `"custom_skill"`입니다
* `skill.source`: 스킬이 로드된 위치 (예: `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)
* `plugin.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인의 이름
* `marketplace.name` (`OTEL_LOG_TOOL_DETAILS=1`이거나 플러그인이 공식 마켓플레이스에서 온 경우): 스킬이 플러그인에서 제공될 때 소유 플러그인이 설치된 마켓플레이스

#### API 재시도 소진됨 이벤트

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

**이벤트 이름**: `claude_code.api_retries_exhausted`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `event.name`: `"api_retries_exhausted"`
* `event.timestamp`: ISO 8601 타임스탬프
* `event.sequence`: 세션 내 이벤트 순서 지정을 위한 단조 증가 카운터
* `model`: 사용된 모델
* `error`: 최종 오류 메시지
* `status_code`: HTTP 상태 코드 (문자열)
* `total_attempts`: 수행된 총 시도 횟수
* `total_retry_duration_ms`: 모든 시도에 걸친 총 벽시계 시간
* `speed`: `"fast"` 또는 `"normal"`

#### 훅 실행 시작 이벤트

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

**이벤트 이름**: `claude_code.hook_execution_start`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`이 모두 활성화되어 있을 때만 포함됨

#### 훅 실행 완료 이벤트

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

**이벤트 이름**: `claude_code.hook_execution_complete`

**속성**:

* 모든 [표준 속성](#standard-attributes)
* `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`이 모두 활성화되어 있을 때만 포함됨

#### 압축 이벤트

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

**이벤트 이름**: `claude_code.compaction`

**속성**:

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

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

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

### 사용 모니터링

| 메트릭                                                           | 분석 기회                             |
| ------------------------------------------------------------- | --------------------------------- |
| `claude_code.token.usage`                                     | `type` (입력/출력), 사용자, 팀 또는 모델별로 분류 |
| `claude_code.session.count`                                   | 시간 경과에 따른 채택 및 참여 추적              |
| `claude_code.lines_of_code.count`                             | 코드 추가/제거를 추적하여 생산성 측정             |
| `claude_code.commit.count` & `claude_code.pull_request.count` | 개발 워크플로우에 미치는 영향 이해               |

### 비용 모니터링

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

* 팀 또는 개인 전체의 사용 추세 추적
* 최적화를 위한 높은 사용 세션 식별

<Note>
  비용 메트릭은 근사값입니다. 공식 청구 데이터는 API 제공자 (Claude Console, AWS Bedrock 또는 Google Cloud Vertex)를 참조하세요.
</Note>

### 경고 및 세분화

고려할 일반적인 경고:

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

모든 메트릭은 `user.account_uuid`, `user.account_id`, `organization.id`, `session.id`, `model` 및 `app.version`으로 세분화할 수 있습니다.

### 재시도 소진 감지

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

이벤트의 `attempt` 속성은 총 시도 횟수를 기록합니다. `CLAUDE_CODE_MAX_RETRIES` (기본값 `10`)보다 큰 값은 요청이 일시적 오류에 대한 모든 재시도를 소진했음을 나타냅니다. 더 낮은 값은 `400` 응답과 같은 재시도 불가능한 오류를 나타냅니다.

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

### 이벤트 분석

이벤트 데이터는 Claude Code 상호 작용에 대한 자세한 통찰력을 제공합니다:

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

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

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

## 백엔드 고려 사항

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

### 메트릭의 경우

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

### 이벤트/로그의 경우

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

### 추적의 경우

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

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

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

## 서비스 정보

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

* `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 측정 리소스

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

## 보안 및 개인 정보 보호

* 원격 측정은 선택 사항이며 명시적 구성이 필요합니다
* 원본 파일 콘텐츠 및 코드 스니펫은 메트릭 또는 이벤트에 포함되지 않습니다. 추적 스팬은 별도의 데이터 경로입니다: 아래의 `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 모니터링

Amazon Bedrock의 Claude Code 사용 모니터링에 대한 자세한 지침은 [Claude Code 모니터링 구현 (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)을 참조하세요.