포스트

OpenTelemetry가 뭐고? 어캐 적용할긴데

OpenTelemetry가 뭐고? 어캐 적용할긴데

우리 서비스에서 “사용자 액션 하나에 LLM 호출이 몇 번 일어났는가”를 보여주어야 했다. 이를 위해 trace 관련 표준과 다른 LLM 게이트웨이들의 방식을 조사하여 우리 시스템에 어떤 방식으로 반영해야할지 방향을 잡고자 한다!


1. OpenTelemetry란

OpenTelemetry(OTel)는 애플리케이션이 텔레메트리를 만들고 내보내는 방식을 정한 벤더 중립 규격이다. 여기서 다루는 텔레메트리는 trace, metric, log 세 가지다.

왜 필요했는데?

OTel 이전에는 계측 코드가 벤더 SDK에 묶여 있었다. 예를 들어 Datadog SDK로 계측해 둔 코드를 Jaeger로 옮기려면? 계측을 전부 다시 짜야 했다.

그래서 OTel은 계측과 백엔드를 떼어놓는 것부터 시작한다.

  • 계측 코드는 벤더 SDK가 아니라 OTel API에만 의존한다. 직접 호출하든 자동 계측 라이브러리를 쓰든 마찬가지다.
  • 데이터를 어디로 보낼지는 애플리케이션 시작 시점의 SDK와 exporter 설정(또는 Collector)에서 따로 정해준다.
  • 그래서 백엔드를 바꿔도 계측 코드는 그대로 활용할 수 있는 것이다.

OTel의 구성 요소

구성 요소역할
API계측 코드가 호출하는 인터페이스. tracer.startSpan()
SDKAPI의 구현체로, 샘플링, 배칭, 내보내기를 처리함
Data Modelspan, metric, log의 데이터 구조
OTLP데이터를 보내는 전송 프로토콜 (protobuf over gRPC/HTTP)
Semantic Conventionsattribute 이름 규약. http.request.method, gen_ai.request.model

덕분에 라이브러리 개발자는 OTel API만 보고 계측 코드를 미리 넣어둘 수 있다. 애플리케이션에 SDK가 없으면 이 코드는 아무 일도 하지 않으니 손해 볼 게 없고,  애플리케이션이 SDK를 붙이는 시점부터 데이터가 실제로 쌓이기 시작한다!

그래서 “OTel을 쓴다”는 말도 사람마다 가리키는 게 다른데, 누구는 OTel SDK로 계측했다는 뜻으로, 누구는 데이터를 OTLP로 보낸다는 뜻으로, 또 누구는 gen_ai 같은 이름 규약을 따른다는 뜻으로 말한다. 셋 다 OTel을 쓰는 건 맞지만 OTel 자체의 범위가 넓은 만큼 사용 방식이 서로 다를 수 있다.

세 가지 시그널

 TraceMetricLog
용도어느 구간이 느렸는지, 누가 누구를 호출했는지 추적요청 수, 지연 같은 수치의 추이 확인특정 시점에 발생한 이벤트 기록
데이터 형태요청 하나의 흐름 (span 트리)일정 기간 동안 집계한 수치개별 이벤트 한 건
예시POST /chat 1.2s 아래 LLM 호출 1.1s분당 요청 수, p95 지연, 토큰 합계ERROR provider timeout

세 시그널은 같은 출처 정보(service.name 등)와 같은 attribute 이름 규약(gen_ai.request.model 등)을 공유한다.

특히 Log에는 trace_id, span_id 필드가 있어서, span 안에서 찍은 로그는 자연스럽게 해당 trace에 연결되는 구조이다.

반면 Metric은 여러 요청을 합친 집계 데이터라 trace_id가 따로 없고, exemplar라는 기능으로 대표 trace 몇 개를 샘플처럼 가리킬 수 있는 정도긴 하다.


2. W3C Trace Context와 trace_id

사용하려던 trace_id는 OTel이 정한게 아니었다.

서비스 사이에 “이 요청이 어느 trace의 어느 span에서 왔는가”를 넘기는 형식은 사실 OTel이 아니라 W3C Trace Context라는 웹 표준이 정한 것이었다. 이건 구현체가 아니라 헤더 이름과 값의 형식만 정해둔 스펙이고, OTel은 이걸 기본 전파 방식으로 가져다 쓴 것뿐이다. 그래서 ID를 만들어 다음 서비스로 넘기는 것 자체를 OTel이라고 볼 수는 없고, 실제로 OTel 없이도 같은 형식의 헤더를 얼마든지 만들 수 있다.

이 표준이 생기기 전에는 Zipkin(X-B3-TraceId), AWS(X-Amzn-Trace-Id), Datadog(x-datadog-trace-id)이 저마다 다른 헤더를 썼기에, 중간에 다른 벤더의 서비스가 하나라도 끼면 trace가 거기서 끊기는 문제가 발생했다고 한다.

traceparent 헤더

