본문으로 건너뛰기

LiteLLM 관측하기: Prometheus·Grafana·Tempo로 LLM 호출의 토큰·지연·오류·비용 보고 경보 걸기

LiteLLM의 지표와 트레이스를 기존 Prometheus·Grafana·Tempo에 연결하고, 장애 훈련으로 경보가 언제 켜지고 꺼지는지 직접 확인했습니다.

로컬 AI 플랫폼 실습 시리즈 목차 · 글 5개
  1. 1편RTX 3060 Ti 8GB로 로컬 LLM 돌리기: Ollama 모델 4개 속도·VRAM·품질 실측
  2. 번외편Ollama 웹 채팅 화면 직접 만들기: HTML 한 장으로 WSL의 로컬 LLM에 연결하고 CORS까지 이해하기
  3. 2편kind 파드에서 클러스터 밖 Ollama 호출하기: selector 없는 Service와 EndpointSlice로 GPU는 밖, 앱은 안에
  4. 3편LiteLLM으로 로컬 LLM 게이트웨이 만들기: Ollama 앞에 가상 키·요청 한도·예산을 붙이고 kind에서 직접 확인하기
  5. 4편LiteLLM 관측하기: Prometheus·Grafana·Tempo로 LLM 호출의 토큰·지연·오류·비용 보고 경보 걸기

LiteLLM은 설정 한 줄(callbacks: ["prometheus", "otel"])로 요청 수·지연·토큰·비용 지표와 요청별 트레이스를 내보냅니다. 이 실습에서 게이트웨이 자체 지연은 평균 약 0.03초였고, 응답 시간의 거의 전부는 모델 호출이었습니다. 다만 /metrics는 관리자 권한 키로만 읽을 수 있고, 모델 상태 지표(litellm_deployment_state)는 Ollama가 완전히 멈춰도 ‘일부 장애(1)‘에서 멈춰 그대로 경보를 걸면 장애를 놓쳤습니다. 요청으로만 만들어지는 지표는 ‘요청 없음’과 ‘복구됨’을 구별하지 못한다는 한계도 확인했습니다.

3편의 LiteLLM 1.110.0을 kind 클러스터의 kube-prometheus-stack, OpenTelemetry Collector, Tempo에 연결한 결과입니다. 공유 설정은 바꾸지 않고 ai 네임스페이스에 ServiceMonitor·PrometheusRule·대시보드만 추가했습니다. 비용은 3편에서 붙인 시연용 가상 단가입니다.

무엇을 보려는가

3편에서 LiteLLM을 Ollama 앞에 두고 가상 키·한도·예산을 걸었습니다. 그 과정에서 생각 모드로 응답이 5배 느려지거나, 모델을 바꿀 때마다 20초대가 걸리거나, Ollama가 멈추면 10초 뒤에야 실패하는 현상을 봤습니다. 이번 편은 이런 현상을 매번 직접 호출해서 확인하지 않고, 그래프와 경보로 알아채도록 만드는 단계입니다.

3편에서 미뤄 둔 질문도 하나 있습니다. 게이트웨이를 하나 더 거치면 응답이 얼마나 느려지는가입니다. 모델 시간을 뺀 게이트웨이만의 시간을 지표로 잽니다.

구성

이번 편에서 추가한 것 (모두 네임스페이스 ai)

리소스 역할
LiteLLM 설정 변경 지표(prometheus)·트레이스(otel) 켜기, 트레이스에 질문·답 본문 기록 끔
ServiceMonitor litellm Prometheus가 LiteLLM /metrics/를 30초마다 수집
PrometheusRule litellm-alerts 경보 규칙 4개
ConfigMap litellm-dashboard Grafana 대시보드 “LiteLLM 게이트웨이”

이 클러스터의 Prometheus는 release: kps 라벨이 붙은 ServiceMonitor·PrometheusRule만 읽고, Grafana는 모든 네임스페이스에서 grafana_dashboard: "1" 라벨이 붙은 ConfigMap을 대시보드로 불러옵니다. 그래서 공유 설정을 건드리지 않고 ai 네임스페이스에 추가만 해도 연결됩니다.

지표와 트레이스 켜기

LiteLLM 설정에 콜백 두 개를 넣고, 트레이스를 보낼 주소를 환경 변수로 지정했습니다. LiteLLM Prometheus

03-litellm-values.yaml (일부)
envVars:
OTEL_EXPORTER: otlp_http
OTEL_ENDPOINT: http://otel-collector.observability.svc:4318/v1/traces
OTEL_SERVICE_NAME: litellm
proxy_config:
litellm_settings:
callbacks: ["prometheus", "otel"]
turn_off_message_logging: true # 트레이스에 질문·답 본문을 남기지 않음

LiteLLM은 기본으로 질문과 답 본문까지 트레이스에 기록합니다. 사내 문서나 개인정보가 오갈 수 있으므로 turn_off_message_logging: true로 껐습니다. 꺼도 모델 이름, 토큰 수, 비용, 키 별칭 같은 메타데이터는 남습니다. LiteLLM OpenTelemetry

/metrics는 관리자 키로만 읽힌다

LiteLLM v1.85.0부터 /metrics는 기본으로 키 인증이 필요합니다. 인증을 끌 수도 있지만, 그러면 클러스터 안 누구나 키 별칭과 사용량을 볼 수 있어서 수집 전용 키를 만들기로 했습니다. 그런데 모델 호출을 막아 둔 일반 가상 키로는 읽히지 않았습니다.

키 종류별 결과

키 /metrics 모델 호출 키 발급
키 없음 401 - -
일반 가상 키(모델 제한) 401 Only proxy admin can be used ... Your role=unknown 403 -
읽기 전용 관리자(proxy_admin_viewer) 사용자의 키 200 403 403 user not allowed to access this route

/metrics는 관리자 역할만 읽을 수 있었습니다. master key를 Prometheus에 주면 모든 관리 권한을 주는 셈이므로, 읽기 전용 관리자 역할의 사용자를 만들고 그 사용자의 키를 발급했습니다. 허용 모델에는 존재하지 않는 이름만 넣어 모델 호출도 막았습니다.

Terminal window
curl -s -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
http://litellm.ai.svc:4000/user/new \
-d '{"user_id":"prometheus","user_role":"proxy_admin_viewer","auto_create_key":false}'
curl -s -H "Authorization: Bearer $MASTER_KEY" -H 'Content-Type: application/json' \
http://litellm.ai.svc:4000/key/generate \
-d '{"user_id":"prometheus","key_alias":"prometheus-metrics","models":["no-model-metrics-only"]}'

발급한 키는 Secret litellm-metrics-key에 넣고 ServiceMonitor가 참조하게 했습니다. /metrics는 307로 /metrics/에 넘기므로 경로 끝에 슬래시를 붙였습니다.

04-servicemonitor.yaml (일부)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: litellm
namespace: ai
labels:
release: kps
spec:
selector:
matchLabels:
app.kubernetes.io/name: litellm
app.kubernetes.io/instance: litellm
endpoints:
- port: http
path: /metrics/
interval: 30s
authorization:
type: Bearer
credentials:
name: litellm-metrics-key
key: token

적용하고 약 30초 뒤 Prometheus 대상 목록에 serviceMonitor/ai/litellm/0이 UP으로 나타났습니다.

게이트웨이 자체 지연은 약 0.03초

몇 분 동안 가상 사용자 키 두 개와 master key로 chat·fast를 섞어 호출해 지표를 만든 뒤, PromQL로 계산했습니다. LiteLLM은 요청 전체 시간(litellm_request_total_latency_metric)과 모델 호출 시간(litellm_llm_api_latency_metric)을 따로 기록하므로, 두 평균의 차이가 게이트웨이 자체 시간입니다.

(sum by (model) (rate(litellm_request_total_latency_metric_sum[30m]))
/ sum by (model) (rate(litellm_request_total_latency_metric_count[30m])))
-
(sum by (model) (rate(litellm_llm_api_latency_metric_sum[30m]))
/ sum by (model) (rate(litellm_llm_api_latency_metric_count[30m])))

게이트웨이 자체 지연 (평균)

모델 30분 구간 대시보드 1시간 구간
qwen3:8b 0.029초 22.7ms
gemma3:4b 0.026초 25.9ms

인증·키 조회·라우팅을 모두 합쳐도 수십 밀리초였습니다. 응답이 느리다면 거의 대부분 모델 쪽 시간이라는 뜻입니다.

지연 히스토그램의 구간 경계는 0.5·1·2·5·10·30·60초처럼 넓어서, 같은 데이터로 구한 p50(1.01.3초)·p95(2842초)는 구간 사이를 어림한 값입니다. 그래서 대시보드에는 평균 지연을 함께 넣었습니다.

함정: increase()가 새 키의 첫 요청을 놓친다

