Claude Code에서 OpenTelemetry를 활성화하고 구성하는 방법을 알아보세요.
/Library/Application Support/ClaudeCode/managed-settings.json
/etc/claude-code/managed-settings.json
C:\ProgramData\ClaudeCode\managed-settings.json
환경 변수 | 설명 | 예시 값 |
---|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | 텔레메트리 수집 활성화 (필수) | 1 |
OTEL_METRICS_EXPORTER | 메트릭 익스포터 유형(쉼표로 구분) | console , otlp , prometheus |
OTEL_LOGS_EXPORTER | 로그/이벤트 익스포터 유형(쉼표로 구분) | console , otlp |
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_METRICS_INCLUDE_SESSION_ID | 메트릭에 session.id 속성 포함 | true | false |
OTEL_METRICS_INCLUDE_VERSION | 메트릭에 app.version 속성 포함 | false | true |
OTEL_METRICS_INCLUDE_ACCOUNT_UUID | 메트릭에 user.account_uuid 속성 포함 | true | false |
.claude/settings.json
에 추가:
OTEL_RESOURCE_ATTRIBUTES
환경 변수를 사용하여 서로 다른 그룹을 구별하는 사용자 정의 속성을 추가할 수 있습니다:
OTEL_RESOURCE_ATTRIBUTES
환경 변수는 W3C Baggage 사양을 따르며, 엄격한 형식 요구사항이 있습니다:user.organizationName=My Company
는 유효하지 않습니다key1=value1,key2=value2
"key=value with spaces"
)은 OpenTelemetry 사양에서 지원되지 않으며 속성이 따옴표로 시작하게 됩니다.속성 | 설명 | 제어 변수 |
---|---|---|
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) |
terminal.type | 터미널 유형 (예: iTerm.app , vscode , cursor , tmux ) | 감지될 때 항상 포함 |
메트릭 이름 | 설명 | 단위 |
---|---|---|
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 |
type
: ("added"
, "removed"
)model
: 모델 식별자 (예: “claude-3-5-sonnet-20241022”)type
: ("input"
, "output"
, "cacheRead"
, "cacheCreation"
)model
: 모델 식별자 (예: “claude-3-5-sonnet-20241022”)tool
: 도구 이름 ("Edit"
, "MultiEdit"
, "Write"
, "NotebookEdit"
)decision
: 사용자 결정 ("accept"
, "reject"
)language
: 편집된 파일의 프로그래밍 언어 (예: "TypeScript"
, "Python"
, "JavaScript"
, "Markdown"
). 인식되지 않는 파일 확장자의 경우 "unknown"
을 반환합니다.OTEL_LOGS_EXPORTER
가 구성된 경우):
claude_code.user_prompt
속성:
event.name
: "user_prompt"
event.timestamp
: ISO 8601 타임스탬프prompt_length
: 프롬프트 길이prompt
: 프롬프트 내용 (기본적으로 편집됨, OTEL_LOG_USER_PROMPTS=1
로 활성화)claude_code.tool_result
속성:
event.name
: "tool_result"
event.timestamp
: ISO 8601 타임스탬프tool_name
: 도구 이름success
: "true"
또는 "false"
duration_ms
: 실행 시간(밀리초)error
: 오류 메시지 (실패한 경우)decision
: "accept"
또는 "reject"
source
: 결정 소스 - "config"
, "user_permanent"
, "user_temporary"
, "user_abort"
, 또는 "user_reject"
tool_parameters
: 도구별 매개변수를 포함하는 JSON 문자열 (사용 가능한 경우)
bash_command
, full_command
, timeout
, description
, sandbox
포함claude_code.api_request
속성:
event.name
: "api_request"
event.timestamp
: ISO 8601 타임스탬프model
: 사용된 모델 (예: “claude-3-5-sonnet-20241022”)cost_usd
: 예상 비용(USD)duration_ms
: 요청 지속 시간(밀리초)input_tokens
: 입력 토큰 수output_tokens
: 출력 토큰 수cache_read_tokens
: 캐시에서 읽은 토큰 수cache_creation_tokens
: 캐시 생성에 사용된 토큰 수claude_code.api_error
속성:
event.name
: "api_error"
event.timestamp
: ISO 8601 타임스탬프model
: 사용된 모델 (예: “claude-3-5-sonnet-20241022”)error
: 오류 메시지status_code
: HTTP 상태 코드 (해당하는 경우)duration_ms
: 요청 지속 시간(밀리초)attempt
: 시도 번호 (재시도된 요청의 경우)claude_code.tool_decision
속성:
event.name
: "tool_decision"
event.timestamp
: ISO 8601 타임스탬프tool_name
: 도구 이름 (예: “Read”, “Edit”, “MultiEdit”, “Write”, “NotebookEdit” 등)decision
: "accept"
또는 "reject"
source
: 결정 소스 - "config"
, "user_permanent"
, "user_temporary"
, "user_abort"
, 또는 "user_reject"
메트릭 | 분석 기회 |
---|---|
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
메트릭은 다음에 도움이 됩니다:
user.account_uuid
, organization.id
, session.id
, model
, app.version
으로 세분화할 수 있습니다.
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
OTEL_LOG_USER_PROMPTS=1
을 설정하세요