llm-wiki/raw/official-docs/otel-exceptions-semantic-conventions.md

---
title: "official-doc / OpenTelemetry — Semantic Conventions for Exceptions on Spans + Recording Errors + Trace API Set Status"
source_type: official-doc
url: https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/
archive_url:
related_branches: [feature-operational-error-observability-foundation]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, error-handling, opentelemetry, span-event, trace-status]
created: 2026-06-01
---

# official-doc / OpenTelemetry — Semantic Conventions for Exceptions on Spans + Recording Errors + Trace API Set Status

> Layer: `raw/official-docs/` — OpenTelemetry 공식 사양 3개 페이지의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | D16 — 운영 오류(5xx/INTERNAL) 발생 시 서버 측 span 에 `exception` 이벤트 기록 (`exception.type`, `exception.message`, `exception.stacktrace`) + span status ERROR 설정 (서버 측 telemetry 전용, 클라이언트 HTTP 응답에 stack trace 미포함) |

## 출처 / Source

- 원본 URL 1 (예외 span): https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/
- 원본 URL 2 (에러 기록): https://opentelemetry.io/docs/specs/semconv/general/recording-errors/
- 원본 URL 3 (Trace API Set Status): https://opentelemetry.io/docs/specs/otel/trace/api/#set-status
- 아카이브 URL:
- 저자 / 조직: OpenTelemetry Authors (CNCF)
- 사양 버전: Semantic conventions 1.41.0 (exceptions-spans: Status Deprecated → logs 이전 권고; recording-errors: Status Development)
- 마지막 확인일: 2026-06-01

## 왜 저장했는지 / Why archived

`feature-operational-error-observability-foundation` branch 의 결정 D16 은 서버 측 span 에 `exception` 이벤트를 기록하고 span status 를 ERROR 로 설정하는 기준을 정의한다. 이 자료는 그 기준의 공식 사양 근거 — `exception` 이벤트의 속성 정의(`exception.type`, `exception.message`, `exception.stacktrace`), 에러 발생 시 span status ERROR 설정 의무(`SHOULD`), 그리고 Instrumentation Library 가 아닌 **Application 코드**가 status 를 설정해야 하는 맥락을 제공한다. 스택 트레이스는 서버 측 telemetry 속성으로만 정의되며, 클라이언트 HTTP 응답 노출 여부는 이 사양 범위 밖이다.

## 핵심 인용 / Key quotes (verbatim, 3~5문장)

> [§ Exception event — exceptions-spans] "The event name MUST be `exception`."
> (source: https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/ — line 48 in fetched text)

> [§ Exception event attributes — exceptions-spans] "A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG."
> (attribute: `exception.stacktrace`, Requirement Level: Recommended — line 102 in fetched text)

> [§ Recording errors on spans — recording-errors] "Span Status Code MUST be left unset if the instrumented operation has ended without any errors. When the operation ends with an error, instrumentation: SHOULD set the span status code to `Error`"
> (source: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ — lines 54–59 in fetched text)