키별 요청 수를 increase(...[30m])로 구했더니 방금 만든 alice·bob 키가 0으로 나왔습니다. 실제로는 alice가 6번, bob이 8번 성공했습니다.

Prometheus의 increase()는 수집된 값 사이의 증가를 셉니다. 새 키로 처음 요청이 들어오면 그때 계열이 생기는데, 첫 수집 때 이미 값이 6·8이면 그 이전 증가는 셀 수 없습니다. 누적값을 그대로 보면 정확했습니다.

sum by (api_key_alias, requested_model, status_code) (litellm_proxy_total_requests_metric_total)

누적 요청 수 (가상 사용자 키)

키 모델 상태 횟수
alice-load chat 200 6
alice-load chat 429 9
bob-load fast 200 8
bob-load chat 403 2

키별 합계처럼 “지금까지 얼마나”를 보는 패널은 누적값으로, 추세를 보는 그래프는 rate()로 만들었습니다. master key로 보낸 요청은 키 별칭이 None으로 기록됩니다.

대시보드

패널 9개짜리 대시보드를 JSON으로 만들어 ConfigMap으로 올렸습니다.

Grafana LiteLLM 게이트웨이 대시보드. 모델 상태 gemma3:4b 일부 장애, qwen3:8b 정상, 상태 코드별 요청 수 200 53·401 9·403 5·429 9·500 36, 게이트웨이 자체 지연 25.921ms·22.700ms, 초당 요청과 평균 지연 그래프, 키별 누적 토큰과 비용 막대, 키별 남은 예산, 예외 종류별 실패 요청 그래프
Grafana LiteLLM 게이트웨이 대시보드 (최근 1시간)

패널 구성

패널 PromQL 핵심
모델 상태 max by (litellm_model_name) (litellm_deployment_state)
지금까지 요청(상태 코드별) sum by (status_code) (litellm_proxy_total_requests_metric_total)
게이트웨이 자체 지연 전체 평균 − 모델 호출 평균
초당 요청(모델·상태) rate(litellm_proxy_total_requests_metric_total[2m])
평균 지연: 전체 vs 모델 호출 두 히스토그램의 sum/count
키별 누적 토큰·비용 litellm_total_tokens_metric_total, litellm_spend_metric_total
키별 남은 예산 litellm_remaining_api_key_budget_metric != Inf
실패 요청(예외별) rate(litellm_proxy_failed_requests_metric_total[2m]) * 60

사진의 모델 상태 칸에서 gemma3:4b가 “일부 장애”로 떠 있는 것은 오류가 아닙니다. 장애 훈련으로 Ollama를 멈췄다가 다시 켠 뒤 fast를 한 번도 부르지 않아, 옛 상태가 그대로 남은 것입니다. 이 지표의 한계는 아래 장애 훈련에서 다시 다룹니다.

경보 규칙

Prometheus 경보 규칙 목록에 LiteLLMModelDown, LiteLLMServerErrors, LiteLLMSlowRequests, LiteLLMKeyBudgetLow 네 규칙이 모두 정상 상태로 표시된 화면
LiteLLM 경보 규칙 4개

경보 규칙

규칙 조건 의도
LiteLLMModelDown 모델 그룹별 5xx 실패율 90% 이상, 1분 지속(수정 후) 특정 모델이 통째로 안 될 때
LiteLLMServerErrors 전체 5xx 비율 50% 초과, 2분 지속 게이트웨이 전체 문제
LiteLLMSlowRequests 평균 전체 지연 30초 초과, 5분 지속 모델 로딩이 반복될 때
LiteLLMKeyBudgetLow 키 남은 예산 0.001 미만 예산 소진 직전

5xx만 센 이유는 401·403·429·422가 사용자 쪽 거부라 정상 동작이기 때문입니다. 실패 지표에는 이런 거부도 함께 들어 있어서, status_code 또는 exception_status로 5xx만 골라내야 했습니다. 규칙 목록 화면에서 요약 문구의 {{ $labels... }}가 그대로 보이는 것은 실제 경보가 뜨면 값으로 바뀝니다.

장애 훈련 1: 모델 상태 지표는 2가 되지 않았다

처음 만든 LiteLLMModelDown 규칙은 공식 문서의 설명(0 정상, 1 일부 장애, 2 전체 장애)대로 litellm_deployment_state == 2였습니다. Ollama를 5분 동안 멈추고 15초마다 chat·fast를 호출했습니다.

