donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

7.9 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

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

원본 URL: https://opentelemetry.io/docs/specs/otel/trace/api/
아카이브 URL: (미등록)
저자 / 조직: OpenTelemetry Authors
발행일: (ongoing — stable spec)
마지막 확인일: 2026-06-14

왜 저장했는지 / 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 `SpanContext`s 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 확인).

같은 주제 다른 official-doc:
- raw/official-docs/tracing-w3c-trace-context-spec.md — W3C traceparent/tracestate propagation spec
- raw/official-docs/tracing-otel-sampling-tail-vs-head-spec.md — head vs tail sampling spec
- raw/official-docs/tracing-b3-propagation-zipkin-spec.md — B3 propagation spec
이 자료를 인용한 wiki 요약: (생성 시 추가)

7.9 KiB Raw Permalink Blame History Unescape Escape