donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
55de4f55b037af9554af9007ce834030ac7e729e
llm-wiki/raw/official-docs/tracing-otel-trace-api-spec.md
T

7.9 KiB
Raw Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created
title source_type url archive_url related_branches related_projects tags created
OpenTelemetry Tracing API Specification official-doc https://opentelemetry.io/docs/specs/otel/trace/api/
feature-distributed-tracing-contract
ca-skeleton
official-doc
ca-skeleton
tracing
observability
opentelemetry
backend
2026-06-14

OpenTelemetry Tracing API Specification

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-distributed-tracing-contract D4 — tracing disabled 시 exporter/sampling off 만으로 meaningful traceId 유지 가능. SDK noop 을 쓰면 all-zero ID 가 생성되므로 "disabled but keep meta.traceId" 는 SDK-on + exporter-off 로만 유효.
raw/branch-notes/feature-distributed-tracing-contract D12 — span 예외 recording 시 RecordException 은 Event 만 기록하는 AddEvent 변형이고, status=ERROR 설정은 별도 SetStatus 호출이 필요함.

출처 / Source

왜 저장했는지 / Why archived

D4 의 "disabled profile 에서 meaningful traceId 유지" 결정에 대해 SDK noop 이 all-zero Span/Trace ID 를 반환한다는 스펙 근거가 필요했다. 또한 D12 span error recording 에서 RecordException 이 status=ERROR 를 자동으로 세팅하지 않는다는 사실을 공식 스펙으로 확인하기 위해 보관.

핵심 인용 / Key quotes (verbatim, 4개)

[§Behavior of the API in the absence of an installed SDK] "In general, in the absence of an installed SDK, the Trace API is a "no-op" API." (line 813 of fetched markdown)

[§Behavior of the API in the absence of an installed SDK] "If the parent Context contains no Span, an empty non-recording Span MUST be returned instead (i.e., having a SpanContext with all-zero Span and Trace IDs, empty Tracestate, and unsampled TraceFlags). This means that a SpanContext that has been provided by a configured Propagator will be propagated through to any child span and ultimately also Inject, but that no new SpanContexts will be created." (lines 820–825 of fetched markdown)

[§Record Exception] "This is a specialized variant of AddEvent, so for anything not specified here, the same requirements as for AddEvent apply." (line 639 of fetched markdown)

[§Set Status] "These values form a total order: Ok > Error > Unset." (line 541 of fetched markdown)

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
OTEL-TAPI-C1 SDK 가 설치되지 않은 경우 Trace API 는 no-op 으로 동작한다 [§Absence of SDK] "In general, in the absence of an installed SDK, the Trace API is a "no-op" API." official-reference OTel Trace API 구현 전반 — 언어 무관 SDK가 설치되지 않은 상태에서 SDK-on + exporter-off 시나리오까지 증명하지 않음. 이 claim 은 SDK 자체가 없을 때의 동작만 다룸
OTEL-TAPI-C2 SDK noop 상태에서 부모 Context 에 Span 이 없으면, 반환되는 비-기록 Span 의 SpanContext 는 all-zero Trace/Span ID 를 가진다 [§Absence of SDK] "having a `SpanContext` with all-zero Span and Trace IDs, empty Tracestate, and unsampled TraceFlags" official-reference 부모 Context 에 Span 이 없는 루트 스팬 생성 시점 부모 Context 에 이미 유효한 SpanContext 가 있을 때의 동작은 별도 규정(부모 SpanContext 전파). SDK-on + exporter-off 시나리오는 이 claim 의 범위 밖
OTEL-TAPI-C3 SDK noop 상태에서는 새로운 SpanContext 가 생성되지 않는다 [§Absence of SDK] "no new SpanContexts will be created" official-reference SDK 미설치 상태 전체 SDK-on 상태에서의 동작과 구별 필요. exporter-off SDK-on 의 경우 SpanContext 는 정상 생성됨
OTEL-TAPI-C4 RecordException 은 AddEvent 의 특화 변형이며, Event 를 기록하는 것이다 — SetStatus 를 자동으로 호출하지 않는다 [§Record Exception] "This is a specialized variant of `AddEvent`, so for anything not specified here, the same requirements as for `AddEvent` apply." official-reference RecordException 을 제공하는 모든 OTel 언어 구현 RecordException 이 status=ERROR 를 세팅한다는 것을 이 인용이 직접 말하지 않음. 별도 SetStatus 호출 없이 에러 상태가 자동 설정된다는 것도 증명 안 됨
OTEL-TAPI-C5 Span Status 값의 우선순위는 Ok > Error > Unset 순서이며, Ok 로 설정되면 이후 변경 시도는 무시되어야 한다 [§Set Status] "These values form a total order: `Ok > Error > Unset`." official-reference SetStatus API 를 사용하는 모든 OTel 구현 이 우선순위 규칙이 특정 언어/SDK 에서 기본값으로 적용됨을 보장하지 않음

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:

    • OTEL-TAPI-C1, OTEL-TAPI-C2, OTEL-TAPI-C3: SDK 미설치(noop) 상태에서 루트 Span 은 all-zero ID SpanContext 를 가지며 새 SpanContext 가 생성되지 않는다.
    • OTEL-TAPI-C4: RecordException 은 AddEvent 변형으로 Event 만 기록하며, status 를 자동으로 ERROR 로 세팅하지 않는다.
    • OTEL-TAPI-C5: SetStatus 의 우선순위 규칙 (Ok > Error > Unset).

  • 이 자료가 증명하지 않는 것:

    • SDK-on + exporter-off 시나리오에서 SpanContext 가 정상 생성된다는 것 (이 시나리오는 SDK 설치 상태이므로 no-op 규칙이 적용되지 않음 — 별도 SDK 동작 spec 참조 필요).
    • D4 의 "meaningful traceId 유지" 정책 자체가 best practice 임을 직접 증명하지 않음. OTel spec 은 disabled 시 traceId 를 유지하라고 권고하지 않음.
    • RecordException 이 특정 언어(예: Java Micrometer Observation) 에서 어떻게 노출되는지.

  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:

    • ca-tmpl 의 Spring Boot Micrometer Tracing + OTel exporter 설정에서 exporter-off 시 SpanContext 가 여전히 propagation 에 사용 가능한지 wire-level 검증.
    • Observation.error(throwable) 호출이 내부적으로 RecordException 과 SetStatus(ERROR) 를 별도로 호출하는지 Micrometer Tracing source 확인.

메모 / Notes

  • D4 critical finding: OTEL-TAPI-C2/C3 는 SDK noop 상태에서는 all-zero ID 와 "no new SpanContext" 를 명시한다. 따라서 D4 의 "tracing disabled 시에도 meta.traceId 유지" 는 SDK-on + exporter-off 구성으로만 구현 가능. SDK 자체를 noop 으로 두면 meaningful traceId 는 생성되지 않는다. D4 의 UNSUPPORTED_DECISION 라벨은 이 spec 으로 부분 해소되지만, "exporter-off SDK-on 에서 meaningful traceId 가 생성된다"는 별도 SDK 동작 spec 이 추가로 필요하다.
  • D12 finding: OTEL-TAPI-C4 는 RecordException 이 SetStatus 를 포함하지 않음을 간접적으로 확인. spec 은 RecordException 을 AddEvent 의 변형으로만 정의하며 status 변경을 언급하지 않는다. 따라서 error status 설정은 별도 SetStatus(ERROR) 호출이 필요함.
  • 인용된 spec 은 Status: Stable (2026-06-14 확인).

Related / 관련

Reference in New Issue View Git Blame Copy Permalink