> [§ Recording exceptions — recording-errors] "Exceptions which are propagated to the caller should be recorded (or logged) once."
> (source: https://opentelemetry.io/docs/specs/semconv/general/recording-errors/ — line 111 in fetched text)

> [§ Set Status — trace/api] "When the status is set to `Error` by Instrumentation Libraries, the `Description` SHOULD be documented and predictable. The status code should only be set to `Error` according to the rules defined within the semantic conventions. [...] Application developers and Operators may set the status code to `Ok`."
> (source: https://opentelemetry.io/docs/specs/otel/trace/api/#set-status — lines 612–623 in fetched text)

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OTEL-EXC-C1 | span 위에 예외를 기록할 때 이벤트 이름은 반드시 `exception` 이어야 한다 | [§ Exception event] "The event name MUST be `exception`." | `official-vendor-doc` | OTel Semantic Conventions 를 따르는 모든 계측 코드 | 이벤트를 어느 시점에 호출해야 하는지(API 호출 순서) 는 정의하지 않음 |
| OTEL-EXC-C2 | `exception` 이벤트에는 `exception.type`, `exception.message`, `exception.stacktrace` 세 속성이 정의되어 있으며, `exception.type`/`exception.message` 는 Conditionally Required, `exception.stacktrace` 는 Recommended | [§ Exception event attributes] "`exception.type` Conditionally Required [...] `exception.message` Conditionally Required [1] [...] `exception.stacktrace` Recommended" + "[1] `exception.message`: Required if `exception.type` is not set, recommended otherwise." | `official-vendor-doc` | OTel SDK 에서 `Span.recordException()` 또는 `addEvent("exception", ...)` 를 호출하는 모든 코드 | 세 속성 모두 클라이언트 HTTP 응답에 포함되어야 한다는 의미가 아님 — 이 속성들은 telemetry 신호(span) 안의 속성 |
| OTEL-EXC-C3 | `exception.stacktrace` 는 "언어 런타임의 자연스러운 표현 방식으로 된 문자열 스택 트레이스" 로 Recommended 속성이다 | [§ Exception event attributes] "A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG." | `official-vendor-doc` | Java 는 `Throwable.printStackTrace()` 내용을 사용 | 스택 트레이스를 클라이언트 응답에 포함해야 한다거나 포함해도 된다는 의미 아님 — span 속성 전용 |
| OTEL-EXC-C4 | 오류로 끝나는 작업에서 계측 코드는 span status code 를 `Error` 로 설정해야 하며(SHOULD), 오류 없이 종료된 작업의 Span Status Code 는 반드시(MUST) unset 으로 두어야 한다 | [§ Recording errors on spans] "Span Status Code MUST be left unset if the instrumented operation has ended without any errors. When the operation ends with an error, instrumentation: SHOULD set the span status code to `Error`" | `official-vendor-doc` | 에러를 반환하거나 예외를 던지는 모든 계측 작업 | HTTP 5xx 응답이 항상 span status ERROR 를 의미한다는 것을 직접 정의하지 않음 — HTTP 상태 코드 매핑은 HTTP 전용 semconv 별도 참조 필요 |
| OTEL-EXC-C5 | 호출자에게 전파되는 예외는 span/log 에 정확히 한 번 기록되어야 한다; 계측 라이브러리가 내부적으로 처리하는 예외는 기록을 권장하지 않는다 | [§ Recording exceptions] "Exceptions which are propagated to the caller should be recorded (or logged) once." + "It's NOT RECOMMENDED to record exceptions that are handled by the instrumented library." | `official-vendor-doc` | span/log 에서 예외를 기록하는 모든 계측 코드 | 예외가 완전히 처리된 경우에도 반드시 기록해야 한다는 뜻 아님 |
| OTEL-EXC-C6 | Instrumentation Library 는 semantic convention 이 정의한 규칙에 따라서만 status 를 `Error` 로 설정해야 하며, Application developer 와 Operator 는 자유롭게 status 를 설정할 수 있다 | [§ Set Status] "The status code should only be set to `Error` according to the rules defined within the semantic conventions. [...] Application developers and Operators may set the status code to `Ok`." | `official-vendor-doc` | OTel SDK 를 사용하는 애플리케이션 코드와 계측 라이브러리의 역할 분리 | "Application developers may set status to `Error`" 를 직접 명시하지 않음 — `Ok` 에 대해서만 명시. `Error` 설정 권한은 semconv 규칙을 따르면 누구나 가능 (의미 추론 필요) |

### Strength 허용값 참고

`official-vendor-doc` 를 사용한 이유: OpenTelemetry Semantic Conventions 는 CNCF 에서 관리하는 공식 벤더 사양이며, RFC 수준의 표준과는 다르지만 업계 광범위하게 채택된 공식 스펙이다.

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `OTEL-EXC-C1`: `exception` span 이벤트의 이름 규약
  - `OTEL-EXC-C2`: `exception.type`, `exception.message`, `exception.stacktrace` 속성의 존재와 requirement level
  - `OTEL-EXC-C3`: `exception.stacktrace` 가 telemetry 전용 span 속성임 (클라이언트 응답 포함 여부는 이 사양 범위 밖)
  - `OTEL-EXC-C4`: 오류 발생 시 span status SHOULD ERROR, 오류 없으면 MUST unset
  - `OTEL-EXC-C5`: 전파되는 예외는 한 번만 기록; 처리된 예외는 기록 비권장
  - `OTEL-EXC-C6`: Instrumentation Library 는 semconv 규칙만, Application developer 는 자유롭게 status 설정 가능
- 이 자료가 증명하지 않는 것:
  - HTTP 5xx 응답이 span status ERROR 를 항상 의미한다는 것 (HTTP semconv 별도 참조 필요)
  - `exception.stacktrace` 를 클라이언트 HTTP 응답에 포함하면 안 된다는 것 — 이 사양은 telemetry 속성만 정의. 클라이언트 응답 보안은 별도 가이드라인 (ca-tmpl 의 Forbidden: stack trace in response 는 자체 정책)
  - span `recordException` API 의 구체적인 호출 시점이나 순서
  - exceptions-spans 사양이 deprecated 된 이후 대체 사양(exceptions in logs) 의 세부 내용
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - Micrometer Tracing (Spring Boot 기반) 에서 `recordException` / `setStatus(ERROR)` API 의 정확한 호출 패턴
  - `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` 환경변수 설정 여부 (deprecated span events → logs 전환 시 영향)
  - ca-tmpl 의 `error.category=INTERNAL` 시 span status ERROR + exception 이벤트 설정이 GlobalExceptionHandler 에서 자동으로 처리되는지 여부

## 메모 / Notes

- exceptions-spans 사양은 **Status: Deprecated** — 새 계측 코드는 exceptions-in-logs 로 이전 권고. 단, 기존 span event 방식은 `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` 없이도 계속 동작하므로 단기 적용에는 문제 없음.
- recording-errors 사양은 **Status: Development** — 안정화되지 않았음. 변경 가능성 있으므로 주기적 확인 필요 (`last_reviewed` 관리).
- `OTEL-EXC-C6` 에서 Application developer 의 `Error` status 설정 권한은 명시적 문장으로 확인되지 않음 (Ok 에 대해서만 명시). wiki 추출 시 별도 공식 문서에서 확인 권장.
- 추가로 봐야 할 동일 출처 페이지: https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/ (새 표준), https://opentelemetry.io/docs/specs/semconv/http/http-spans/ (HTTP 5xx → span ERROR 매핑)

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]] (OTel sampling)
- 이 자료를 인용한 wiki 요약: (생성 시 링크)