donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/official-docs/otel-exceptions-semantic-conventions.md
T

11 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 tags created
official-doc / OpenTelemetry — Semantic Conventions for Exceptions on Spans + Recording Errors + Trace API Set Status official-doc https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/
feature-operational-error-observability-foundation
ca-skeleton
official-doc
ca-skeleton
observability
error-handling
opentelemetry
span-event
trace-status
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

왜 저장했는지 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink