에이전트를 프로덕션에 올리면 무슨 일이 일어났는지 봐야 합니다. 여러 도구가 같은 것을 같은 이름으로 기록하도록 정해 둔 약속이 OpenTelemetry의 GenAI 시맨틱 규약입니다. 그런데 2026년 6월 12일 GenAI 항목 전체가 원래 저장소에서 “더 이상 권장하지 않음”으로 표시된 뒤 별도 저장소로 옮겨졌고, 새 저장소에는 오늘까지 릴리스 태그가 하나도 없습니다. 규약 정의 파일의 등급은 전부 개발 중(development)이고, OpenTelemetry 자신의 규정은 개발 중인 규격에 장기간 의존하지 않는 편이 좋다고 적고 있습니다.
계측은 프로그램이 실행되는 동안 무슨 일이 있었는지를 코드에서 기록으로 남기는 일입니다.
시맨틱 규약은 그 기록에 “같은 것을 같은 이름으로 쓰자”고 정해 둔 약속입니다.
토큰 사용량을 어느 도구에서든 gen_ai.usage.input_tokens로 부르기로 하면 관측 도구를 바꿔도
기존 기록을 계속 읽을 수 있습니다. 약속이 없으면 도구마다 이름이 달라 옮길 때 변환 작업이 붙습니다.
gen_ai.* 속성 수
OpenTelemetry의 시맨틱 규약은 open-telemetry/semantic-conventions 한 저장소에 모여 있었습니다.
GenAI 부분이 여기서 빠져나갔습니다. 아래에서 원래 저장소는 이곳을, 새 저장소는 옮겨 간 곳을 가리킵니다.
| 시점 | 일어난 일 |
|---|---|
| 2026-05-05 | open-telemetry/semantic-conventions-genai 저장소 개설 |
| 2026-06-12 | 원래 저장소 v1.42.0 릴리스 — gen_ai.* 속성·지표·이벤트·스팬이 전부 “더 이상 권장하지 않음”으로 표시되고 새 저장소로 이관 |
| 2026-08-04 | 원래 저장소 최신 릴리스 v1.44.0 |
| 2026-09-08 | 새 저장소의 릴리스 0개 · 태그 0개. 다만 커밋은 이날에도 들어옴 |
출처 · GitHub API로 두 저장소의 릴리스·태그 목록과 v1.42.0 릴리스 노트를 2026-09-08에 직접 조회.
v1.42.0 릴리스 노트의 문장은 이렇습니다 —
“All gen_ai.* attributes, metrics, events, and spans have been deprecated and moved to
the dedicated OpenTelemetry GenAI Semantic Conventions Repository”.
gen_ai.system, gen_ai.prompt, gen_ai.completion, gen_ai.usage.prompt_tokens는 이 이름 그대로는 현재 레지스트리에 없습니다(2026-09-08 확인). 비슷하지만 다른 키는 있습니다 — 예를 들어 gen_ai.prompt.name은 존재합니다. gen_ai.system의 자리는 gen_ai.provider.name이 대신하고 있습니다.
그리고 새 저장소에 태그가 없으므로 기준으로 고정할 공식 버전이 없습니다.
커밋 해시나 프레임워크 릴리스, 또는 날짜 스냅숏을 기준으로 삼는 수밖에 없습니다.
OpenTelemetry는 규격마다 성숙도 등급을 붙입니다. GenAI 규약의 정의 파일에는 속성 하나하나,
선택지 하나하나에 등급이 적혀 있는데 확인한 10개 파일의 등급이 전부 개발 중(development)이었습니다.
안정(stable)은 하나도 없었습니다.
다만 스팬에는 다른 저장소에서 온 속성도 섞여 쓰입니다 — 예를 들어 error.type은 본래 규약 쪽 속성이고 안정 등급입니다.
OpenTelemetry 스펙의 원문입니다.
“개발 중에는 호환을 깨는 변경과 성능 문제가 일어날 수 있다. 기능이 완성됐다고 기대해서는 안 된다. 경우에 따라 개발 중인 신호가 통째로 폐기되고 제거될 수도 있다. 개발 중인 신호에 장기 의존을 두지 않는 것이 좋다.”
여기서 신호는 OpenTelemetry가 트레이스·지표·로그처럼 관측 데이터의 종류를 부르는 말입니다.
원문은 SHOULD NOT으로, 금지가 아니라 강한 권고입니다.
“엄격한 검증을 거친 뒤에 stable로 전환될 수 있다. 이제 장기 의존을 걸어도 된다.”
즉 두 등급을 가르는 기준이 정확히 “믿고 오래 쓸 수 있는가”입니다.
출처 · OpenTelemetry 스펙 versioning-and-stability.md 원문. 인용은 한국어로 옮긴 것입니다.
확정되지 않았다고 해서 정의된 내용이 없는 것은 아닙니다. 속성의 이름과 의미를 모아 둔 목록(속성 레지스트리)에 72개가 정의돼 있고, 이 블로그가 따로 다뤘던 주제들도 항목으로 들어와 있습니다.
| 그룹 | 개수 | 무엇을 담나 |
|---|---|---|
gen_ai.request.* | 15 | 요청 파라미터 — 모델, 온도, 최대 토큰 등 |
gen_ai.usage.* | 14 | 토큰 사용량. 오디오·캐시 읽기 등으로 세분화 |
gen_ai.tool.* | 7 | 도구 호출 — 인자, 호출 ID, 결과 |
gen_ai.memory.* | 5 | 메모리 조회 — 질의문, 레코드 수·ID, 저장소 ID |
gen_ai.response.* | 5 | 응답 — 종료 이유, 응답 ID, 실제 모델명 |
gen_ai.agent.* | 4 | 에이전트 — 이름, ID, 설명, 버전 |
gen_ai.evaluation.* | 4 | 평가 — 평가 이름, 점수, 라벨, 설명 |
gen_ai.prompt.* | 3 | 프롬프트 — 이름, 버전, 변수 |
gen_ai.retrieval.* | 3 | 검색 — 질의문, 문서, top-k |
gen_ai.conversation.* | 2 | 대화 ID, 압축 여부 |
출처 · model/gen-ai/registry.yaml 원문에서 - key: 항목을 세었습니다. 표는 개수 상위 10개 그룹이며, 전체는 72개입니다.
스팬은 한 작업 구간을 나타내는 기록 단위입니다. 생성된 스팬 문서에는 여섯 종류의 스팬 표가 있습니다.
gen_ai.operation.name은 여섯 곳 모두에서 필수이고,
gen_ai.provider.name은 세 곳에서 필수, 두 곳에서 조건부입니다.
gen_ai.request.model은 값을 알 수 있을 때, error.type은 오류로 끝났을 때 기록하는 조건부이고,
나머지는 권장입니다.
gen_ai.operation.name이 가질 수 있는 값은 현재 18가지입니다. 모델 호출뿐 아니라
에이전트·도구·워크플로·메모리 작업까지 이 한 속성으로 구분합니다 —
chat, generate_content, text_completion, embeddings,
retrieval, fetch_response, create_agent, invoke_agent,
execute_tool, invoke_workflow, plan, 그리고 메모리 관련 일곱 가지.
model/mcp/ 아래에 별도 규약이 있어,
도구 호출 계층까지 같은 체계로 기록하도록 정리되는 중입니다. 물론 이쪽도 development입니다.
“굳을 때까지 기다리자”는 답이 되기 어렵습니다. 이 블로그가 앞서 다룬 것들이 전부 기록이 있어야 판단할 수 있는 문제이기 때문입니다.
| 앞서 다룬 문제 | 기록이 없으면 | 대응하는 속성 |
|---|---|---|
| 캐시가 실제로 적중하는가 | 절감이 났는지 알 수 없습니다 | gen_ai.usage.*의 캐시 읽기 항목 |
| 같은 단계를 반복하는가 | 반복이 눈에 띄지 않습니다 | gen_ai.operation.name + 대화 ID |
| 말한 것과 다르게 실행하는가 | 추론과 호출을 나란히 볼 수 없습니다 | gen_ai.tool.call.* (인자·결과는 Opt-In) |
| 평가 점수를 어디에 남기나 | 실행 기록과 점수가 따로 놉니다 | gen_ai.evaluation.* |
이 표의 연결은 규약 문서가 제시한 것이 아니라, 이 블로그의 앞선 글과 속성 이름을 맞춰 본 것입니다.
반대로 피할 것은 대시보드 질의문·알림 규칙·저장 스키마에 속성 이름을 그대로 박아 두는 것입니다. 그쪽은 고치기가 훨씬 번거롭고, 바뀐 줄도 모른 채 조용히 빈 그래프를 보게 됩니다.
| # | 할 일 | 왜 |
|---|---|---|
| 1 | 지금 내보내는 속성 이름이 폐기된 것인지 확인한다 | 2025년 예제를 보고 계측했다면 옮겨지기 전 이름일 수 있습니다 |
| 2 | 속성 이름을 정의하는 코드를 한 파일에 모은다 | 다음 이동 때 고칠 곳이 한 곳으로 줄어듭니다 |
| 3 | gen_ai.operation.name부터 넣는다 | 여섯 종류의 스팬 표 전부에서 필수인 유일한 속성입니다. gen_ai.provider.name도 대부분 필수이니 함께 넣으세요 |
| 4 | 토큰 사용량을 캐시 읽기까지 나눠 기록한다 | gen_ai.usage.*가 이미 그렇게 세분화돼 있습니다 |
| 5 | 도구 호출의 인자와 결과를 남길지 의식적으로 정한다 | 추론과 실행이 어긋나는 유형은 둘을 나란히 봐야 보입니다. 다만 이 둘은 규약에서 Opt-In이라 기본으로 켜지지 않고, 사용자 입력·개인정보·자격 증명이 그대로 들어갈 수 있습니다. 켤 거면 마스킹과 허용 목록을 함께 두세요 |
| 6 | 속성 이름을 대시보드 질의와 알림 규칙에 직접 박지 않는다 | 바뀌면 조용히 빈 그래프가 됩니다 |
| 7 | 새 저장소에 릴리스 태그가 생기는지 가끔 확인한다 | 태그가 생기는 시점이 버전을 고정할 수 있게 되는 시점입니다 |
model/ 아래 YAML 파일들에서 stability 선언을
세었고, 전부 development였습니다. 저장소의 다른 문서나 브랜치까지 훑은 것은 아닙니다.model/gen-ai/registry.yaml의
- key: 항목을 센 값이고, 벤더별 파일(openai·aws-bedrock)이나
MCP 쪽 속성은 여기에 포함하지 않았습니다.gen_ai.operation.name과 gen_ai.provider.name이 Required로 표시된 것을 확인했고, 스팬 종류마다 요구 수준이 다를 수 있는지까지 전수로 보지는 않았습니다.| 자료 | 이 글에서 쓴 내용 | 링크 |
|---|---|---|
| OpenTelemetry GenAI 시맨틱 규약 저장소 | 2026-05-05 개설, 릴리스·태그 0개(2026-09-08 조회), 모델 파일의 stability 전수, 속성 72개, gen_ai.operation.name 값 18가지, MCP 규약 포함 |
github.com/open-telemetry/semantic-conventions-genai |
| OpenTelemetry 시맨틱 규약 본 저장소 — v1.42.0 릴리스 노트 | gen_ai.* 전체의 폐기 표시와 이관, 시점 2026-06-12 |
github.com/open-telemetry/semantic-conventions — v1.42.0 |
| OpenTelemetry 스펙 — Versioning and stability | development·stable 등급의 정의. “장기 의존을 걸지 말라”는 문장 | opentelemetry-specification — versioning-and-stability.md |
저장소 상태는 GitHub API로, 규약 내용은 저장소의 YAML 원문으로, 등급 정의는 스펙 문서 원문으로 2026-09-08에 확인했습니다. 2차 정리 글은 인용하지 않았습니다. 이 영역은 몇 달 단위로 바뀌므로 계측을 시작하기 전에 저장소를 다시 확인하세요.