OpenTelemetry 스팬 상태 검수, ERROR를 넣었는데 OK가 남는 이유
OpenTelemetry 스팬 상태는 마지막 설정만으로 정해지지 않습니다. SDK 실행 표본으로 OK·ERROR·UNSET의 우선순위와 예외 이벤트, 종료 뒤 변경을 나누는 인수 기준을 정리합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
OpenTelemetry 스팬의 OK는 뒤늦은 ERROR로 바뀌지 않습니다. 2026-11-22 확인 기준, 예외 이벤트도 상태와 따로 읽습니다.
오류를 표시하려고 스팬에 ERROR를 설정했는데 최종 기록은 OK일 수 있습니다. 앞서 호출한 성공 판정이 이후 상태 변경을 막았다면, 마지막 호출만 따라가서는 이유를 찾기 어렵습니다.
이 글은 에이전트·업무 자동화의 관측 결과를 인수하는 담당자를 위한 가상 SDK 실행 가이드입니다. 한 스팬의 상태 설정 순서·예외 이벤트·종료 시점을 비교합니다. 실제 고객 장애나 특정 관측 백엔드의 화면을 재현한 글은 아닙니다.
마지막 ERROR가 앞선 OK를 바꾸지 못하는 이유는 무엇입니까?#
OpenTelemetry Trace API의 상태에는 OK > ERROR > UNSET의 우선순위가 있습니다. OK를 최종 성공 판정으로 설정하면 이후 ERROR나 UNSET으로 바꾸려는 시도가 무시됩니다. Trace API의 상태 설정 규칙이 공식 근거입니다.
따라서 오류 표시가 남지 않으면 ERROR 호출의 유무와 함께 먼저 OK를 넣은 코드·계측 주체를 확인합니다. 자동 계측, 공통 래퍼, 업무 코드가 같은 스팬을 바꾸는지와 각 호출 시점을 대조해야 합니다.
재시도 전체와 개별 시도의 결과가 섞이는 문제는 OpenTelemetry 도구 재시도 스팬 검수를 먼저 봅니다. 이번 표는 재시도 범위를 바꾸지 않고 동일 SDK 스팬의 상태 호출을 비교합니다. 부모 관계가 다르면 자식 프로세스 추적 검수의 별도 질문으로 남깁니다.
호출 순서와 예외 기록에 따라 무엇이 저장됩니까?#
각 조건은 별도의 가상 synthetic-task 스팬입니다. Python의 API·SDK 1.45.2에서 호출한 뒤 메모리 exporter에 저장된 상태와 exception 이벤트 수를 읽었습니다. 사건 이름·예외 값은 합성 입력입니다.
| 가상 호출 조건 | 저장된 status | 예외 이벤트 |
|---|---|---|
| 설정 없음 | UNSET | exception 0개 |
| ERROR만 설정 | ERROR | exception 0개 |
| ERROR 뒤 UNSET | ERROR | exception 0개 |
| OK 뒤 ERROR | OK | exception 0개 |
| ERROR 뒤 OK | OK | exception 0개 |
| 예외 이벤트만 | UNSET | exception 1개 |
| OK 뒤 예외 이벤트 | OK | exception 1개 |
| 종료 뒤 ERROR | UNSET | exception 0개 |
‘OK 뒤 ERROR’의 최소 실행 코드는 아래와 같습니다. 이 예시는 오류 상태를 요청하는 API 호출을 비교하며 실제 업무가 실패했다는 증거로 사용하지 않습니다. 출력은 OK였습니다.
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.trace import Status, StatusCode
provider = TracerProvider()
tracer = provider.get_tracer("synthetic-status")
span = tracer.start_span("synthetic-task")
span.set_status(Status(StatusCode.OK))
span.set_status(Status(StatusCode.ERROR, "synthetic failure"))
span.end()
print(span.status.status_code.name) # OK
‘ERROR 뒤 UNSET’도 ERROR가 남았습니다. 초기 상태가 UNSET이라는 사실을 ‘나중에 UNSET으로 초기화할 수 있다’는 뜻으로 읽으면 안 됩니다. 종료 뒤 ERROR를 설정한 표본은 이미 저장된 UNSET 상태를 바꾸지 못했습니다.
예외 이벤트가 있으면 스팬도 ERROR가 됩니까?#
수동 record_exception 호출만으로 최종 상태가 ERROR가 되는 것은 아닙니다. 이번 표본은 예외 이벤트를 하나 기록해도 상태가 UNSET이었고, 먼저 OK를 설정한 경우에는 OK가 남았습니다.
반대로 ERROR만 설정한 표본에는 예외 이벤트가 없었습니다. 상태와 이벤트는 서로 다른 증거이므로 예외 이벤트 개수를 실패 요청 수로 바꾸어 집계하지 않습니다. 자동 계측이나 컨텍스트 매니저가 추가로 상태를 설정하는 동작은 적용 설정을 따로 확인해야 합니다.
처리한 오류를 성공한 스팬에 기록할지, 처리하지 못한 예외를 어떤 범위에 남길지는 오류 기록 규약에 맞춰 판단합니다. API 호출의 기계적인 결과와 업무의 최종 성공·실패 판정은 구분합니다.
개발자나 운영자가 성공을 검증한 뒤 OK로 확정하는 경우도 있습니다. OK 자체를 잘못된 값으로 취급할 필요는 없습니다. 성공이 확인되기 전에 공통 래퍼가 OK를 넣고 있지는 않은지, 그 판정을 뒤집으려는 코드가 왜 필요한지부터 검토합니다.
스팬 상태 인수표에 무엇을 남깁니까?#
스팬의 업무 범위, 상태를 바꾸는 주체, 호출 순서와 종료 시점, 저장된 status·예외 이벤트를 같은 표본으로 묶습니다. 화면에서 실패로 보이지 않는다면 SDK에 저장된 값과 전송·백엔드 처리 결과를 단계별로 대조합니다.
이 글은 2026-10-22 UTC 공개된 specification v1.62.0의 Stable Trace API와 2026-10-29 UTC 공개된 Python SDK v1.45.2를 확인했습니다. 오류 기록 규약은 2026-11-02 UTC 공개된 semantic-conventions v1.45.0의 Development 문서입니다. 사양 버전과 SDK 버전, 문서의 안정성 지위를 섞지 않습니다.
모든 원문 확인일은 2026-11-22입니다. 다음 검토는 2026-12-22 또는 API·SDK·계측 설정·백엔드 규칙 변경 시 진행합니다. 스팬 전송의 일부 거절은 OTLP 트레이스 부분 성공 검수에서 별도 다룹니다.
알파카랩스는 AX 구축·운영 서비스에서 운영 검수와 감사 리포트 등의 협의 범위를 설명합니다. 이는 자기표기이며 특정 SDK 기능의 납품 실적·고객 성과·운영 정확도 보장은 아닙니다. 운영 주체는 알파카랩스이며 아래 상담으로 연결될 수 있습니다.
OpenTelemetry 스팬 상태 검수 FAQ#
상태는 마지막 set_status 호출로 정해집니까?
상태 우선순위와 OK의 최종성이 적용됩니다. 이번 OK 다음 ERROR 호출은 OK를 바꾸지 못했으므로 호출 순서를 함께 확인해야 합니다.
UNSET은 오류가 없었다는 확정 증거입니까?
기본 상태이며 업무 성공 전체를 입증하지 않습니다. 상태 설정·예외 기록·스팬 범위·계측 누락과 업무 결과를 함께 대조해야 합니다.
record_exception을 호출하면 상태도 자동으로 바뀝니까?
이번 수동 SDK 호출에서는 이벤트만 추가됐습니다. 자동 계측이나 컨텍스트 매니저가 상태 변경을 함께 수행하는지는 해당 설정과 실행 표본으로 따로 확인합니다.
OK를 모두 없애야 합니까?
성공을 검증한 개발자·운영자의 확정 판정에는 사용할 수 있습니다. 계측 코드가 성공을 확인하기 전에 OK로 확정하는지와 오류 기록 규약을 대조해야 합니다.
SDK 표본이 맞으면 관측 화면의 실패 집계도 맞습니까?
이번 실행은 메모리에 저장한 상태와 이벤트만 확인했습니다. 샘플링·전송·Collector·백엔드 처리와 실제 업무 판정은 별도 인수 범위입니다.
스팬 상태 인수표 초안을 정리합니다#
스팬 상태 인수표 초안을 정리합니다
첫 범위 협의에서 비식별 상태 호출·스팬 범위·표시 규칙을 대조해 스팬 상태 인수표 초안을 정리합니다. 소요 시간은 SDK·계측 주체·관측 범위를 확인한 뒤 안내합니다.
스팬 상태 인수표 초안 협의