Grafana Cloud

LiteLLM 트레이스와 GenAI 메트릭을 OTLP로 Grafana Cloud에 보내는 방법을 알려드릴게요.

출처: 문서

본문

사전 요구사항 (Prerequisites)

Grafana Cloud 스택
**Connections > Add new connection > OpenTelemetry (OTLP)**에서 traces:write 및 metrics:write 스코프를 가진 액세스 정책 토큰
같은 페이지에 표시되는 스택의 OTLP 엔드포인트와 숫자형 인스턴스 ID

설정 (Setup)

Grafana Cloud는 OTLP를 HTTP Basic 인증으로 검증해요. 사용자 이름은 인스턴스 ID, 비밀번호는 토큰이에요. 자격 증명을 한 번 만들어 두세요:

echo -n "<instance-id>:<access-policy-token>" | base64

LiteLLM을 게이트웨이에 연결해 주세요:

.env:

LITELLM_OTEL_V2=true
LITELLM_OTEL_INTEGRATION_ENABLE_METRICS=true

OTEL_EXPORTER="otlp_http"
OTEL_ENDPOINT="https://otlp-gateway-prod-us-west-0.grafana.net/otlp"
OTEL_HEADERS="Authorization=Basic%20<base64-from-above>"

config.yaml:

litellm_settings:
  callbacks: ["otel"]

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

include_list는 메트릭 속성을 제한된 집합으로 유지해서 rate()와 increase()가 깔끔하게 집계되고 활성 시리즈 수를 낮게 유지하게 해줘요. 프로덕션 트래픽을 보내기 전에 설정하세요. 메트릭에만 적용되므로 트레이스는 전체 속성 집합을 유지해요. 제외 목록(denylist) 형태는 메트릭 속성 카디널리티 제어를 참고해 주세요.

프록시를 시작하고 요청을 보내 보세요. 트레이스는 Tempo에, 메트릭은 호스팅 Prometheus에 들어오며 둘 다 Explore에서 쿼리할 수 있어요.

왜 Basic%20이고 Basic 이 아닌가? — OTEL_HEADERS는 값을 W3C Baggage 형식으로 인코딩하는 OTLP 사양을 따르므로 공백은 %20으로 쓰여요. Grafana Cloud 설정 화면이 정확히 이 형태로 값을 알려줘요. 리터럴 공백도 작동해요.

트레이스만 보내려면 LITELLM_OTEL_INTEGRATION_ENABLE_METRICS를 빼면 돼요.

트레이스 (Traces)

각 요청은 하나의 트레이스예요. 라우트의 서버 스팬, auth 스팬, 그리고 모델·프로바이더·토큰 수·지연 시간에 대한 표준 OpenTelemetry GenAI 속성을 가진 chat <model> 스팬으로 구성돼요.

메트릭 (Metrics)

메트릭은 OTLP 히스토그램으로 도착하며, Prometheus 정규화 이름으로 Explore에서 쿼리할 수 있어요:

LiteLLM 계측	쿼리 가능 이름
`gen_ai.client.operation.duration`	`gen_ai_client_operation_duration_seconds_bucket`
`gen_ai.client.token.usage`	`gen_ai_client_token_usage_bucket`
`gen_ai.usage.cost`	`gen_ai_usage_cost_USD_sum`
`gen_ai.server.time_to_first_token`	`gen_ai_server_time_to_first_token_seconds_bucket`
`gen_ai.server.time_per_output_token`	`gen_ai_server_time_per_output_token_seconds_bucket`
`gen_ai.client.response.duration`	`gen_ai_client_response_duration_seconds_bucket`

대시보드 (Dashboard)

LiteLLM은 cookbook/litellm_proxy_server/grafana_dashboard/dashboard_genai_otel에 이 메트릭용 대시보드를 제공해요. Dashboards > New > Import에서 JSON을 가져오고 Prometheus 데이터 소스를 선택하세요.

지출, 토큰, 요청 수, p95 지연 시간을 통계로 보여주고, 모델별로 요청 비율, 시간당 지출, 입력·출력으로 나눈 토큰 처리량, p95 지연 시간, 첫 토큰까지의 시간, 프로바이더 생성 시간을 보여줘요.

Prometheus 메트릭

OTLP 경로는 요청별 GenAI 텔레메트리를 다뤄요. LiteLLM의 운영 메트릭(예산, 속도 제한, 배포 상태, 지출)은 프록시의 /metrics 엔드포인트에 있으며 스크래핑으로 Grafana Cloud에 도달해요. Grafana Alloy를 프록시에 연결해 주세요:

config.alloy:

prometheus.scrape "litellm" {
  targets      = [{__address__ = "litellm-proxy:4000"}]
  bearer_token = "<litellm-api-key>"
  forward_to   = [prometheus.remote_write.grafana_cloud.receiver]
}

prometheus.remote_write "grafana_cloud" {
  endpoint {
    url = "https://prometheus-prod-<region>.grafana.net/api/prom/push"
    basic_auth {
      username = "<instance-id>"
      password = "<access-policy-token>"
    }
  }
}

/metrics는 기본적으로 LiteLLM API 키가 필요한데, bearer_token이 이를 제공해요. 인증 없이 노출하려면 litellm_settings 아래에 require_auth_for_metrics_endpoint: false를 설정하세요. 멀티 워커 배포에서는 PROMETHEUS_MULTIPROC_DIR을 설정해 워커들이 통합된 뷰를 보고하게 해야 해요.

OTLP에서 했던 것과 같은 방식으로 레이블 집합을 제한해 주세요:

config.yaml:

litellm_settings:
  prometheus_metrics_config:
    - group: "core"
      metrics:
        - "litellm_proxy_total_requests_metric"
        - "litellm_spend_metric"
      include_labels:
        - "model"
        - "team"

전체 메트릭 참조와 LiteLLM이 유지 관리하는 대시보드는 Prometheus 메트릭을 참고해 주세요.

더 알아보기 (Learn more)

Grafana Cloud — 호스팅 관측성 플랫폼
OpenTelemetry v2 — 스팬 속성·메트릭 카디널리티 제어