1
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
필드예시 값설명
version00traceparent 헤더 형식의 버전. 현재 스펙에는 00만 정의돼 있다 (ff는 무효)
trace-id4bf92f35…0e4736 (32자)요청 전체를 식별하는 ID (모두 0이면 무효)
parent-id00f067aa…a902b7 (16자)요청을 보낸 쪽의 span ID
flags01샘플링 여부. 01이면 보낸 쪽이 기록, 00이면 기록하지 않는다는 flag 값

요청을 받은 쪽은 trace-id는 그대로 물려받고, parent-id는 자기 span의 부모로 삼는 식이다. 그리고 다음 서비스로 넘길 때는 parent-id 자리만 자기 span ID로 바꿔서 보낸다.

구간보내는 traceparent받는 쪽 span의 부모
A → B00-T-a1-01a1
B → C00-T-b1-01b1

결국 같은 trace 안의 요청들은 trace-id는 모두 같고, parent-id만 서로 다른 것이다.

trace_id와 span_id

 trace_idspan_id
범위요청 전체 (트리 전체)요청 안의 개별 구간 (트리의 노드)
크기16바이트8바이트
전파 방식다음 서비스에 그대로 전달구간마다 새로 생성

정리하면 trace_id는 “같은 묶음인가”를, span_id와 부모 span_id는 “그 묶음 안에서 누가 누구를 불렀나”를 알려주는 셈이다.

참고로 traceparent 말고도, 벤더별 추가 정보를 싣는 tracestate와 trace 전체에 따라다녀야 하는 도메인 값을 싣는 baggage 헤더도 W3C 표준에 포함돼 있다고 한다.


3. 데이터 구조

Span

그럼 실제로 OTel Data Model에서 Span은 어떻게 생겼을까?

1
2
3
4
5
6
7
8
9
10
11
message Span {
  bytes  trace_id = 1;              // 16바이트
  bytes  span_id  = 2;              // 8바이트
  bytes  parent_span_id = 4;        // 트리를 만드는 필드
  string name = 5;
  fixed64 start_time_unix_nano = 7;
  fixed64 end_time_unix_nano   = 8;
  repeated KeyValue attributes = 9;
  repeated Event    events = 11;
  repeated Link     links  = 13;
}
  • start_time / end_time: 한 시점이 아니라 구간을 담아서 어디서 시간이 걸렸는지 바로 관측할 수 있는 구조이다.
  • parent_span_id: 누가 누구를 불렀는지가 데이터 안에 들어 있다. 이런 Span들이 모이면 트리가 되고, 그 트리 전체가 하나의 Trace와 대응된다고 생각하면 된다.
  • attributes: span에 붙이는 key-value 영역이다. 사용자 ID나 주문 번호 같은 서비스 고유의 값은 여기에 넣는다.
  • links: 부모-자식 관계가 아닌, 다른 trace와의 연결을 남길 때 사용한다.

전체 트리를 그리려면 부모 span이 필요해

trace_id가 같다는 것만으로는 같은 묶음이라는 사실까지만 알 수 있다. 누가 누구를 불렀는지까지 그리려면 각 span의 부모 span이 같은 저장소에 함께 있어야 하는데, 바로 이 차이 때문에 4장에서 볼 게이트웨이들의 방식이 갈린다.

LLM용 attribute 규약은 아직 정답이 없다..

LLM 호출에 어떤 attribute 이름을 붙일지는 아직 표준이 하나로 정해지지 않았다고 한다. Arize가 주도하는 OpenInference와 OTel 커뮤니티의 GenAI 규약(gen_ai.*)이 경쟁 중이고, 한쪽 이름으로 찍은 trace가 다른 쪽 이름으로 자동 번역되지도 않는 시기이기에, 정답은 없는 것 같다.


4. 상용 LLM 게이트웨이의 trace 활용 방식

먼저 Langfuse, Arize Phoenix 같은 Observability 백엔드는 대부분 OTLP 수집을 지원한다. 적어도 데이터를 보내는 방식은 OTel로 모이고 있다고 정리해도 될 것 같다.

그런데 게이트웨이는 사정이 좀 다르다. 게이트웨이가 볼 수 있는 건 자기한테 들어온 HTTP 요청 하나뿐이고, 고객 애플리케이션 안에서 만들어진 span(에이전트 노드 등)은 볼 수 없다. 그래서 처음에 내가 생각한 것 처럼 trace_id만 보고 호출 트리를 거꾸로 만들어내는 곳은 없고, 대신 아래 세 가지 방식으로 나뉜다고 한다.

방식벤더사용하는 헤더·데이터제공 기능
같은 ID로 묶기LiteLLMx-litellm-session-id, x-litellm-trace-idSession Logs 화면에서 요청 묶어 보기
 Cloudflare AI Gatewaycf-aig-metadata 태그 (최대 5개)로그 검색, 필터
고객이 구조를 직접 전달HeliconeHelicone-Session-Id + Helicone-Session-Path (/research/search)경로 기반 호출 트리
 Portkeytrace id, span id, parent span id 헤더. traceparent도 받아서 매핑span 트리 (고객 span을 OTLP로도 수집)
OTel span 내보내기Kong AI GatewayOTel 플러그인, gen_ai.* attribute고객의 트레이싱 백엔드에서 트리 구성
 LiteLLM (otel 콜백)수신한 traceparent에 span을 연결고객의 Langfuse 등에서 트리 구성

참고로 LangSmith는 게이트웨이가 아니라 LangChain/LangGraph 콜백을 통해 프로세스 안에서 노드를 직접 보는 형태이기에, 따로 역산할 필요 없이 처음부터 트리가 나온다. 호출하는곳-관측하는곳을 둘 다 지원하니 얻는 혜택인 것 같다.

결국 게이트웨이가 고를 수 있는 건 세 가지로 정리되는데, 같은 ID로 묶기만 하거나, 고객이 헤더로 구조를 직접 전달하게 하거나, 고객 쪽 백엔드로 span을 넘겨서 거기서 트리를 구성하게 하는 것.


5. 우리 시스템엔 어떻게 적용해야할까?

현재 상태

  • SDK: 고객이 액션 진입점을 우리 SDK의 context로 감싸고 traceId를 지정하면, 그 안에서 일어나는 모든 LLM 호출에 W3C 형식의 traceparent가 붙는다. OTel 라이브러리를 쓰는 건 아니고 헤더 형식만 맞춘 상태이고, 고객 앱이 이미 OTel로 traceparent를 보내고 있다면 그 값을 덮어쓰지 않고 그대로 둔다.
  • Gateway: traceparent를 받기는 하지만, 아직 trace-id를 분석 데이터에 남기지는 않는다. 그래서 지금은 고객이 trace_id를 붙여 보내도 액션 단위로 묶어서 볼 방법이 없다.

반영 방향

1. 먼저 trace-id를 분석 이벤트에 저장하자. 들어온 traceparent가 올바른 값인지(32자리 hex이고, 전부 0이 아닌지) 확인한 뒤 trace-id만 꺼내서 call 이벤트에 저장한다. 우리 SDK가 만든 값이든 고객 OTel이 만든 값이든 형식은 W3C를 따르니까 묶는데는 상관이 없다. 호출 수를 정확히 세야 하므로, 샘플링 없이 모든 요청이 쌓이는 call 이벤트에 두는 게 맞다.

2. feature_id와 trace-id 두 기준으로 보여주자.

기준파악할 수 있는 정보
feature_id여러 호출부가 같은 기능에 속하는지
trace-id여러 호출이 같은 액션에서 나왔는지, 한 액션에서 호출이 몇 번 어떤 순서로 일어났는지, 액션 전체의 토큰과 비용, 지연 시간 등 여러 호출을 묶는 기준값

3. 한계는 문서에 분명히 적어두자.

  • “하나의 유저 액션”의 범위는 trace를 만든 쪽이 정한다는 걸 명시해야 한다. 우리 SDK의 traceId를 쓰면 고객이 감싼 블록이 하나의 액션 범위가 될 것이고, 고객 OTel을 쓰면 고객의 루트 span이 하나의 액션이 될 것이기에, trace 설정이 정의한 곳에 따라 달라질 수 있음을 클라이언트에게 알려야만 혼동이 덜할 것이라 생각한다. (게이트웨이 규약도 Docs에 투명하게 공개한 것 처럼)
  • 액션당 호출이 몇 번인지는 알 수 있지만, 어떤 단계를 거쳤는지나 인과 관계(A의 결과를 B가 썼는지)까지는 알 수 없다. 이건 추가적인 기능이라고 판단함.

나중에 추가적으로 해야할 것

나중에 트리까지 보고 싶다는 요구가 생기면, Helicone 방식이 가장 적은 비용으로 할 수 있는 방향 같다. 고객이 경로 헤더(/planner/search)를 보내주고 Gateway는 그걸 저장만 하는 형식인데, 물론 이것도 클라이언트에게 위임하는 방식이라 거부감이 드는 건 사실이다.. Portkey처럼 고객 span을 OTLP로 받아서 트리를 직접 구성하는 건 A/B 테스트라는 우리 서비스의 핵심과는 거리가 있어서 일단 미뤄둬야 할 것 같다.


마치며

다수의 서버에서 텔레메트리를 찍는 것에 업계가 어떤 표준을 지향하는지 알아볼 수 있었다. W3C 구조만 봐도 알 수 있듯이, 호출부를 트리 구조에 따라 확인할 수 있어야 확실한 트래킹이 가능하다고 느껴졌다.

다만 이조차도 완전히 하나로 통일된 것은 아니기에, 우리 서비스 적용에 있어 확장이 가능하도록 고민을 추가적으로 하고 적용을 해야할 것 같다.

이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.