Langtrace

Langtrace

Langtrace는 LLM 애플리케이션을 위한 오픈소스 관측성 및 평가 도구예요(langtrace.ai). LiteLLM 스팬을 OpenTelemetry Collector를 거쳐 Langtrace로 보내는 방법을 알려드릴게요.

출처: 문서

본문

info — 콜백을 더 좋게 만들기 위해 LiteLLM 창업자와 이야기하거나 디스코드에 참여해 주세요.

사전 요구사항 (Pre-Requisites)

uv add litellm

Langtrace는 사용자 지정 경로(/api/trace)에서 x-api-key 헤더와 함께 JSON 인코딩 OTLP를 수집하는 반면, litellm은 protobuf를 /v1/traces로 보내요. 따라서 Langtrace가 litellm의 스팬을 직접 받을 수 없어요. 둘 사이에 OpenTelemetry Collector를 실행하세요. litellm은 컬렉터로 내보내고, 컬렉터는 스팬을 JSON으로 재인코딩해 Langtrace로 전달해요.

langtrace 콜백은 Langtrace의 속성 스키마를 적용하고, 컬렉터가 전달만 담당해요. 그래서 프리셋은 자체 자격 증명을 읽지 않고, LANGTRACE_API_KEY도 프록시가 아니라 컬렉터 환경에 존재해요.

빠른 시작 (Quick Start)

SDK:

import litellm
import os

os.environ["LITELLM_OTEL_V2"] = "true"
os.environ["OTEL_ENDPOINT"] = "http://otel-collector:4318"
# LLM API Keys
os.environ["OPENAI_API_KEY"] = ""

# set langtrace as a callback, litellm will send the data to langtrace
litellm.callbacks = ["langtrace"]

# openai call
response = litellm.completion(
  model="gpt-5.6-terra",
  messages=[
    {"role": "user", "content": "Hi 👋 - i'm openai"}
  ]
)

LiteLLM Proxy:

  1. config.yaml 설정
model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  callbacks: ["langtrace"]
  1. litellm을 컬렉터에 연결
LITELLM_OTEL_V2=true
OTEL_ENDPOINT="http://otel-collector:4318"
  1. 컬렉터 구성 — otel-collector-config.yaml, LANGTRACE_API_KEY는 컬렉터 환경에 설정:
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  otlphttp/langtrace:
    encoding: json
    compression: none
    traces_endpoint: https://app.langtrace.ai/api/trace
    headers:
      x-api-key: ${env:...KEY}
      Content-Type: application/json
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/langtrace]
  1. LiteLLM 프록시 시작
litellm --config /path/to/config.yaml
  1. 테스트해 보세요!
curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-d '{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Hey, how are you?"
    }
  ]
}'

Langtrace가 렌더링하는 것 (What Langtrace renders)

Langtrace UI를 열어 보세요. 스팬은 표준 gen_ai.* 키와 함께 langtrace.* 및 llm.* 키를 들고 컬렉터를 통해 흘러가요.

langtrace 매퍼는 프로바이더용 langtrace.service.name, 요청·응답 식별자(llm.model, gen_ai.response.model, gen_ai.response_id, gen_ai.system_fingerprint), 요청 파라미터(llm.temperature, top_p, top_k, max_tokens, frequency_penalty, presence_penalty), llm.stream 플래그, llm.token.counts.* 사용량 분할, 그리고 콘텐츠 캡처가 켜져 있을 때 llm.prompts / llm.completions를 추가해요. 전체 속성 표는 full attribute table을 참고해 주세요.

전체 OpenTelemetry 참조 (Full OpenTelemetry reference)

이 페이지는 Langtrace 전용 설정을 다뤄요. 스팬 속성, 프롬프트·응답 캡처, 메트릭, 분산 추적, 추적되는 라우트에 대한 자세한 내용은 OpenTelemetry v2 가이드를 참고해 주세요.

지원 및 창업자와 소통 (Support & Talk to Founders)

더 알아보기 (Learn more)