OpenTelemetry v2로 마이그레이션

OpenTelemetry v2로 마이그레이션 (Migrating to OpenTelemetry v2)

OpenTelemetry v2는 LiteLLM 트레이싱의 재작성(re-write)이에요. HTTP 서버 스팬은 LiteLLM이 아니라 표준 FastAPI 계측이 소유하고, 스팬 모델은 타입화되며, 벤더 속성 어휘는 매퍼 체인(mapper chain)을 통해 합성돼요. 이 가이드는 v1 OpenTelemetry 통합에서 v2로 이동할 때 무엇이 바뀌는지, 그리고 기존 대시보드를 깨뜨리지 않고 마이그레이션하는 방법을 다뤄요.

출처: 문서

본문

켜기 (Turn it on)

피처 플래그를 설정하고 프록시를 재시작해요:

LITELLM_OTEL_V2=true

기존 OTEL_* 환경 변수와 콜백은 계속 작동하므로, 많은 설정에서 이것만 바꾸면 돼요. 이 플래그는 시작 시 한 번만 읽혀요.

무엇이 바뀌나요 (What changes)

차이점은 모두 소리 없이 지나가지 않아요. 각각은 대시보드에서 검색할 수 있는 것이므로, 그것에 의존하는 쿼리를 마이그레이션하세요.

루트 스팬 이름 (The root span name)

v1 로거는 루트 스팬을 직접 만들고 Received Proxy Server Request라고 이름을 붙여요. v2는 FastAPI 계측이 루트 스팬을 소유하게 하며, 루트 스팬은 라우트에 따라 이름이 붙고(예: POST /v1/chat/completions) http.route를 스탬프해요. 리터럴 Received Proxy Server Request로 필터링하는 저장된 쿼리나 알림은 라우트 이름이나 http.route로 옮겨야 해요.

가드레일 스팬 이동 (The guardrail span moves)

v1에서 가드레일 스팬은 litellm_request 스팬의 자식이에요. v2에서는 LLM 호출 전 가드레일이 LLM 호출이 존재하기 전에 실행되므로, 가드레일 스팬은 LLM 호출 스팬의 형제로 요청 루트 바로 아래에 위치해요. 인퍼런스 스팬에서 아래로 내려가 가드레일 스팬을 찾는 쿼리는 요청 루트를 가리키도록 다시 지정해야 해요.

인퍼런스 스팬 이름과 종류 (The inference span name and kind)

v1은 기본적으로 인퍼런스 스팬 이름을 litellm_request로 짓고, 실험적 시맨틱 규칙을 선택했을 때만 {operation} {model}로 짓지만, v2는 항상 {operation} {model}로 짓고(예: chat gpt-5.6-terra) 스팬 종류는 CLIENT예요.

벤더 선택 (Vendor selection)

v1은 속성 코드의 분기를 통해 콜백 이름에서 벤더 속성 종류를 골라요. v2는 매퍼 체인을 통해 어휘를 합성해요. 표준 genai 매퍼는 항상 있고, 프리셋이 그 위에 벤더 매퍼를 추가해요. 프리셋 콜백을 구성하는 것은 여전히 벤더를 선택하는 방법이지만, 내부 메커니즘은 바뀌었고 이제 하나의 스팬에 여러 어휘를 계층화할 수 있어요.

아이덴티티 스탬핑 (Identity stamping)

v1은 각 스팬에 명시적인 스팬별 코드로 팀과 키 아이덴티티를 스탬프해요. v2는 소수의 아이덴티티 값을 한 번 OpenTelemetry Baggage로 승격시키고, 스팬 프로세서가 그것들을 모든 스팬에 복사해요. 결과 키(litellm.team.id, litellm.api_key.hash 등)가 같은 개념이므로 보통 대시보드에는 보이지 않는 차이지만, 이제 집합이 명시적이고 구성 가능한 allowlist라는 점이 달라요. Identity baggage 참조.

성공 상태 (Success status)

v1은 성공한 스팬의 상태를 OK로 설정해요. v2는 시맨틱 규칙 기본값인 UNSET으로 두고(FastAPI 서버 스팬과 일치), 진짜 오류일 때만 ERROR로 설정해요. status OK에 키잉된 알림은 오류가 아닌 스팬을 세도록 전환해야 해요.

전환 기간 동안 이전 속성 이름 유지 (Keep the old attribute names during the cutover)

v2는 기본적으로 켜진 레거시 호환 매퍼(LITELLM_OTEL_LEGACY_COMPAT=true)와 함께 제공되며, 이 매퍼는 표준 키와 함께 더 오래된 Traceloop 키 이름(gen_ai.system, gen_ai.usage.prompt_tokens, gen_ai.usage.completion_tokens, llm.is_streaming 등)으로 동일한 데이터를 내보내요. 이것이 점진적 마이그레이션을 가능하게 해요. v2를 켜면 이전 토큰 수와 프로바이더 키를 읽는 대시보드가 계속 작동해요. 각 쿼리를 표준 gen_ai.* 키로 원하는 속도로 마이그레이션한 다음 LITELLM_OTEL_LEGACY_COMPAT=false로 설정해 중복을 제거하면 돼요.

안전한 롤아웃 (A safe rollout)

  1. legacy_compat를 켠 상태(기본값)로 LITELLM_OTEL_V2=true를 사용해 v2를 스테이징에서 활성화해요.
  2. 트레이스가 도착하고 트리가 올바른지 확인해요. 요청당 서버 스팬 하나, 그 아래 LLM 호출 스팬, 가드레일은 형제로.
  3. 바뀐 스팬 이름과 성공 상태 변경에 맞게 대시보드와 알림을 업데이트해요.
  4. 속성 쿼리를 레거시 키 이름에서 표준 gen_ai.* 키로 마이그레이션해요.
  5. LITELLM_OTEL_LEGACY_COMPAT=false를 설정하고 아무것도 깨지지 않는지 확인해요.
  6. 프로덕션에 롤아웃해요.

롤백 (Rolling back)

LITELLM_OTEL_V2=false로 설정하고(또는 설정 해제) 재시작해요. LiteLLM은 이미 구성해 둔 동일한 OTEL_* 변수와 콜백을 사용해 v1 로거로 폴백하므로, 롤백에 다른 변경이 필요 없어요.

더 알아보기 (Learn more)