OpenTelemetry 도구 스팬 검수, 재시도에 성공하면 오류는 어디에 남길까
OpenTelemetry에서 AI 도구의 개별 시도와 재시도까지 감싼 전체 호출을 구분합니다. 가상 트레이스와 인수표로 최종 오류 상태, 관측 누락, 원문 수집 범위를 확인합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
2026년 11월 기준, 도구가 재시도 끝에 성공하면 전체 스팬은 Unset으로 둡니다. 실패는 따로 기록한 시도 스팬에서 확인합니다.
AI가 사내 재고 조회 도구를 호출한 가상 상황입니다. 첫 조회는 시간 초과였지만 다음 조회에서 값을 받았습니다. 모니터링 화면에서 도구 호출 전체가 실패로 집계된다면, 실제로 오류가 난 시도와 재시도까지 끝난 호출을 같은 범위로 기록했는지부터 확인합니다.
재시도에 성공하면 어떤 스팬에 오류를 남기나요?#
오류로 끝난 개별 시도를 별도 스팬으로 수집한다면 그 스팬에 오류를 남깁니다. 재시도를 포함한 전체 도구 호출이 정상 종료했다면 전체 스팬 상태는 Unset으로 두고 error.type을 붙이지 않습니다. 모든 시도가 실패해 호출도 오류로 끝났다면 전체 스팬도 실패로 분류합니다. OpenTelemetry 오류 기록 규칙
OpenTelemetry에서 스팬은 계측한 작업의 시작과 끝을 담는 추적 단위입니다. GenAI 규약은 자동 재시도에 걸린 시간까지 호출자의 논리 작업 스팬에 포함하도록 권고합니다. 도구 호출의 이름 예시는 execute_tool 뒤에 도구명을 붙이는 방식입니다. 아래 예시에서 개별 시도용 자식 스팬 이름은 인수 검수를 위해 정한 이름입니다. GenAI 스팬 범위 원문 · 도구 실행 규약
인수 때 어떤 입력과 상태를 대조하나요?#
같은 읽기 도구에 정상과 실패를 주입하고, 전체 호출과 각 시도의 종료 상태를 따로 기록합니다. 전체 호출의 종료 결과와 상태가 일치하는지, 실패한 시도의 흔적을 그 아래에서 찾을 수 있는지를 함께 봅니다. 아래는 첫 시도에 시간 초과를 넣고 다음 시도에 정상 값을 돌려준 가상 기록입니다.
execute_tool inventory_lookup
gen_ai.operation.name = execute_tool
gen_ai.tool.name = inventory_lookup
전체 상태 = Unset
error.type 없음
inventory.read.attempt (첫 시도)
상태 = Error
error.type = TimeoutError
inventory.read.attempt (다음 시도)
상태 = Unset
error.type 없음| 가상 입력 또는 계측 관측 | 개별 시도에서 기대하는 값 | 전체 호출에서 기대하는 값 |
|---|---|---|
| 첫 시도에서 조회 성공 | Unset | Unset, error.type 없음 |
| 첫 시간 초과 뒤 조회 성공 | 첫 시도 Error, 다음 시도 Unset | Unset, 첫 시도의 오류 유형을 복사하지 않음 |
| 마지막 시도까지 시간 초과 | 실패한 시도 각각 Error | Error와 종료 오류 유형 |
| 요청 범위 안에서 정상적으로 빈 목록 반환 | Unset | Unset, 업무 결과는 빈 목록으로 따로 확인 |
| HTTP 200의 본문 전송은 정상, 본문은 도구 계약상 실패, 재시도 없음 | HTTP 계측에 추가 오류 정보가 없으면 HTTP 스팬 Unset, 도구 시도 Error | Error와 종료 오류 유형 |
| 실패를 주입했으나 시도 스팬이 수집 화면에 없음 | 관측 불가, 계측·샘플링·수집 확인 | 호출 결과는 별도 대조, 인수에서는 관측 누락으로 기록 |
HTTP 표본에서 일반 HTTP 계측은 본문에 담긴 도구 계약을 해석하지 않는다고 가정합니다. 200 응답과 본문 수신까지 정상이면 이 범위의 HTTP 스팬은 Unset으로 두고, 본문을 해석하는 도구 스팬에서는 오류를 기록합니다. OpenTelemetry HTTP 스팬 상태 규칙
인수 기록에는 실제 도구의 최종 응답, 전체 스팬과 시도의 연결 관계, 실패 시 종료 오류 유형을 대조한 결과를 남깁니다. 조회 인수와 결과 원문은 기본 수집에서 빼고, 오류 유형은 TimeoutError처럼 종류를 제한한 식별자로 기록합니다. GenAI 규약에서도 도구의 인수와 결과 본문 수집은 명시적으로 선택하는 항목입니다. 도구 인수·결과 수집 규약
시도마다 새 스팬을 꼭 만들어야 하나요?#
기존 DB나 HTTP 스팬으로 시도와 호출 관계를 확인할 수 있다면 그 기록을 활용할 수 있습니다. 먼저 실제 SDK가 스팬 하나를 어느 범위에 붙이는지 확인합니다. 인수 표본에서는 실패를 주입한 시도와 전체 도구 결과를 각각 확인할 수 있을 만큼만 계측 범위를 정합니다.
표본에서 스팬이 보이지 않으면 샘플링·계측·전송 설정을 확인하고 동일 입력을 재현합니다. 이 표는 읽기 도구의 계측 검수에 적용합니다. 발주나 출고처럼 상태를 바꾸는 작업은 재시도 가능 여부와 원장 반영을 별도 인수 조건으로 둡니다.
장기 추적에는 AI 감사 로그의 증거 보존 기준, 응답 내용에는 MCP 구조화 결과와 설명 대조, 업무 변경에는 AI 에이전트의 ERP 원장 반영 검수를 적용할 수 있습니다.
근거와 확인일#
OpenTelemetry 일반 오류 기록은 2026년 11월 2일 UTC에 공개된 Semantic Conventions v1.45.0에서 확인했습니다. GenAI 도구 규약은 분리 저장소의 2026년 11월 6일 커밋 시점을 기준으로 읽었습니다. 일반 오류 기록과 GenAI 도구 규약은 Development, HTTP 스팬 상태 규칙은 Stable로 표시됩니다. 모두 2026년 11월 8일에 확인했습니다. 설치한 SDK의 계측 범위는 인수 환경에서 별도로 대조합니다. v1.45.0 릴리스 · GenAI 규약 이동 안내
알파카랩스는 출처와 권한을 지키는 AI·MCP 조회와 운영 인수 조건을 협의하는 범위를 공개합니다. 2026년 11월 8일 확인한 자사 서비스 설명입니다. 온톨로지 구축·컨설팅 서비스
OpenTelemetry 도구 스팬 검수 FAQ#
재시도 끝에 성공한 전체 스팬을 Ok로 표시하나요?
이 글의 오류 기록 기준에서는 성공한 전체 스팬 상태를 Unset으로 두고 error.type을 남기지 않습니다. 실패한 시도는 별도로 수집한 시도 스팬에서 확인합니다.
모든 시도가 실패하면 최초 오류를 전체 스팬에 남기나요?
전체 작업을 종료시킨 오류 유형을 전체 스팬에 기록합니다. 먼저 발생한 오류나 다른 시도의 오류는 각각의 시도 스팬에서 확인합니다.
HTTP 200이면 도구 스팬도 정상인가요?
HTTP 200의 본문까지 정상 수신했고 HTTP 계측에 다른 오류 정보가 없다면 HTTP 스팬은 Unset입니다. 도구 계약이 본문을 실패로 해석하고 호출도 오류로 끝났다면 전체 도구 스팬은 Error와 종료 오류 유형을 기록합니다.
도구 스팬에 요청과 결과 원문이 필요한가요?
이 인수표는 스팬의 연결 관계와 상태, 분류한 오류 유형으로 대조합니다. 원문을 수집해야 하는 별도 용도가 있으면 허용 범위와 열람 권한을 정하고 수집을 선택합니다.
실패한 시도 스팬이 보이지 않으면 어디를 확인하나요?
계측 적용 범위와 샘플링·전송 여부를 먼저 확인합니다. 통제한 표본의 요청 기록과 최종 응답을 대조하고, 설명할 수 없는 누락은 관측 실패로 기록합니다.
도구 스팬 인수표 초안 협의#
첫 범위 협의에서 비식별 트레이스와 가상 실패 표본으로 스팬 범위·최종 상태·누락 확인 기준을 초안에 정리합니다. 소요 시간은 자료와 검수 범위를 확인한 뒤 협의합니다.
개별 시도와 전체 도구 호출을 대조합니다
첫 범위 협의에서 비식별 트레이스로 스팬 범위와 오류 판정 기준을 정리합니다. 소요 시간은 자료와 검수 범위를 확인한 뒤 협의합니다.
도구 스팬 인수표 초안 협의