llm-wiki/raw/official-docs/tracing-otel-trace-api-spec.md

---
title: OpenTelemetry Tracing API Specification
source_type: official-doc
url: https://opentelemetry.io/docs/specs/otel/trace/api/
archive_url:
related_branches: [feature-distributed-tracing-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, tracing, observability, opentelemetry, backend]
created: 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

- 원본 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 `SpanContext`s will be created."
> (lines 820–825 of fetched markdown)

> [§Record Exception] "This is a specialized variant of [`AddEvent`](#add-events), 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\`](#add-events), 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 / 관련

- 같은 주제 다른 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 요약: (생성 시 추가)