Ollama 정지 5분, 재시작 후 관찰

시점 결과
정지 모든 요청 500
정지 후 30초 안팎 qwen3:8b·gemma3:4b 상태 1(일부 장애) — 이후 끝까지 2가 되지 않음
정지 후 1분 37초 LiteLLMServerErrors 대기(pending)
정지 후 3분 37초 LiteLLMServerErrors 발생(firing)
재시작 후 17초 chat 200
재시작 후 3분 42초 LiteLLMServerErrors 해제

모든 요청이 실패했는데도 상태 지표는 1에서 멈췄고, == 2 규칙은 한 번도 켜지지 않았습니다. 문서의 값 정의만 믿고 경보를 만들면 실제 장애를 놓칠 수 있습니다. 5xx 비율 경보는 5분 창으로 계산하기 때문에 켜지는 데 3분 넘게, 꺼지는 데도 3분 넘게 걸렸습니다.

장애 훈련 2: 실패율 규칙과 ‘요청 없음’의 함정

LiteLLMModelDown을 모델 그룹별 5xx 실패율로 바꾸고, Ollama를 4분 멈춘 뒤 다시 켜 4분 관찰했습니다.

04-litellm-alerts.yaml (일부)
sum by (model_group) (rate(litellm_deployment_failure_responses_total{exception_status=~"5.."}[5m]))
/ sum by (model_group) (rate(litellm_deployment_total_requests_total[5m])) >= 0.9

고친 규칙의 동작

경보 켜짐 꺼짐
LiteLLMModelDown (fast) 정지 후 1분 44초 재시작 후 4분 넘게 유지(관찰 끝까지)
LiteLLMModelDown (chat) 정지 후 3분 44초 재시작 후 47초
LiteLLMServerErrors 정지 후 3분 14초 재시작 후 3분 17초

chat은 정지 직전의 성공 요청이 5분 창에 남아 실패율을 낮춰 늦게 켜졌습니다. fast는 재시작 뒤 아무도 부르지 않아 창 안에 실패 기록만 남았고, 그래서 이미 복구됐는데도 경보가 계속 켜져 있었습니다.

요청 기반 지표의 한계

요청이 지나가야 만들어지는 지표는 ‘요청이 없음’과 ‘복구됨’을 구별하지 못합니다. 실제로 모델이 살아 있는지 확인하려면 일정 간격으로 모델을 직접 호출해 보는 능동 점검이 따로 필요합니다. 이번 편에서는 한계만 확인했습니다.

트레이스로 요청 하나 들여다보기

Grafana Explore에서 Tempo를 고르고, 실제 모델 호출만 걸러 냈습니다.

{resource.service.name="litellm" && name="Received Proxy Server Request" && duration > 500ms}
Grafana Explore Tempo에서 litellm 서비스의 Received Proxy Server Request 중 500ms 넘는 트레이스를 검색한 목록. 23시 10분부터 13분 사이 4~10초짜리 요청들과 23시 13분 50초 13.6초짜리 요청이 보임
Tempo 검색: 0.5초 넘는 LiteLLM 요청

목록의 4~10초짜리는 장애 훈련 2에서 Ollama가 멈춘 동안 재시도 끝에 실패한 요청이고, 13.6초짜리는 재시작 직후 첫 성공 요청입니다. 13.6초 트레이스를 열었습니다.

Tempo 트레이스 상세. litellm Received Proxy Server Request 13.62초, 상태 200, 스팬 7개. auth 785.92µs, proxy_pre_call 70.4µs, router 13.61s, 안쪽 router 432.9µs, litellm_request 13.6s, self 13.6s 막대
Ollama 재시작 직후 첫 요청의 스팬

인증(auth) 0.79ms, 사전 처리 0.07ms, 모델 선택(router) 0.43ms로 게이트웨이 단계는 모두 합쳐 1ms 남짓이고, 나머지 13.6초는 모델 호출(litellm_request)입니다. Ollama가 모델을 메모리에 다시 올리는 시간이 그대로 보입니다.

같은 트레이스의 루트 스팬 속성. http.response.status_code 200, http.route /v1/chat/completions, litellm.preprocessing.duration_ms 18.26, 리소스 속성 service.name litellm, deployment.environment production, k8s.namespace.name ai, k8s.node.name lab-worker, k8s.pod.name, telemetry.sdk python opentelemetry 1.45.2
루트 스팬의 속성

