OpenTelemetry

트레이스, 메트릭, 로그를 자체 컬렉터/백엔드로 내보내는 옵트인 OTLP 익스포트.

shunt는 트레이스, 메트릭, 로그를 OTLP/HTTP로 자체 OpenTelemetry Collector(또는 OTLP 호환 백엔드)에 내보낼 수 있습니다. 옵트인이며 기본적으로 꺼져 있습니다 — [otel] 섹션이 없으면 아무것도 머신 밖으로 나가지 않습니다 — 그리고 Sentry와 독립적으로 동작하므로 둘 중 하나 또는 둘 다 켤 수 있습니다.

활성화

키 하나로 켜집니다 — 컬렉터의 OTLP/HTTP 리시버를 가리키세요:

[otel]
endpoint = "http://localhost:4318"   # OTLP/HTTP base URL; shunt가 /v1/{traces,metrics,logs}를 덧붙임

나머지는 모두 합리적인 기본값을 가집니다:

[otel]
endpoint = "http://localhost:4318"
service_name = "shunt"     # (기본값) service.name 리소스 속성
environment = "prod"       # 선택: deployment.environment.name
sample_ratio = 1.0         # (기본값) head-based 트레이스 샘플링, 0.0–1.0
traces = true              # (기본값) 요청 스팬 내보내기
metrics = true             # (기본값) 사용량 메트릭 내보내기
logs = true                # (기본값) 로그 이벤트 내보내기 (stderr 로그는 영향 없음)
include_session_id = false # (기본값) 클라이언트 세션 id를 스팬에서 제외

[otel.headers]             # 선택: 요청마다 붙는 헤더, 예: 호스팅 컬렉터 토큰
authorization = "Bearer <token>"

endpoint = ""(예: SHUNT_OTEL__ENDPOINT="")로 설정하면 섹션을 지우지 않고도 익스포트를 다시 끕니다. 유효하지 않은 엔드포인트, http(s)가 아닌 URL, 범위를 벗어난 sample_ratio는 시작 오류이므로, 오타 때문에 모든 익스포트가 조용히 사라지지 않습니다.

세 가지 시그널

시그널	내보내는 내용	참고
트레이스	요청별 `proxy_request` 스팬	`sample_ratio` 기반 head 샘플링. 저(低)카디널리티이며 요청/응답 본문 없음.
메트릭	아래에 나열된 저카디널리티 계열	`[sentry] metrics = true`일 때 shunt가 Sentry로 보내는 것과 동일한 계열.
로그	shunt의 `tracing` 로그 이벤트를 OTLP로 브리지	stderr 로그는 영향받지 않음.

각 시그널은 traces / metrics / logs로 개별 토글합니다.

메트릭 계열

계열	유형	속성	의미
`shunt.requests`	카운터	`provider`, `model`, `http.response.status_code`	프록시된 추론 요청.
`shunt.latency`	히스토그램(ms)	`provider`, `model`, `http.response.status_code`	스트림은 헤더 지연 시간, 그 외에는 전체 지연 시간.
`shunt.ttft`	히스토그램(ms)	`provider`, `model`	요청 시작부터 첫 SSE 본문 청크까지의 시간.
`shunt.stream_outcome`	카운터	`provider`, `model`, `outcome`	SSE 최종 결과 하나: `completed`, `error_event`, `upstream_cut`, `client_disconnect`.
`shunt.tokens`	카운터	`provider`, `model`, `kind`	마지막으로 보고된 스트리밍 토큰 사용량(`input`, `output`, `cache_read`, `cache_creation`). 비스트리밍 사용량은 기록하지 않음.
`shunt.codex_continuation`	카운터	`provider`, `outcome`	Codex WebSocket continuation hit 또는 fallback.
`shunt.codex_client_events`	카운터	`event`	정제된 이벤트 이름별 Codex CLI 분석 이벤트. payload와 속성은 폐기됨.
`shunt.upstream_retries`	카운터	`provider`, `reason`	제한된 일시적 업스트림 재시도.
`shunt.failover`	카운터	`provider`, `state`	순서 있는 업스트림 페일오버 전환: `attempted`, `advanced`, `exhausted`.
`shunt.pool.quota_utilization`	게이지	`provider`, `window`	`5h`, `7d`, `7d_oi`별 활성 상태이고 관측됐으며 만료되지 않은 quota 값 중 최소 사용률.
`shunt.pool.rotations`	카운터	`provider`, `reason`	계정에서 이동한 횟수와 pool이 소진된 요청 수.

프라이버시

shunt는 메트릭과 트레이스에서 요청/응답 본문, 헤더, 자격 증명을 절대 내보내지 않습니다.

메트릭과 트레이스는 저카디널리티이며 본문이 없습니다. OTLP 트레이스 익스포트에서 요청 스팬의 클라이언트 세션 id는 include_session_id = true(기본 꺼짐)일 때만, 그리고 트레이스 익스포트가 활성화된 동안에만 컬렉터로 전송됩니다. 같은 규칙이 Sentry 트레이스 익스포트([sentry] traces_sample_rate / include_session_id)에도 적용됩니다. 어떤 스팬 익스포트도 활성화되지 않은 경우 id는 예전처럼 로컬 요청 스팬에만 남습니다.
로그는 shunt 자체 진단 이벤트를 있는 그대로 반영하므로, stderr 로그처럼 요청에서 파생된 필드(업스트림 오류 본문, 인증된 클라이언트 id)를 포함할 수 있습니다. 엄격하게 본문 없는 익스포트를 원하면 logs = false로 두고 메트릭/트레이스만 유지하세요.

내보내는 리소스는 service.*, telemetry.sdk.*, 그리고 environment가 설정된 경우 deployment.environment.name을 광고합니다 — host나 process detector가 실행되지 않아 머신 호스트네임은 붙지 않습니다 — 여기에 표준 OTEL_RESOURCE_ATTRIBUTES로 설정한 값이 더해집니다.

표준 `OTEL_` 환경 변수

endpoint와 service_name은 이 구성에서 오며 OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME보다 우선합니다.
표준 OTEL_EXPORTER_OTLP_HEADERS와 OTEL_RESOURCE_ATTRIBUTES는 [otel.headers] 및 내장 리소스 속성 위에 병합됩니다.

모든 키는 [otel] 구성 레퍼런스를 참고하세요.