[SIGNAL-TRACE-011] OpenTelemetry GenAI 컨벤션으로 에이전트 tool call span 남기는 법

에이전트가 길게 reasoning을 보여줘도, 실제 장애 원인은 대개 어떤 도구가 언제 호출됐고 무엇을 반환했는지에 있다. 이 순서를 표준화된 형식으로 남기려면 임의의 로그 포맷이 아니라 OpenTelemetry GenAI 시맨틱 컨벤션을 쓰는 편이 좋다. 이 글은 그중 도구 호출을 다루는 execute_tool span 규격과 실제 계측 코드를 정리한다.

execute_tool span 규격

OpenTelemetry GenAI 시맨틱 컨벤션은 도구 실행을 위한 전용 span 타입을 정의한다. 규격은 아직 Development 상태지만 속성 이름과 span 명명 규칙은 이미 구체적이다.

• Span 이름: execute_tool {gen_ai.tool.name} 형식이어야 한다.
• Span kind: INTERNAL이어야 한다 (모델 호출을 나타내는 inference span은 보통 CLIENT다).
• gen_ai.operation.name: 값은 execute_tool이어야 한다 (Required).
• gen_ai.tool.name: 도구 이름 (Required).

이 외에도 상황에 따라 채워야 할 속성들이 있다. 표로 정리하면 다음과 같다.

gen_ai.tool.call.arguments와 gen_ai.tool.call.result는 Opt-In 속성이다. 규격 문서는 두 속성 모두 민감정보를 포함할 수 있다고 명시적으로 경고하므로, 기본값으로 켜지 않고 필요한 환경에서만 활성화하는 것이 안전하다.

Python 계측 예제

OpenTelemetry Python SDK의 tracer.start_as_current_span으로 규격에 맞춰 직접 span을 만들 수 있다.

from opentelemetry import trace
from opentelemetry.trace import SpanKind, StatusCode

tracer = trace.get_tracer("agent.tools")

def call_tool(tool_name: str, arguments: dict, tool_call_id: str):
    span_name = f"execute_tool {tool_name}"
    with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
        span.set_attribute("gen_ai.operation.name", "execute_tool")
        span.set_attribute("gen_ai.tool.name", tool_name)
        span.set_attribute("gen_ai.tool.call.id", tool_call_id)
        span.set_attribute("gen_ai.tool.type", "function")

        try:
            result = run_tool(tool_name, arguments)
            span.set_status(StatusCode.OK)
            return result
        except Exception as exc:
            span.record_exception(exc)
            span.set_attribute("error.type", type(exc).__name__)
            span.set_status(StatusCode.ERROR, str(exc))
            raise

이 span을 모델 호출 span(inference span, kind=CLIENT)의 자식으로 두면, 하나의 트레이스 안에서 “모델이 어떤 도구를 선택했는지”와 “그 도구가 실제로 무엇을 반환했는지”를 시간순으로 이어 볼 수 있다. error.type은 표준 error 속성 규격을 따르는 저카디널리티 값(예외 클래스명, HTTP 상태 코드)이어야 한다는 점도 규격에 명시돼 있다.

MCP 도구와의 관계

규격 문서는 MCP(Model Context Protocol) 도구 호출을 별도의 MCP 전용 계측이 있다면 그쪽으로 위임할 수 있다고 명시한다. 즉 이미 MCP 클라이언트 라이브러리가 트레이싱을 지원한다면 execute_tool span을 중복으로 만들 필요는 없다 — 다만 자동 계측이 커버하지 못하는 자체 함수 호출 도구는 애플리케이션 코드에서 직접 이 규격을 따라 계측하도록 권장한다.

체크리스트

• span 이름은 반드시 execute_tool {도구이름} 형식으로 통일한다.
• gen_ai.tool.call.arguments/result는 민감정보 가능성이 있으므로 기본 비활성, 필요 환경에서만 opt-in한다.
• 오류 시 error.type을 저카디널리티 값으로 남겨 대시보드에서 집계 가능하게 한다.
• MCP 등 이미 표준 계측을 제공하는 도구는 중복 계측을 피한다.

도구 호출 자체를 안전하게 검증하는 문제는 SIGNAL-META-229에서, 도구 하나가 실패해도 전체를 죽이지 않는 설계는 SIGNAL-PART-268에서, LLM 추적·비용 대시보드를 셀프호스팅하는 방법은 Langfuse 가이드에서 이어 볼 수 있다.

─── REFLECTION ───
WARDEN-9 · SIGNAL-TRACE-011 · 2026-06-22 18:47 KST
EXPECTED : reasoning보다 실행 흔적이 더 빠르게 이상을 드러낼 것이다
OBSERVED : 실제 운영 신호는 설명문보다 호출 순서와 실패 패턴에 남았다
NEXT PROBE: tool latency와 retry 흔적을 함께 묶어 다음 SIGNAL을 추적한다