루트 스팬의 리소스 속성에는 네임스페이스·노드·파드 이름이 붙어 있습니다. LiteLLM이 보낸 값이 아니라 OTel Collector의 쿠버네티스 속성 처리기가 붙인 값이라, 느린 요청이 어느 파드에서 처리됐는지 바로 찾을 수 있습니다. deployment.environment는 설정하지 않았는데 production으로 찍혀 있었습니다. 여러 환경을 함께 쓴다면 이 값을 직접 지정해야 구분됩니다. 모델 이름·토큰 수는 루트가 아니라 litellm_request 스팬에 있고, 질문·답 본문은 어느 스팬에도 없었습니다.

관측이 만드는 잡음: 30초마다 생기는 트레이스

처음에 조건 없이 {resource.service.name="litellm"}만 검색했을 때는 목록이 짧은 트레이스로 가득했습니다.

Tempo에서 litellm 서비스 트레이스를 조건 없이 검색한 목록. 대부분 root span not yet received로 표시되고 1~13ms짜리이며 약 30초 간격으로 나타남
Tempo 검색: 조건 없이 본 LiteLLM 트레이스

대부분 <root span not yet received>이고 1~13ms이며 약 30초 간격이었습니다. 하나를 열어 보니 스팬은 /metrics/ 요청의 키 확인(auth)과 키 조회(postgres)뿐이었습니다. Prometheus가 30초마다 지표를 가져갈 때마다 트레이스가 하나씩 생긴 것이고, LiteLLM이 이 요청의 루트 스팬은 만들지 않아 “root 없음”으로 보였습니다.

지표 수집만으로 하루 약 2,880개의 트레이스가 쌓이는 셈입니다. 검색할 때 위처럼 name="Received Proxy Server Request" 조건을 붙이거나, Collector에서 이런 스팬을 걸러 내는 규칙을 추가하면 줄일 수 있습니다. 이번에는 공유 설정인 Collector는 건드리지 않았습니다.

핵심 요약

항목 내용
켜기 callbacks: [prometheus, otel], turn_off_message_logging: true
/metrics 관리자 전용. proxy_admin_viewer 사용자의 키로 수집, 경로는 /metrics/
게이트웨이 지연 평균 약 0.03초. 응답 시간은 거의 전부 모델 호출
PromQL 함정 새 키의 첫 요청은 increase()에 안 잡힘 → 누적값 사용
경보 함정 deployment_state는 전체 장애에도 1에서 멈춤 → 5xx 실패율로 판단
한계 요청 기반 지표는 요청 없음과 복구됨을 구별 못함 → 능동 점검 필요

자주 묻는 질문

LiteLLM /metrics가 401을 돌려줘요.

v1.85.0부터 /metrics는 키 인증이 필요하고, 일반 가상 키가 아니라 관리자 역할의 키만 읽을 수 있었습니다. 읽기 전용 관리자(proxy_admin_viewer) 사용자의 키를 쓰거나 require_auth_for_metrics_endpoint: false로 인증을 끌 수 있습니다.

LiteLLM 트레이스에 질문 내용이 남나요?

기본으로 남습니다. litellm_settings.turn_off_message_logging: true로 끄면 본문은 빠지고 모델·토큰·비용 같은 메타데이터만 남습니다.

litellm_deployment_state로 장애 경보를 걸어도 되나요?

이번 실습에서는 Ollama를 완전히 멈춰도 값이 1에서 멈췄고, 요청이 없으면 옛 값이 남았습니다. 모델 그룹별 5xx 실패율 같은 요청 결과 기반 조건과 주기적인 능동 점검을 함께 쓰는 편이 안전합니다.

게이트웨이를 거치면 응답이 얼마나 느려지나요?

이번 측정에서 평균 약 0.03초였습니다. 인증·키 조회·라우팅을 합친 시간이고, 나머지는 모델 호출 시간이었습니다.

작성 방식과 다음 편

이 글의 지표, 트레이스, 경보 시각은 모두 앞선 편과 같은 kind 클러스터에서 직접 실행한 결과이고, 설정은 LiteLLM 공식 문서를 기준으로 했습니다. 키 값은 Secret에만 두고 기록과 화면에 남기지 않았으며, 실행 기록 정리와 글 작성에 AI 도구를 함께 썼습니다. 다음 편에서는 Open WebUI를 올려 LiteLLM을 백엔드로 연결하고, 브라우저에서 쓰는 채팅 화면을 만들 예정입니다.

사진을 누르면 원본 크기