OpenTelemetry v2

OpenTelemetry v2

OpenTelemetry v2(OTel v2)는 LiteLLM Proxy의 차세대 트레이싱이에요. 들어오는 HTTP 호출, 인증, 가드레일, LLM 호출 자체, 내부 데이터베이스/캐시 작업까지 요청 하나당 하나의 깔끔한 트레이스로, 모두 하나의 트리에 중첩시켜 보여 줘요.

표준 OpenTelemetry GenAI 시맨틱 컨벤션을 따르기 때문에, 생성된 트레이스는 Grafana Tempo, Jaeger, Honeycomb, Datadog 등 어떤 OTel 백엔드에서든 읽을 수 있어요. 그리고 인기 있는 LLM 관측성 도구(Arize, Phoenix, Langfuse, Weave, Langtrace, Levo, AgentOps)를 위한 준비된 프리셋도 함께 제공돼요.

옵트 인(Opt-in) 기능

OTel v2는 기본적으로 꺼져 있어요. LITELLM_OTEL_V2=true를 설정하기 전까지는 아무것도 실행되지 않아요. 기존 OpenTelemetry 통합과는 별개이므로 둘 중 하나만 선택하면 돼요. v1에서 이동한다면 OpenTelemetry v2로 마이그레이션 문서를 참고해 주세요.

출처: 문서

본문

무엇을 얻을 수 있나요? (What you get)

프록시에 대한 단일 요청은 다음과 같은 하나의 트레이스를 만들어 내요.

POST /v1/chat/completions                  ← HTTP request (server span)
├── auth /v1/chat/completions              ← authentication
│   ├── postgres get_key_object            ← DB lookups during auth
│   └── postgres get_team_membership
├── execute_guardrail presidio-pii         ← each guardrail that runs
├── chat gpt-5.6-terra                     ← the LLM call (model, tokens, cost)
└── batch_write_to_db                      ← spend/usage written to DB

주요 특징:

  • 하나의 트레이스로 처음부터 끝까지 — HTTP 요청, 인증, 가드레일, LLM 호출, DB 쓰기가 모두 같은 트레이스 안에 올바르게 중첩돼요.
  • 풍부한 GenAI 속성 — 모든 LLM 호출 스팬은 gen_ai.* 속성(모델, 프로바이더, 토큰 사용량, 비용, 완료 사유, 요청 파라미터 등)을 담아요.
  • 표준 기반 — 공식 OpenTelemetry GenAI 시맨틱 컨벤션 위에 구축되어 어떤 OTel 호환 백엔드에서도 동작해요.
  • 벤더 프리셋 — 한 줄로 Arize, Phoenix, Langfuse, Weave, Langtrace, Levo 또는 AgentOps에 각 도구가 기대하는 형식으로 트레이스를 보낼 수 있어요.
  • 기본적으로 안전 — 요청 내용에 명시적으로 옵트 인하지 않는 한 프롬프트/응답은 캡처하지 않아요. 건강 체크·메트릭 스크랩·UI 자산 같은 시끄러운 라우트는 자동으로 제외돼요.
  • 분산 트레이싱 — 클라이언트가 traceparent 헤더를 보내면 LiteLLM의 스팬이 기존 트레이스 안에 중첩돼요.

시작하기 (Getting Started)

프록시 환경에 LITELLM_OTEL_V2=true를 설정한 뒤 아래 목적지 중 하나를 선택해요.

1. 모든 OTLP 콜렉터에 트레이스 보내기

이 방식은 아래 엔드포인트에서 이미 실행 중인 콜렉터/백엔드로 OTLP(OpenTelemetry Protocol)를 통해 스팬을 보내요. 아직 없다면 Quickstart의 console exporter로 먼저 시작해 보세요. 기능 플래그와 표준 OTEL_* 환경 변수만 설정하면 되고, config 변경은 필요 없어요.

OTLP HTTP 콜렉터

LITELLM_OTEL_V2=true
OTEL_EXPORTER="otlp_http"
OTEL_ENDPOINT="http://localhost:4318"

OTLP gRPC 콜렉터

gRPC export에는 grpcio가 필요해요. pip install grpcio로 설치하면 됩니다.

LITELLM_OTEL_V2=true
OTEL_EXPORTER="otlp_grpc"
OTEL_ENDPOINT="http://localhost:4317"

백엔드가 필요로 하는 인증 헤더는 OTEL_HEADERS로 전달할 수 있어요.

OTEL_HEADERS="api-key=your-key,x-tenant=acme"

그다음 프록시를 평소처럼 시작해요.

litellm --config config.yaml

요청을 보내면 백엔드에서 요청당 하나의 트레이스를 확인할 수 있어요.

2. 특정 도구로 보내기 (프리셋)

LLM 관측성 도구에는 **프리셋(preset)**을 사용해요. 프리셋은 해당 도구의 엔드포인트를 알고 있으며, 그 도구가 기대하는 스키마로 속성을 내보내요. 활성화하려면 config의 callbacks에 이름을 추가하고, 도구 자격 증명을 환경 변수로 설정하면 돼요.

Arize

litellm_settings:
  callbacks: ["arize"]

LITELLM_OTEL_V2=true
ARIZE_SPACE_ID="your-space-id"
ARIZE_API_KEY="your-api-key"
ARIZE_PROJECT_NAME="your-project-name"   # recommended: names the project traces land in

Arize Phoenix

litellm_settings:
  callbacks: ["arize_phoenix"]

LITELLM_OTEL_V2=true
PHOENIX_API_KEY="your-api-key"
PHOENIX_COLLECTOR_ENDPOINT="https://app.phoenix.arize.com/v1/traces"
PHOENIX_PROJECT_NAME="my-project"   # optional

Langfuse

litellm_settings:
  callbacks: ["langfuse_otel"]

LITELLM_OTEL_V2=true
LANGFUSE_PUBLIC_KEY="pk-..."
LANGFUSE_SECRET_KEY="sk-..."
LANGFUSE_HOST="https://cloud.langfuse.com"   # or your self-hosted URL

Weave (W&B)

litellm_settings:
  callbacks: ["weave_otel"]

LITELLM_OTEL_V2=true
WANDB_API_KEY="your-api-key"
WANDB_PROJECT_ID="your-entity/your-project"

Langtrace

Langtrace는 litellm의 OTLP 스팬을 직접 받지 않아요. 커스텀 경로(/api/trace)에서 x-api-key 헤더와 함께 JSON 인코딩된 OTLP를 수집하는 반면, litellm v2는 /v1/traces로 protobuf를 보내요. 따라서 둘 사이에 OpenTelemetry Collector를 두세요: litellm은 콜렉터로 export하고, 콜렉터가 스팬을 JSON으로 재인코딩해 Langtrace로 전달해요. langtrace 콜백은 여전히 Langtrace의 속성 스키마를 적용하며, 콜렉터는 전달만 담당해요.

litellm_settings:
  callbacks: ["langtrace"]

LITELLM_OTEL_V2=true
OTEL_ENDPOINT="http://otel-collector:4318"

콜렉터(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]

Levo

litellm_settings:
  callbacks: ["levo"]

LITELLM_OTEL_V2=true
LEVOAI_API_KEY="your-api-key"
LEVOAI_ORG_ID="your-org-id"
LEVOAI_WORKSPACE_ID="your-workspace-id"
LEVOAI_COLLECTOR_URL="your-levo-collector-url"   # contact Levo support for this

AgentOps

litellm_settings:
  callbacks: ["agentops"]

LITELLM_OTEL_V2=true
AGENTOPS_API_KEY="your-api-key"

여러 백엔드에 동시에 보내기

같은 트레이스를 여러 벤더로 보내려면 callbacks에 각 프리셋을 나열하고 각자의 환경 변수를 설정하면 돼요. 예를 들어 Langfuse와 Arize를 함께 쓰면:

litellm_settings:
  callbacks: ["langfuse_otel", "arize"]

각 프리셋이 자기 목적지를 추가하므로, 스팬이 각 도구의 네이티브 형식으로 병렬로 모든 곳에 도달해요.

프리셋 참조 (Preset Reference)

각 프리셋은 하나의 공유 트레이서 위에 하나의 exporter로 변환돼요. 아래 표는 각각의 callback 이름(callbacks에 넣는 값), 읽는 자격 증명, 전송 대상, 표준 gen_ai.* 키 위에 추가하는 속성 어휘, 요청별(팀/키) 자격 증명 지원 여부를 보여 줘요.

프리셋 자격 증명 전송 대상
arize ARIZE_SPACE_ID, ARIZE_SPACE_KEY, ARIZE_API_KEY, ARIZE_PROJECT_NAME, ARIZE_ENDPOINT/ARIZE_HTTP_ENDPOINT https://otlp.arize.com/v1
arize_phoenix PHOENIX_API_KEY, PHOENIX_COLLECTOR_HTTP_ENDPOINT, PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_PROJECT_NAME —
langfuse_otel LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST/LANGFUSE_OTEL_HOST https://us.cloud.langfuse.com / https://cloud.langfuse.com
weave_otel WANDB_API_KEY, WANDB_PROJECT_ID(<entity>/<project>), WANDB_HOST https://trace.wandb.ai
langtrace — —
levo LEVOAI_API_KEY, LEVOAI_ORG_ID, LEVOAI_WORKSPACE_ID, LEVOAI_COLLECTOR_URL —
agentops AGENTOPS_API_KEY, AGENTOPS_SERVICE_NAME, AGENTOPS_ENVIRONMENT https://otlp.agentops.ai/v1/traces
  • arize, arize_phoenix는 openinference 속성 vocab을 추가해요. 자세한 내용은 Arize 통합과 Phoenix 통합을 참고해 주세요.
  • langtrace는 /v1/traces가 아니라 콜렉터를 통한 별도 경로로 보내므로 gen_ai.* + llm.* vocab을 적용해요.

트레이스 확인하기 (Seeing your traces)

LLM 호출 스팬 이름은 chat <model> 형식이에요.

Arize에서 렌더링되는 모습

ARIZE_PROJECT_NAME으로 프로젝트가 구분되며, openinference 개방형 스키마 속성(gen_ai.* 기반)이 사용돼요. 예: openinference.span.kind=LLM, llm.model_name, llm.provider, llm.token_count.prompt/completion/total, llm.invocation_parameters, llm.input_messages.{idx}.message.role/content, llm.output_messages.{idx}.message.role/content, input.value, output.value, llm.tools.{idx}.tool.name/description/json_schema. 전체 스키마는 OpenInference 시맨틱 컨벤션을 참고하세요.

설정 메모: ARIZE_SPACE_KEY를 쓰려면 반드시 ARIZE_SPACE_ID가 있어야 해요.

LiteLLM trace in Arize

Phoenix에서 렌더링되는 모습

PHOENIX_PROJECT_NAME(기본 default)이 openinference.project.name로 연결돼요. 팀/키별로 Phoenix 프로젝트를 나누고 싶다면 Phoenix 통합 - 프로젝트 라우팅 문서를 참고하세요. Phoenix도 openinference 스키마를 사용해요.

설정 메모: PHOENIX_COLLECTOR_HTTP_ENDPOINT와 PHOENIX_COLLECTOR_ENDPOINT를 구분해요. grpc://...:4317 같은 gRPC 주소는 PHOENIX_COLLECTOR_ENDPOINT로, /v1/traces가 붙는 HTTP 주소(예: https://app.phoenix.arize.com/s/<space-name>/v1/traces, https://app.phoenix.arize.com/legacy/v1/traces, https://app.phoenix.arize.com/v1/traces, http://localhost:6006/v1/traces)는 PHOENIX_COLLECTOR_HTTP_ENDPOINT로 설정해요.

LiteLLM trace in Phoenix

Langfuse에서 렌더링되는 모습

Langfuse 프리셋은 LANGFUSE_OTEL_HOST(없으면 LANGFUSE_HOST)의 /api/public/otel 경로로 보내요. langfuse vocab을 사용해요: langfuse.observation.type=generation, langfuse.observation.model.name, langfuse.observation.model.parameters, langfuse.observation.id(= litellm.call_id), langfuse.observation.input/output, langfuse.observation.usage_details, langfuse.observation.cost_details, langfuse.trace.metadata.team_id/team_alias.

설정 메모: 인증은 Authorization: Basic <base6...ey)> 헤더로 LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY를 조합해 보내요. traceparent가 있을 때는 OTEL_IGNORE_CONTEXT_PROPAGATION=true를 고려해 보세요. 스팬 범위를 LLM 호출만으로 제한하려면 LITELLM_OTEL_LANGFUSE_SPAN_SCOPE=llm_only를 쓰세요(1. 모든 OTLP 콜렉터로 보내기 참고).

LiteLLM trace in Langfuse

Weave에서 렌더링되는 모습

Weave는 wandb.ai/<entity>/weave로 보내며, weave_otel 프리셋은 weave + openinference vocab을 사용해요: weave.display_name = "{operation} {model}"(예: chat gpt-4o), weave.call_id(= litellm.call_id), weave.output.

설정 메모: WANDB_PROJECT_ID는 entity/project 형식이에요. weave_otel을 활성화하면 wandb 통합은 별도로 동작하지 않아요. 자세한 내용은 W&B 통합을 참고하세요.

LiteLLM trace in Weave

AgentOps에서 렌더링되는 모습

AgentOps는 gen_ai.*(레거시) vocab을 사용해요.

AgentOps 프리셋이 추가하는 속성

  • service.name — AGENTOPS_SERVICE_NAME(기본 agentops)
  • deployment.environment — AGENTOPS_ENVIRONMENT

설정 메모: AGENTOPS_SERVICE_NAME, AGENTOPS_ENVIRONMENT를 설정해 주세요.

LiteLLM trace in AgentOps

Langtrace에서 렌더링되는 모습

Langtrace는 langtrace.*, llm.* vocab을 사용해요. 예: 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.prompt/completion/total, llm.prompts, llm.completions.

LiteLLM trace in Langtrace

Levo에서 렌더링되는 모습

Levo는 gen_ai.*(레거시) vocab을 사용해요.

Levo 프리셋이 추가하는 속성

LEVOAI_COLLECTOR_URL로 보내며, Authorization: Bearer *** + x-levo-organization-id, x-levo-workspace-id 헤더를 LEVOAI_ORG_ID, LEVOAI_WORKSPACE_ID로 설정해요.

설정 메모: OTEL_ENVIRONMENT_NAME도 설정할 수 있어요.

일반 OTLP 백엔드에서 렌더링되는 모습

generic 목적지에서는 gen_ai.* + litellm.* + legacy vocab을 사용해요. Legacy compat를 원하면 LITELLM_OTEL_LEGACY_COMPAT=true를 설정하세요. 자세한 내용은 Grafana Cloud 문서를 참고해 주세요.

프롬프트·응답 캡처 (Capturing Prompts & Responses)

기본(no_content)은 프롬프트/응답을 캡처하지 않아요. 원하면 명시적으로 옵트 인합니다.

# no_content (default) — never capture prompts/responses
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="no_content"
# span_only — write prompts/responses as attributes on spans
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="span_only"
# event_only — write prompts/responses on log events instead of span attributes
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="event_only"
# span_and_event — write content to both spans and events
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="span_and_event"

스팬 속성 (Span Attributes)

LLM 호출 스팬은 genai(및 legacy) mapper를 사용해요. 주요 gen_ai.* 속성: gen_ai.operation.name(chat, text_completion, embeddings), gen_ai.provider.name, gen_ai.request.model, gen_ai.request.temperature/top_p/top_k/max_tokens, gen_ai.request.frequency_penalty/presence_penalty/seed, gen_ai.request.stop_sequences, gen_ai.tool.{idx}.name/description/parameters(또는 집계된 litellm.request.tools.declared), 그리고 server.address, server.port도 포함돼요.

  • 도구 정의는 상한이 있어요: gen_ai.tool.{idx}.*, gen_ai.*(genai/legacy), openinference vocab은 개수/크기가 제한될 수 있고, 집계 경로로 litellm.request.tools.declared가 추가돼요.
  • 채팅 메시지도 상한이 있어요: openinference의 llm.input_messages.{idx}.*, llm.output_messages.{idx}.*과 gen_ai.*는 OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT(SpanLimits)에 영향을 받아요. 값 길이는 OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT로, 특히 input.value가 잘릴 수 있어요. genai/openinference 모드에서 LITELLM_OTEL_LEGACY_COMPAT=false면 지수/로그 지문이 생기지 않아요(예: llm.input_messages.0.18.59). legacy vocab은 input.value, output.value(및 gen_ai.input.messages, gen_ai.output.messages)를 사용해요.

응답 및 사용량 속성: gen_ai.response.id, gen_ai.response.model, gen_ai.response.finish_reasons, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions.

LiteLLM별 속성 (litellm.*): litellm.call_id, litellm.provider.model, litellm.request.streaming, litellm.request.route, http.route(예: /v1/responses/{response_id}, /openai/...), OTEL_PYTHON_FASTAPI_EXCLUDED_URLS로 제외 가능, litellm.cost.total, litellm.cost.input/output/cache_read/cache_creation/tool_usage, litellm.cost.original, 그리고 discount_amount/discount_percent/margin_fixed_amount/margin_percent/margin_total_amount.

오류 속성: exception(예외) — exception.type, exception.message, error.type, ERROR 상태 스팬.

상태(setStatus): UNSET, ERROR, OK 사용.

기타 스팬 종류 (Other span kinds)

  • 가드레일 스팬 — litellm.guardrail.* 속성: name, mode, status(success, guardrail_intervened, guardrail_failed_to_respond, not_run), provider, action, response, violation_categories, confidence_score, risk_score, masked_entity_count, duration, id, policy_template, detection_method. 예외 시 ERROR로 표시돼요.
  • DB/서비스 스팬 — db.system.name, db.operation.name, litellm.service.name, litellm.service.call_type. (litellm.service.*, db.* vocab)
  • MCP(도구) 스팬 — gen_ai.operation.name=execute_tool, mcp.method.name, mcp.session.id, gen_ai.tool.name, litellm.mcp.server.name, litellm.call_id, litellm.cost.total, gen_ai.tool.call.arguments, gen_ai.tool.call.result. (gen_ai.* vocab)
  • HTTP 서버 스팬 — http.request.method, http.route, http.response.status_code, url.path.

속성 컨벤션 (Attribute Conventions)

mapper_names는 genai, legacy, (LITELLM_OTEL_LEGACY_COMPAT=true/false에 따라) openinference, langfuse, weave, langtrace가 될 수 있어요. 주요 매핑 예시:

standard (genai) legacy
gen_ai.usage.input_tokens gen_ai.usage.prompt_tokens / llm.token_count.prompt
gen_ai.usage.output_tokens gen_ai.usage.completion_tokens / llm.token_count.completion
gen_ai.provider.name gen_ai.system / llm.provider
litellm.request.streaming llm.is_streaming
gen_ai.request.model llm.model_name

모든 스팬의 요청 식별 (Request Identity on Every Span)

OpenTelemetry Baggage를 사용해 요청 식별 정보를 모든 스팬에 전파할 수 있어요. 팀/키/메타데이터 식별 속성이 기본적으로 포함되고, 환경 변수(LITELLM_OTEL_BAGGAGE_PROMOTED_KEYS, LITELLM_OTEL_BAGGAGE_METADATA_KEYS, LITELLM_OTEL_BAGGAGE_TEAM_METADATA_KEYS)로 추가 키를 승격할 수 있어요. callback_settings.otel로 제어해요.

관련 속성: litellm.team.id, litellm.team.alias, litellm.team.metadata, litellm.api_key.hash, gen_ai.request.model, litellm.provider.model, litellm.metadata.*(litellm.metadata.user_api_key_org_id, litellm.metadata.user_api_key_user_id, litellm.metadata.user_api_key_alias, litellm.metadata.user_api_key_end_user_id, litellm.metadata.requester_ip_address 등).

메트릭 (Metrics)

LITELLM_OTEL_V2=true와 함께 LITELLM_OTEL_INTEGRATION_ENABLE_METRICS=true를 설정하면 gen_ai.* 메트릭이 OTEL_EXPORTER(console, otlp_http, otlp_grpc), OTEL_ENDPOINT, OTEL_HEADERS로 전송돼요.

기록되는 항목: gen_ai.client.operation.duration(s), gen_ai.client.token.usage({token}, gen_ai.token.type), gen_ai.usage.cost(USD), gen_ai.server.time_to_first_token(s), gen_ai.server.time_per_output_token(s), gen_ai.client.response.duration(s), 그리고 gen_ai.client.token.cost, gen_ai.client.response.time_to_first_token, gen_ai.client.response.time_per_output_token 등. 메트릭에 metadata.*가 태그로 들어갈 수 있어요(v1 참고).

메트릭 속성 카디널리티 제어

hidden_params, metadata.* 같은 고카디널리티 속성이 메트릭 태그를 과도하게 만들 수 있어요. callback_settings.otel.attributes의 include_list/exclude_list로 제어해요. LITELLM_OTEL_V2 모드에서는 callbacks에 otel을 넣어도 동일하게 callback_settings.otel로 제어할 수 있어요(실제로는 arize, arize_phoenix, langfuse_otel 등 v2 프리셋이 사용됨).

callback_settings:
  otel:
    attributes:
      exclude_list:
        - hidden_params
        - metadata.requester_metadata
        - metadata.requester_ip_address
        - metadata.spend_logs_metadata
        - metadata.mcp_tool_call_metadata
        - metadata.vector_store_request_metadata
        - metadata.prompt_management_metadata

callback_settings:
  otel:
    attributes:
      include_list:
        - gen_ai.operation.name
        - gen_ai.system
        - gen_ai.request.model
        - gen_ai.framework
        - metadata.user_api_key_team_id
        - metadata.user_api_key_org_id

(gen_ai.token.type, gen_ai.client.token.usage 같은 항목은 include_list/exclude_list로 관리할 수 있어요.)

어떤 라우트가 트레이싱되나요? (Which routes are traced)

기본적으로 시끄러운 라우트(/health*, /metrics, /ui, /docs, /redoc, /_next, /openapi.json)는 자동으로 제외돼요.

# Trace everything, including health checks
OTEL_PYTHON_FASTAPI_EXCLUDED_URLS=""
# Exclude only your own custom paths
OTEL_PYTHON_FASTAPI_EXCLUDED_URLS="/health,/internal"

키/팀별 자격 증명 (Per-Key / Per-Team Credentials, Multi-Tenant)

callback_vars를 통해 팀/키별로 별도 자격 증명을 설정할 수 있어요. 자세한 내용은 팀 로깅 문서를 참고해 주세요.

요청별 자격 증명을 지원하는 프리셋: langfuse_otel(langfuse_public_key, langfuse_secret_key, langfuse_host), arize(arize_space_id, arize_space_key, arize_api_key), weave_otel(wandb_api_key, weave_project_id), newrelic(newrelic_api_key, newrelic_region — us/eu, 기본 us). arize_phoenix(phoenix_project_name), langtrace, levo, agentops, otel도 지원돼요. 또한 service.name(otel_service_name), metadata도 설정할 수 있어요.

팀에 설정하기

curl -X POST 'http://localhost:4000/team/<team-id>/callback' \
  -H "Authorization: Bearer ***" -H 'Content-Type: application/json' \
  -d '{
    "callback_name": "langfuse_otel",
    "callback_type": "success",
    "callback_vars": {
      "langfuse_public_key": "pk-lf-...",
      "langfuse_secret_key": "sk-lf-..."
    }
  }'

조회는 GET /team/<team-id>/callback, 삭제는 DELETE /team/<team-id>/callback/<callback_name>, 비활성화는 POST /team/<team-id>/disable_logging을 사용해요.

키에 설정하기

curl -X POST 'http://localhost:4000/key/generate' \
  -H "Authorization: Bearer ***" -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "logging": [{
        "callback_name": "arize",
        "callback_type": "success",
        "callback_vars": {"arize_space_id": "...", "arize_api_key": "..."}
      }]
    }
  }'

자세한 내용은 /key/update 문서를 참고해 주세요.

테넌트가 받는 것 (What the tenant receives)

langfuse_otel 같은 프리셋은 기본적으로 테넌트 자격 증명으로 대체(override)돼요. otel도 동일해요.

내 사본도 함께 유지하기

기본값은 override지만, additive(추가) 모드로 바꾸면 나만의 프리셋과 테넌트 프리셋을 모두 실행할 수 있어요.

litellm_settings:
  otel_tenant_destination_mode: additive   # default: "override"

환경 변수로는 LITELLM_OTEL_TENANT_DESTINATION_MODE=additive를 설정하면 돼요.

테넌트를 자체 Langfuse 호스트로 보내기

테넌트가 langfuse_host를 설정하면 자체 호스트로 보낼 수 있어요. 안전을 위해 허용 호스트 목록을 지정할 수 있어요.

litellm_settings:
  provider_url_destination_allowed_hosts: ["langfuse.acme.com"]

(LANGFUSE_HOST도 설정.)

모델 호출만 Langfuse로 보내기

기본 full 대신 llm_only 스코프를 사용하면 LLM 호출 스팬만 Langfuse로 보내요. gen_ai.operation.name 스팬만 전송되며, langfuse.trace.name(또는 user.id, session.id, langfuse.trace.tags)는 langfuse_trace_name/metadata.trace_name으로 지정할 수 있어요. 기본 스팬 이름은 chat claude-3-5-haiku 형식입니다.

curl -X POST 'http://localhost:4000/team/<team-id>/callback' \
  -H "Authorization: Bearer ***" -H 'Content-Type: application/json' \
  -d '{
    "callback_name": "langfuse_otel",
    "callback_type": "success",
    "callback_vars": {
      "langfuse_public_key": "pk-lf-...",
      "langfuse_secret_key": "sk-lf-...",
      "langfuse_span_scope": "llm_only"
    }
  }'

전역으로는 LITELLM_OTEL_LANGFUSE_SPAN_SCOPE=llm_only(기본 full)를 설정하거나, langfuse_otel 프리셋의 langfuse_span_scope(full/llm_only)로 설정할 수 있어요.

분산 트레이싱 (Distributed Tracing)

클라이언트가 traceparent 헤더를 보내면 LiteLLM의 스팬이 기존 트레이스 안에 중첩돼요.

설정 참조 (Configuration Reference)

변수/callback 기본값 설명
LITELLM_OTEL_V2 false OTel v2 활성화 (기본값 true로 변경 가능)
LITELLM_OTEL_TENANT_DESTINATION_MODE override 테넌트 목적지 모드 (additive 가능)
LITELLM_OTEL_LANGFUSE_SPAN_SCOPE / langfuse_span_scope full Langfuse 스팬 범위 (full/llm_only)
OTEL_EXPORTER / OTEL_EXPORTER_OTLP_PROTOCOL console exporter 유형: console, otlp_http, otlp_grpc
OTEL_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT — OTLP 엔드포인트 (기본 otlp_http; OTEL_EXPORTER에 따라 자동)
OTEL_HEADERS / OTEL_EXPORTER_OTLP_HEADERS — key=value 형식 헤더
OTEL_SERVICE_NAME litellm service.name 리소스 속성
OTEL_ENVIRONMENT_NAME deployment.environment 배포 환경 (production)
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT no_content no_content, span_only, event_only, span_and_event
OTEL_PYTHON_FASTAPI_EXCLUDED_URLS "" 제외할 라우트 목록
LITELLM_OTEL_INTEGRATION_ENABLE_METRICS false 메트릭 활성화
LITELLM_OTEL_LEGACY_COMPAT true 레거시 속성 호환성

문제 해결 (Troubleshooting)

  • 트레이스가 안 보여요: LITELLM_OTEL_V2=true와 OTEL_EXPORTER="console"로 시작해 보세요. /v1/chat/completions 요청(및 opentelemetry-instrumentation-fastapi로 노출된 auth, postgres 스팬)이 console에 출력되는지 확인해요. FastAPI 계측이 프록시에 적용되지 않으면 해당 패키지 설치를 확인해요. 콘텐츠 캡처 확인은 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_only를 써 보세요.

지원 (Support)

문제가 있으면 GitHub 이슈로 알려주세요.

더 알아보기 (Learn more)