docs(observability): OTel GenAI semantic conventions 참조가 현행 스펙과 불일치

[balance-coding]

문서 두 편의 OpenTelemetry GenAI 시맨틱 규약 참조가 현행 업스트림과 어긋나 있어 정리를 제안드립니다.

배경

GenAI 시맨틱 규약이 open-telemetry/semantic-conventions에서 분리되어
open-telemetry/semantic-conventions-genai(2026-05-05 생성)로 이관됐고,
구 저장소의 gen_ai.* 속성은 전부 Deprecated 처리됐습니다. 이 과정에서 속성명 일부가 변경됐습니다.

확인된 불일치

1. docs/aidlc/operations/agentic-metrics.md §4.1 (KO 426-432 / EN 428-434)

문서가 사용하는 gen_ai.* 속성 7개를 업스트림 레지스트리와 전수 대조한 결과 2건 불일치입니다.

속성	업스트림	판정
gen_ai.system	부재 — gen_ai.provider.name으로 대체	수정 필요
gen_ai.response.finish_reason	부재 — gen_ai.response.finish_reasons (복수형, 배열)	수정 필요
gen_ai.request.model / .temperature / .max_tokens	존재	이상 없음
gen_ai.usage.input_tokens / .output_tokens	존재	이상 없음

OTel Python SDK의 생성 상수도 같은 내용을 명시합니다 —
gen_ai_attributes.py의
GEN_AI_SYSTEM 독스트링: "Deprecated: Replaced by gen_ai.provider.name, which has moved to the OpenTelemetry GenAI semantic conventions repository."

또한 §4.1 본문(KO 420)과 참고 자료(KO 723)가 v1.28.0을 인용하는데, 현재 semconv는 1.44.0입니다.
링크(opentelemetry.io/docs/specs/semconv/gen-ai/) 자체는 살아 있으나(HTTP 200) 버전 표기와 정본 위치 안내가 필요해 보입니다.

2. 같은 문서 §4.3 코드 블록 (KO 441-465 / EN 443-467)

"OTel → Langfuse 브리지" 예제가 현재 상태로는 실행되지 않습니다.

현재	실제
endpoint …/api/public/otlp	/api/public/otel (시그널별 경로는 /api/public/otel/v1/traces)
Authorization: Bearer <KEY>	Basic <base64(public_key:secret_key)>
opentelemetry.exporter.otlp.proto.grpc.trace_exporter	Langfuse OTLP는 HTTP이므로 proto.http

출처: https://langfuse.com/integrations/native/opentelemetry (2026-09-02 확인)

3. docs/agentic-ai-platform/operations-mlops/observability/llmops-observability.md §5.2 (257-263)

표 제목이 "OTel Semantic Conventions 매핑"인데 속성이 llm.model, llm.input_tokens, llm.temperature 등
llm.* 네임스페이스입니다. llm.*는 OpenTelemetry 규약이 아니라 OpenInference(Arize) 계열입니다.

추가로, Langfuse가 llm.*를 인식하기는 하지만 문서에 적힌 이름과 다릅니다
(llm.model → llm.model_name, llm.input_tokens/llm.output_tokens → llm.token_count.*,
llm.temperature → llm.invocation_parameters.*).

그 결과 agentic-metrics.md는 gen_ai.*, llmops-observability.md는 llm.*를 쓰고 있어
두 문서의 네임스페이스가 어긋나 있습니다.

재현

SHA=ac46a5d7bfe0b0f47e8ce393e2db3a2c3042f236
curl -sL "https://raw.githubusercontent.com/open-telemetry/semantic-conventions-genai/$SHA/docs/registry/attributes/gen-ai.md" \
  | grep -oE '`gen_ai\.[a-z_.]+`' | tr -d '`' | sort -u > /tmp/spec.txt
grep -rhoE 'gen_ai\.[a-z_.]+' docs/ | sort -u > /tmp/doc.txt
comm -23 /tmp/doc.txt /tmp/spec.txt

→ gen_ai.response.finish_reason, gen_ai.system 두 건이 출력됩니다.

제안

두 건으로 나눠 PR을 올릴 수 있습니다. EN 미러도 함께 수정하겠습니다.

PR 1: agentic-metrics.md 속성명·버전 표기·코드 블록 교정 (위 1·2번). 근거가 확정적이라 판단 여지가 없습니다.
PR 2: llmops-observability.md §5.2 표 (위 3번).

여쭙고 싶은 점

3번 표를 어떻게 정리하는 것이 의도에 맞을지 판단이 서지 않아 여쭙니다.

• 표를 gen_ai.* 기준으로 재작성하고 제목을 그에 맞게 수정
• 표 제목만 사실에 맞게 고치고(예: "Langfuse 속성 매핑"), llm.* 이름을 실제값으로 교정
• gen_ai.* 표와 llm.* 표를 분리해 병기

원래 llm.*를 선택하신 맥락이 있다면(특정 계측 라이브러리 전제 등) 알려주시면 그에 맞추겠습니다. 방향만 정해 주시면 PR로 올리겠습니다.