📈 Prometheus 메트릭

📈 Prometheus 메트릭

LiteLLM은 Prometheus가 폴링할 수 있는 /metrics 엔드포인트를 노출해요. 지출, 토큰 사용량, 레이트 리밋, 예산, 레이턴시, 가드레일, MCP, 관리형 배치 등 프록시의 거의 모든 측면을 시계열 메트릭으로 추적할 수 있어요.

프록시 설정의 callbacks에 prometheus를 추가해 켜고, 기본적으로 /metrics는 LiteLLM API 키 인증을 요구해요(v1.85.0부터).

출처: 문서

본문

LiteLLM은 Prometheus가 폴링할 수 있는 /metrics 엔드포인트를 노출해요.

빠른 시작 (Quick Start)

LiteLLM CLI를 litellm --config proxy_config.yaml로 쓴다면 uv add prometheus_client==0.20.0가 필요해요. 이것은 litellm 도커 이미지에 미리 설치돼 있어요.

프록시 config.yaml에 다음을 추가하세요:

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: gpt-5.6-terra
    litellm_settings:
      callbacks:
        - prometheus

프록시 시작:

    litellm --config config.yaml --debug

테스트 요청:

    curl --location 'http://0.0.0.0:4000/chat/completions' \
        --header 'Content-Type: application/json' \
        --data '{
        "model": "gpt-5.6-terra",
        "messages": [
            {
            "role": "user",
            "content": "what llm are you"
            }
        ]
    }'

/metrics에서 메트릭 보기:

    curl http://localhost:4000/metrics \
      -H "Authorization: Bearer ***"

여러 워커 (Multiple Workers)

여러 워커로 LiteLLM을 쓰면 워커 프로세스 간 집계 메트릭 수집을 활성화하기 위해 PROMETHEUS_MULTIPROC_DIR 환경 변수를 설정해야 해요.

    export PROMETHEUS_MULTIPROC_DIR="/prometheus_multiproc"

이 디렉터리는 Prometheus 클라이언트 라이브러리가 여러 워커 프로세스 간 공유할 메트릭 파일을 저장하는 데 써요. 디렉터리가 존재하고 LiteLLM 프로세스가 쓸 수 있는지 확인하세요.

Prometheus 스크래핑을 추론 트래픽에서 분리하기

기본적으로 LiteLLM은 추론 요청을 서빙하는 같은 Uvicorn 워커들을 사용해 프록시 포트에 /metrics를 렌더링해요. 멀티 워커 배포에서 각 스크래핑은 작업자 간 Prometheus 데이터를 집계해요. 크거나 높은 카디널리티의 메트릭 세트는 요청 서빙 워커의 CPU를 소모하고 꼬리 지연을 높일 수 있어요.

LiteLLM v1.101.0 이상은 전용 프로세스에서 같은 메트릭 세트를 서빙할 수 있어요. --prometheus_metrics_port 또는 PROMETHEUS_METRICS_PORT를 구성한 뒤 Prometheus가 그 포트를 스크래핑하도록 업데이트하세요. 프록시 포트의 기존 /metrics 라우트는 하위 호환성을 위해 유지되므로, 추론 트래픽을 중단하지 않고 스크래핑 대상을 옮길 수 있어요.

prometheus 콜백이 활성화되어야 해요. 전용 포트가 구성되면 LiteLLM은 필요 시 PROMETHEUS_MULTIPROC_DIR을 만들고, 메트릭 프로세스를 프록시 --host에 바인딩하며, 프록시와 함께 프로세스를 중지해요.

    litellm --config config.yaml --num_workers 4 --prometheus_metrics_port 4001

prometheus.yml:

    scrape_configs:
      - job_name: litellm
        static_configs:
          - targets: ["litellm:4001"]

메트릭 리스너 보안

전용 리스너는 LiteLLM 가상 키 인증을 사용하지 않아요. require_auth_for_metrics_endpoint는 프록시 포트의 /metrics에만 적용돼요. 신뢰할 수 있는 Prometheus 또는 수집기 네트워크에서만 접근을 허용하고, 전용 포트를 공개 인그레스나 로드 밸런서로 게시하지 마세요.

배포 구성

• Helm: litellm-helm
• Helm: componentized
• Terraform: AWS

values.yaml:

    metricsServer:
      enabled: true
      port: 4001

    serviceMonitor:
      enabled: true

차트는 전용 <release>-litellm-metrics ClusterIP Service를 만들고 ServiceMonitor를 그것으로 향하게 해요. 기본 Service는 service.type이 LoadBalancer일 때도 변하지 않아요. metricsServer.port는 service.port와 달라야 해요.

values.yaml:

    gateway:
      metricsServer:
        enabled: true
        port: 4001

차트는 메트릭 서버를 게이트웨이와 Prometheus 멀티프로세스 데이터를 공유하는 사이드카로 실행해요. 전용 <release>-litellm-gateway-metrics ClusterIP Service를 통해 리스너를 노출하므로, Prometheus가 그 프라이빗 Service를 발견하도록 구성하세요. 게이트웨이 Service는 그대로예요.

main.tf:

    module "litellm" {
      source  = "BerriAI/litellm/aws"
      version = "~> 1.101"

      gateway_metrics_port         = 4001
      gateway_metrics_scrape_cidrs = ["10.0.0.0/16"]
    }

모듈은 게이트웨이 태스크에 비필수 메트릭 사이드카를 추가하고 gateway_metrics_scrape_cidrs에서만 해당 포트 인바운드 트래픽을 허용해요. Application Load Balancer는 메트릭 포트로 라우팅하지 않아요. gateway_metrics_port가 null(기본값)이면 기능이 비활성화되고, 포트 4000은 게이트웨이 트래픽용으로 예약돼요.

롤아웃 검증하기

Prometheus 대상을 바꾸기 전에 전용 프로세스를 확인하세요:

    curl -fsS http://litellm:4001/health
    # {"status":"healthy","multiproc_dir":"..."}

    curl -fsS http://litellm:4001/metrics/ | head

전용 엔드포인트는 프록시 포트 엔드포인트와 같은 메트릭, 라벨 구성, 필터링, 압축을 지원해요. 프록시 readiness는 포트 4000의 /health/readiness에서 그대로 사용할 수 있어요.

가상 키, 팀, 내부 사용자

user, key, team 등별 추적에 사용해요.

메트릭 이름	설명
litellm_spend_metric	총 지출. "end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email", "client_ip", "user_agent", "requested_model", "model_id", "api_provider", "service_tier"별
litellm_total_tokens_metric	"end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email", "requested_model", "model_id", "api_provider"별 입력 + 출력 토큰
litellm_input_tokens_metric	"end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email", "requested_model", "model_id", "api_provider"별 입력 토큰
litellm_output_tokens_metric	"end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email", "requested_model", "model_id", "api_provider"별 출력 토큰

토큰 유형 상세 메트릭

공급자가 보고하는 usage.prompt_tokens_details와 usage.completion_tokens_details 필드(예: OpenAI 프롬프트 캐싱, Anthropic 프롬프트 캐싱, audio I/O, reasoning 토큰)를 분해하는 토큰 유형별 카운터예요. 이것들은 위 총계에 **추가(additive)**되며, 기존 litellm_input_tokens_metric / litellm_output_tokens_metric / litellm_total_tokens_metric 카운터는 그대로예요.

각 상세 카운터는 **희소(sparse)**해요: 공급자가 해당 필드에 대해 0이 아닌 값을 보고할 때만 증가하므로, 특정 상세를 노출하지 않는 공급자는 그에 대한 series를 만들지 않아요. 라벨 집합은 부모 입력/출력 토큰 카운터와 동일해 PromQL에서 깔끔하게 조인할 수 있어요.

메트릭 이름	usage의 소스 필드	일반 공급자
litellm_input_cached_tokens_metric	prompt_tokens_details.cached_tokens	OpenAI 프롬프트 캐시, Anthropic cache_read_input_tokens, DeepSeek prompt_cache_hit_tokens
litellm_input_cache_creation_tokens_metric	prompt_tokens_details.cache_creation_tokens	Anthropic cache_creation_input_tokens (프롬프트 캐시 쓰기)
litellm_input_audio_tokens_metric	prompt_tokens_details.audio_tokens	OpenAI gpt-4o-audio-*, Gemini 오디오 입력
litellm_output_reasoning_tokens_metric	completion_tokens_details.reasoning_tokens	OpenAI o1-* / o3-*, Anthropic extended thinking
litellm_output_audio_tokens_metric	completion_tokens_details.audio_tokens	OpenAI gpt-4o-audio-* 오디오 출력

모델 그룹의 캐시 적중 비율 PromQL 예시:

    sum by (requested_model) (rate(litellm_input_cached_tokens_metric_total[5m]))
    /
    sum by (requested_model) (rate(litellm_input_tokens_metric_total[5m]))

출력 중 reasoning 토큰 비율 PromQL 예시:

    sum by (requested_model) (rate(litellm_output_reasoning_tokens_metric_total[5m]))
    /
    sum by (requested_model) (rate(litellm_output_tokens_metric_total[5m]))

info

litellm_input_cached_tokens_metric은 공급자 측 프롬프트 캐시 읽기(공급자가 입력의 캐시된 일부를 보고)를 추적해요. 이것은 LiteLLM 자체 응답 캐시 적중(전체 응답이 LiteLLM 캐시에서 서빙되고 공급자 요청이 없음)을 추적하는 litellm_cached_tokens_metric과 달라요.

캐시 메트릭

LiteLLM 자체 응답 캐시를 추적해요. 세 메트릭 모두 "model", "hashed_api_key", "api_key_alias", "team", "team_alias", "end_user", "user", "model_id", "api_provider" 라벨을 가져요.

메트릭 이름	설명
litellm_cache_hits_metric	LiteLLM 응답 캐시에서 완전히 서빙된 요청 (공급자 요청 없음)
litellm_cache_misses_metric	LiteLLM 응답 캐시를 빗나간 요청
litellm_cached_tokens_metric	LiteLLM 응답 캐시에서 서빙된 토큰

팀 - 예산

메트릭 이름	설명
litellm_team_max_budget_metric	팀의 최대 예산 라벨: "team", "team_alias"
litellm_remaining_team_budget_metric	팀의 남은 예산 (LiteLLM에서 만든 팀) 라벨: "team", "team_alias"
litellm_team_budget_remaining_hours_metric	팀 예산이 리셋되기까지 남은 시간 라벨: "team", "team_alias"

가상 키 - 예산

메트릭 이름	설명
litellm_api_key_max_budget_metric	API 키의 최대 예산 라벨: "hashed_api_key", "api_key_alias"
litellm_remaining_api_key_budget_metric	API 키의 남은 예산 (LiteLLM에서 만든 키) 라벨: "hashed_api_key", "api_key_alias"
litellm_api_key_budget_remaining_hours_metric	API 키 예산이 리셋되기까지 남은 시간 라벨: "hashed_api_key", "api_key_alias"

내부 사용자 - 예산

내부 사용자에 연결된 요청에서만 발행되며, 최대 예산과 리셋 시간 게이지는 사용자에게 예산이 설정된 경우에만 요구돼요. 모든 사용자에 대해 스케줄로 발행하려면 Starter에서 Budget Metrics 초기화를 사용하세요.

메트릭 이름	설명
litellm_remaining_user_budget_metric	내부 사용자의 남은 예산 라벨: "user"
litellm_user_max_budget_metric	내부 사용자의 최대 예산 라벨: "user"
litellm_user_budget_remaining_hours_metric	내부 사용자 예산이 리셋되기까지 남은 시간 라벨: "user"

조직 - 예산

조직에 연결된 요청에서만 발행되며, 내부 사용자 메트릭과 같은 조건이 적용돼요.

메트릭 이름	설명
litellm_remaining_org_budget_metric	조직의 남은 예산 라벨: "org_id", "org_alias"
litellm_org_max_budget_metric	조직의 최대 예산 라벨: "org_id", "org_alias"
litellm_org_budget_remaining_hours_metric	조직 예산이 리셋되기까지 남은 시간 라벨: "org_id", "org_alias"

고객 (end_user) - 예산

end_user 추적이 켜져 있을 때만 발행돼요. 각 요청에서 인증 중 캐시된 고객 행에서 해당 요청의 고객에 대해 남은·최대 예산 게이지가 갱신돼요(추가 DB 쿼리 없음. 캐시 미스는 주기적 갱신에 맡김). 리셋 시간 게이지와 최근 트래픽이 없는 고객은 예산이 붙은 모든 고객에 대해 세 게이지를 모두 발행하는 Startup에서 Budget Metrics 초기화가 다뤄요. max_end_user_budget_id가 설정되면 자체 예산이 없는 고객은 그 기본 예산에 대해 발행돼요. 이 시리즈는 Prometheus에서 end_user 추적에 설명된 end_user 카디널리티 상한의 적용을 받아요.

메트릭 이름	설명
litellm_remaining_customer_budget_metric	고객의 남은 예산 라벨: "end_user"
litellm_customer_max_budget_metric	고객의 최대 예산 라벨: "end_user"
litellm_customer_budget_remaining_hours_metric	고객 예산이 리셋되기까지 남은 시간 라벨: "end_user"

가상 키 - 레이트 리밋

메트릭 이름	설명
litellm_remaining_api_key_requests_for_model	LiteLLM 가상 API 키의 남은 요청 수. 가상 키에 모델별 레이트 리밋(rpm)이 설정된 경우에만. 라벨: "hashed_api_key", "api_key_alias", "model", "model_id"
litellm_remaining_api_key_tokens_for_model	LiteLLM 가상 API 키의 남은 토큰 수. 가상 키에 모델별 토큰 제한(tpm)이 설정된 경우에만. 라벨: "hashed_api_key", "api_key_alias", "model", "model_id"

Startup에서 Budget Metrics 초기화

요청을 받고 있든 아니든 모든 키·팀의 예산 메트릭을 litellm이 발행하게 하려면 config.yaml에서 prometheus_initialize_budget_metrics를 true로 설정하세요.

동작 방식:

• prometheus_initialize_budget_metrics가 true로 설정되면
  • 5분마다 litellm이 cron 잡으로 데이터베이스에서 모든 키, 팀, 내부 사용자, 조직을 읽어요
  • 그런 다음 각각에 대해 예산 메트릭을 발행해요
  • 이는 /metrics 엔드포인트의 예산 메트릭을 채우는 데 사용돼요

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_initialize_budget_metrics: true

팟 헬스 메트릭 (Pod Health Metrics)

팟별 큐 깊이를 측정하고, LiteLLM이 요청 처리를 시작하기 전에 발생하는 레이턴시를 진단하는 데 사용해요.

메트릭 이름	타입	설명
litellm_in_flight_requests	Gauge	이 uvicorn 워커에서 현재 처리 중인 HTTP 요청 수. 팟의 큐 깊이를 실시간 추적. 워커가 여러 개면 모든 활성 워커에 걸쳐 합산(livesum)
litellm_admission_admitted_requests	Gauge	현재 워커별 admission 슬롯을 보유한 요청 수. per-worker admission control이 켜져 있을 때만 채워짐. 활성 워커에 걸쳐 합산(livesum)
litellm_admission_queued_requests	Gauge	워커별 admission 슬롯을 기다리는 요청 수. 활성 워커에 걸쳐 합산(livesum)
litellm_admission_rejected_requests_total	Counter	admission control이 503으로 거부한 요청 수, reason 라벨: queue_full(도착 시 큐가 이미 최대) 또는 queue_timeout(admission_queue_timeout_seconds를 기다려도 슬롯을 못 얻음)

언제 이것을 쓸까

LiteLLM은 자체 핸들러가 시작하는 시점부터 레이턴시를 측정해요. 핸들러가 실행되기 전에 요청이 uvicorn의 이벤트 루프에서 기다린다면, 그 대기는 LiteLLM 자체 로그에 보이지 않아요. litellm_in_flight_requests는 그 시점의 팟 부하를 보여줘요.

    high in_flight_requests + high ALB TargetResponseTime → pod overloaded, scale out
    low  in_flight_requests + high ALB TargetResponseTime → delay is pre-ASGI (event loop blocking)

Prometheus 없이도 현재 값을 직접 확인할 수 있어요:

    curl http://localhost:4000/health/backlog \
      -H "Authorization: Bearer ***"
    # {"in_flight_requests": 47}

프록시 레벨 추적 메트릭

전체 LiteLLM Proxy 사용량 추적에 사용해요.

• 프록시로의 실제 트래픽 속도 추적
• 프록시에 대한 요청의 클라이언트 측 요청·실패 수

메트릭 이름	설명
litellm_proxy_failed_requests_metric	프록시의 실패 응답 총 수 - 클라이언트가 litellm 프록시에서 성공 응답을 받지 못함. 라벨: "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "user_email", "exception_status", "exception_class", "route", "client_ip", "user_agent", "model_id", "api_provider"
litellm_proxy_total_requests_metric	프록시 서버에 대한 요청 총 수 - 클라이언트 측 요청 수 추적. 라벨: "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "status_code", "user_email", "route", "client_ip", "user_agent", "model_id", "api_provider". 선택적으로 "stream" 포함 - Emit Stream Label 참고

콜백 로깅 메트릭

S3 콜드 스토리지 같은 다운스트림 콜백으로 로그를 보내는 실패를 모니터링해요.

메트릭 이름	설명
litellm_callback_logging_failures_metric	구성된 콜백으로 로그 발행 시도 실패 총 수. 라벨: "callback_name". S3, langfuse, langfuse_otel 및 기타 otel 공급자에 쓸 때 반복 실패 같은 콜백 전달 문제에 알림을 씀

지원 콜백:

• S3Logger - S3 콜드 스토리지 실패
• langfuse - Langfuse 로깅 실패
• otel - OpenTelemetry 로깅 실패

가드레일 메트릭

가드레일이 실행될 때만 발행돼요.

메트릭 이름	설명
litellm_guardrail_requests_total	가드레일 호출 총 수. 라벨: "guardrail_name", "status", "hook_type"
litellm_guardrail_errors_total	가드레일 실행 중 만난 오류 총 수. 라벨: "guardrail_name", "error_type", "hook_type"
litellm_guardrail_latency_seconds	가드레일 실행 레이턴시(초) 히스토그램. 라벨: "guardrail_name", "status", "error_type", "hook_type"

MCP 게이트웨이 메트릭

MCP 게이트웨이를 통해 만든 MCP 도구 호출에서만 발행돼요. 두 메트릭 모두 "mcp_tool_name", "mcp_server_name", "hashed_api_key", "api_key_alias", "team", "team_alias", "user", "end_user" 라벨을 가져요.

메트릭 이름	설명
litellm_mcp_tool_calls_total	도구·서버 이름별로 세그먼트된 총 MCP 도구 호출 수
litellm_mcp_tool_call_spend_metric	MCP 도구 호출의 총 지출. 호출에 0이 아닌 비용이 있을 때만 증가

관리형 배치 메트릭 (Managed Batch Metrics)

Enterprise 전용. LiteLLM 관리형 배치와 그것을 비용 추적하는 CheckBatchCost 백그라운드 잡을 사용할 때 발행돼요.

메트릭 이름	설명
litellm_managed_batch_created_total	생성된 관리형 배치 총 수. 라벨: "model", "api_provider", "user", "user_email", "api_key_alias"
litellm_managed_file_created_total	생성된 관리형 파일 총 수. 라벨: "model", "api_provider", "user", "user_email", "api_key_alias"
litellm_managed_file_deleted_total	관리형 파일 삭제 총 수, 성공 또는 차단. 라벨: "result"
litellm_managed_file_size_bytes	가장 최근 관리형 배치 파일의 크기(바이트), 라벨 조합별 마지막으로 본 값. 라벨: "purpose", "file_type", "model", "api_provider", "user"
litellm_managed_batch_duration_seconds	완료된 배치의 지속 시간(초) 히스토그램 (completed_at - created_at). 라벨: "model", "api_provider"
litellm_check_batch_cost_jobs_polled	마지막 CheckBatchCost 폴링이 찾은 미처리 배치 수
litellm_check_batch_cost_jobs_processed_total	CheckBatchCost가 성공적으로 비용 추적한 배치 총 수. 라벨: "model", "api_provider"
litellm_check_batch_cost_errors_total	오류 유형별 CheckBatchCost 오류 총 수. 라벨: "error_type"
litellm_check_batch_cost_last_run_timestamp	마지막 CheckBatchCost 잡 실행의 Unix 타임스탬프

LLM 공급자 메트릭

LLM API 오류 모니터링과 남은 레이트 리밋·토큰 제한 추적에 사용해요.

추적되는 라벨

라벨	설명
litellm_model_name	LiteLLM이 사용하는 LLM 모델의 이름
requested_model	요청에 보낸 모델
model_id	디플로이먼트의 model_id. LiteLLM이 자동 생성, 각 디플로이먼트는 고유 model_id
api_base	디플로이먼트의 API 베이스
api_provider	LLM API 공급자. 예: (azure, openai, vertex_ai)
hashed_api_key	요청의 해시된 api 키
api_key_alias	사용된 api 키의 별칭
team	요청의 팀
team_alias	사용된 팀의 별칭
exception_status	있으면 예외 상태
exception_class	있으면 예외 클래스

성공과 실패

메트릭 이름	설명
litellm_deployment_success_responses	디플로이먼트의 성공적인 LLM API 호출 총 수. 라벨: "requested_model", "litellm_model_name", "model_id", "api_base", "api_provider", "hashed_api_key", "api_key_alias", "team", "team_alias", "client_ip", "user_agent"
litellm_deployment_failure_responses	특정 LLM 디플로이먼트의 실패한 LLM API 호출 총 수. 라벨: "requested_model", "litellm_model_name", "model_id", "api_base", "api_provider", "exception_status", "exception_class", "hashed_api_key", "api_key_alias", "team", "team_alias", "client_ip", "user_agent"
litellm_deployment_total_requests	디플로이먼트의 LLM API 호출 총 수 - 성공 + 실패. 라벨: "requested_model", "litellm_model_name", "model_id", "api_base", "api_provider", "hashed_api_key", "api_key_alias", "team", "team_alias", "client_ip", "user_agent"

남은 요청과 토큰

메트릭 이름	설명
litellm_remaining_requests_metric	LLM API 디플로이먼트에서 반환된 x-ratelimit-remaining-requests 추적. 라벨: "model_group", "api_provider", "api_base", "litellm_model_name", "hashed_api_key", "api_key_alias", "model_id"
litellm_remaining_tokens_metric	LLM API 디플로이먼트에서 반환된 x-ratelimit-remaining-tokens 추적. 라벨: "model_group", "api_provider", "api_base", "litellm_model_name", "hashed_api_key", "api_key_alias", "model_id"

공급자 예산

메트릭 이름	설명
litellm_provider_remaining_budget_metric	LLM 공급자의 남은 예산. provider budget routing이 구성될 때만 발행. 라벨: "api_provider"

디플로이먼트 상태

메트릭 이름	설명
litellm_deployment_state	디플로이먼트의 상태: 0 = 정상, 1 = 부분 장애, 2 = 완전 장애. 라벨: "litellm_model_name", "model_id", "api_base", "api_provider"
litellm_deployment_latency_per_output_token	디플로이먼트의 출력 토큰당 레이턴시. 라벨: "litellm_model_name", "model_id", "api_base", "api_provider", "hashed_api_key", "api_key_alias", "team", "team_alias"
litellm_deployment_tpm_limit	디플로이먼트의 구성된 TPM 제한. config에 tpm 제한이 있는 디플로이먼트에서만 설정. 라벨: "litellm_model_name", "model_id", "api_base", "api_provider"
litellm_deployment_rpm_limit	디플로이먼트의 구성된 RPM 제한. config에 rpm 제한이 있는 디플로이먼트에서만 설정. 라벨: "litellm_model_name", "model_id", "api_base", "api_provider"

폴백 (Failover) 메트릭

메트릭 이름	설명
litellm_deployment_cooled_down	LiteLLM 로드 밸런싱 로직이 디플로이먼트를 쿨다운한 횟수. 라벨: "litellm_model_name", "model_id", "api_base", "api_provider", "exception_status"
litellm_deployment_successful_fallbacks	primary 모델에서 폴백 모델로의 성공적인 폴백 요청 수. 라벨: "requested_model", "fallback_model", "hashed_api_key", "api_key_alias", "team", "team_alias", "exception_status", "exception_class", "model_id"
litellm_deployment_failed_fallbacks	primary 모델에서 폴백 모델로의 실패한 폴백 요청 수. 라벨: "requested_model", "fallback_model", "hashed_api_key", "api_key_alias", "team", "team_alias", "exception_status", "exception_class", "model_id"

요청 카운팅 메트릭

메트릭 이름	설명
litellm_requests_metric	deprecated litellm_proxy_total_requests_metric 사용. API 키, 팀, 사용자별로 추적되는 litellm에 대한 LLM 호출 총 수. 라벨: "end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email", "client_ip", "user_agent", "requested_model", "model_id", "api_provider"
litellm_zero_cost_requests_total	usage를 가졌지만 가격 항목의 요율이 0이 아닌 모델에서 $0으로 기록된 요청. 무료 모델과 usage 없는 요청은 카운트되지 않음. 라벨: "requested_model", "model", "model_id", "api_provider", "reason"에서 reason은 missing_pricing_key, pricing_not_applied, cost_calculation_error. 카운트된 각 요청은 누락된 가격 키를 이름으로 쓰는 경고 하나도 기록함. Requests that price to $0 참고

요청 레이턴시 메트릭

레이턴시 SLO와 알림에는 litellm_request_total_latency_metric을 사용해요. 프록시 도착부터 처리 종료까지 전체 요청을 측정해요. 총 레이턴시가 늘면 다른 메트릭으로 지연이 인증, LLM 공급자, LiteLLM 처리 중 어디서 오는지 식별하세요.

모든 요청 레이턴시 메트릭은 초 단위로 측정되는 Prometheus 히스토그램이에요.

측정하려는 것	메트릭	측정 창
엔드 투 엔드 레이턴시	litellm_request_total_latency_metric	요청 도착부터 처리 종료까지. 인증, pre-call 훅, LLM API 호출, post-call 처리 포함
인증과 요청 대기 시간	litellm_request_queue_time_seconds	요청 도착부터 pre-call 처리 시작까지. 인증과 ASGI 레벨 큐잉 포함. 로드된 프록시 팟 진단 시 litellm_in_flight_requests와 비교
LLM 공급자 레이턴시	litellm_llm_api_latency_metric	LLM API 호출 시작부터 끝까지
첫 토큰까지 시간	litellm_llm_api_time_to_first_token_metric	LLM API 호출 시작부터 첫 토큰까지. 스트리밍 요청에서만 발행
LiteLLM 처리 오버헤드	litellm_overhead_latency_metric	LLM API 호출과 가드레일을 제외한 LiteLLM 처리 시간
LiteLLM 처리·가드레일 오버헤드	litellm_overhead_with_guardrails_latency_metric	LiteLLM 처리 시간 + pre-call·post-call 가드레일, LLM API 호출 제외. 호출 중 가드레일은 LLM API 호출과 동시에 실행되며 포함되지 않음

예를 들어 다음 쿼리는 지난 5분간 엔드 투 엔드 p95 레이턴시를 반환해요:

    histogram_quantile(0.95, sum by (le) (rate(litellm_request_total_latency_metric_bucket[5m])))

요청 레이턴시 메트릭의 라벨:

메트릭	라벨
litellm_request_total_latency_metric litellm_llm_api_latency_metric litellm_llm_api_time_to_first_token_metric	end_user, hashed_api_key, api_key_alias, requested_model, team, team_alias, user, model, model_id, api_provider, service_tier
litellm_request_queue_time_seconds	end_user, hashed_api_key, api_key_alias, requested_model, team, team_alias, user, model, model_id, api_provider
litellm_overhead_latency_metric litellm_overhead_with_guardrails_latency_metric	model_group, api_provider, api_base, litellm_model_name, hashed_api_key, api_key_alias, model_id

litellm_request_queue_time_seconds는 공급자가 이 메트릭을 기록할 때 service tier를 선택하지 않았으므로 service_tier를 포함하지 않아요.

디플로이먼트·레이턴시 메트릭의 호출자 신원 구성

기본적으로 디플로이먼트 카운터와 호출자 범위 레이턴시 히스토그램은 호출자를 api_key_alias로 식별해요. prometheus_deployment_and_latency_caller_identity를 설정해 대신 user_email을 쓰거나 두 라벨을 모두 노출하세요:

config.yaml:

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_deployment_and_latency_caller_identity: user_email

값	호출자 신원 라벨	동작
api_key_alias (기본)	api_key_alias	기존 메트릭 스키마와 기존 쿼리 유지
user_email	user_email	라벨 스키마에서 같은 위치의 api_key_alias를 대체
both	api_key_alias, 그다음 user_email	두 차원 모두 발행. user_email은 api_key_alias 바로 뒤에 배치

이 설정은 다음 메트릭 패밀리에만 적용돼요:

• litellm_deployment_total_requests
• litellm_deployment_success_responses
• litellm_deployment_failure_responses
• litellm_request_total_latency_metric
• litellm_llm_api_latency_metric
• litellm_llm_api_time_to_first_token_metric
• litellm_request_queue_time_seconds
• litellm_overhead_latency_metric
• litellm_deployment_latency_per_output_token

호출자 범위가 아닌 관련 메트릭이나 가드레일 포함 litellm_overhead_with_guardrails_latency_metric은 바꾸지 않아요. 카운터 샘플은 Prometheus _total 접미사를, 히스토그램 _bucket, _sum, _count 샘플은 선택한 신원 라벨을 받아요.

이메일이 해석되지 않은 요청은 LiteLLM의 기존 "None" 라벨 값을 사용해요. 예를 들어 다음 쿼리는 해석된 이메일별로 공급자 요청과 p95 엔드 투 엔드 레이턴시를 그룹화하면서 이메일이 없는 요청은 제외해요:

    sum by (user_email) (
      rate(litellm_deployment_total_requests_total{user_email!="None"}[5m])
    )

    histogram_quantile(
      0.95,
      sum by (user_email, le) (
        rate(litellm_request_total_latency_metric_bucket{user_email!="None"}[5m])
      )
    )

prometheus_metrics_config.include_labels는 선택된 모드에 대해 검증돼요. api_key_alias 모드에서는 api_key_alias를, user_email 모드에서는 user_email을, both 모드에서는 둘 중 하나 또는 둘 다 포함할 수 있어요. 유효하지 않은 모드 값은 수락되는 값을 명명한 ValueError로 프록시 시작을 실패시키고, user_email 모드가 영향을 받는 패밀리에서 include_labels: [api_key_alias]와 결합되면 두 설정을 명명하며 시작도 실패해요. prometheus_exclude_labels는 나중에 적용되며 두 신원 라벨 중 하나를 제거할 수 있어요. 예를 들어 전체적으로 both를 선택하고 api_key_alias를 제외하면 영향을 받는 패밀리에는 user_email만 남아요.

warning

이 설정을 바꾸면 고정 Prometheus 수집기 라벨 스키마가 바뀌어요. 변경 후 모든 LiteLLM Proxy/logger 프로세스를 재시작하세요. 라이브 구성 리로드로 기존 수집기를 재구축할 수 없어요.

이메일 주소는 민감한 데이터예요. 이메일 레벨 귀속이 필요할 때만 기본값을 바꾸고, /metrics 인증을 유지하며, 신뢰할 수 있는 Prometheus 스크래퍼로만 네트워크 접근을 제한하세요.

both는 관찰된 완전한 라벨 튜플마다 하나씩 series를 기록해요. 같은 요청에 대한 두 번째 series를 만들지 않아요. 별칭과 이메일이 안정적인 일대일 매핑이면 이메일 라벨을 추가해도 고유 series 수는 늘지 않아요. 별칭이 사용자 간 재사용되거나 매핑이 시간에 따라 바뀌거나 같은 별칭이 해석된 이메일과 부재 이메일로 모두 관찰되면 카디널리티가 늘 수 있어요.

service tier별 레이턴시·지출 세그먼트

요청 레이턴시 메트릭과 litellm_spend_metric의 service_tier 라벨은 요청이 실제로 실행된 티어를 담아요. 그래서 트래픽을 더 싸거나 더 빠른 티어로 옮기기 전후의 레이턴시와 비용을 비교할 수 있어요:

    histogram_quantile(0.95, sum by (service_tier, le) (rate(litellm_request_total_latency_metric_bucket[5m])))

값은 공급자가 서빙했다고 보고한 티어예요. 그래서 "service_tier": "auto"로 보낸 요청이 auto가 아니라 공급자가 고른 구체적인 티어(예: default) 아래에 나타나요. 공급자가 티어를 보고하지 않으면 요청에서 명명된 티어를 쓰고, 티어를 요청하지도 받지도 않은 요청은 빈 값으로 라벨링돼요.

Prometheus에서 end_user 추적

기본적으로 LiteLLM은 Prometheus에서 end_user를 추적하지 않아요. 이는 LiteLLM Proxy 메트릭의 카디널리티를 줄이기 위해서예요.

Prometheus에서 end_user를 추적하려면 다음을 할 수 있어요:

config.yaml:

    litellm_settings:
      callbacks: ["prometheus"]
      enable_end_user_cost_tracking_prometheus_only: true

end_user 라벨을 지니는 모든 메트릭(고객 예산 게이지 포함)은 prometheus_end_user_metrics_max_series_per_metric(기본 10000, 오래된 series가 먼저 버려짐)으로 메트릭당 상한되고, prometheus_end_user_metrics_ttl_seconds(기본 3600)보다 오래 유휴한 series는 제거돼요. 그 제한을 비활성화하려면 둘 중 하나를 null로 설정하세요.

config.yaml:

    litellm_settings:
      callbacks: ["prometheus"]
      enable_end_user_cost_tracking_prometheus_only: true
      prometheus_end_user_metrics_max_series_per_metric: 500
      prometheus_end_user_metrics_ttl_seconds: 1800

Emit Stream 라벨

요청을 스트리밍 vs 비-스트리밍으로 나누려면 litellm_proxy_total_requests_metric에 stream 라벨을 추가해요. 기본적으로 비활성화돼요.

config.yaml:

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_emit_stream_label: true

켜면 litellm_proxy_total_requests_metric에 값 "True", "False", "None"을 가진 stream 라벨이 추가돼요.

    litellm_proxy_total_requests_metric{..., stream="True"} 42
    litellm_proxy_total_requests_metric{..., stream="False"} 100

note

이 라벨은 옵트인이에요. 기존 메트릭에 새 라벨을 추가하면 카디널리티가 바뀌고 이 메트릭을 대상으로 하는 기존 Prometheus 쿼리/Grafana 대시보드가 깨지기 때문이에요. 새 배포에서만 켜거나 대시보드를 업데이트할 준비가 됐을 때만 켜세요.

[BETA] 커스텀 메트릭

위에 언급된 모든 이벤트에서 커스텀 메트릭을 Prometheus로 추적해요.

커스텀 메타데이터 라벨

1. config.yaml에서 커스텀 메타데이터 라벨을 정의해요

    model_list:
      - model_name: openai/gpt-5.6-terra
        litellm_params:
          model: openai/gpt-5.6-terra
          api_key: os.environ/OPENAI_API_KEY

    litellm_settings:
      callbacks: ["prometheus"]
      custom_prometheus_metadata_labels: ["metadata.foo", "metadata.bar"]

2. 커스텀 메타데이터 라벨로 요청을 보내요

• Curl 요청
• 키에서
• 팀에서

    curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ***' \
    -d '{
        "model": "openai/gpt-5.6-terra",
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What's in this image?"
              }
            ]
          }
        ],
        "max_tokens": 300,
        "metadata": {
            "foo": "hello world"
        }
    }'

    curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{
        "metadata": {
            "foo": "hello world"
        }
    }'

    curl -L -X POST 'http://0.0.0.0:4000/team/new' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{
        "metadata": {
            "foo": "hello world"
        }
    }'

3. 커스텀 메트릭을 위해 /metrics 엔드포인트를 확인해요

    ... "metadata_foo": "hello world" ...

커스텀 태그

더 나은 필터링·모니터링을 위해 특정 태그를 prometheus 라벨로 추적해요.

1. config.yaml에서 커스텀 태그를 정의해요

    model_list:
      - model_name: openai/gpt-5.6-terra
        litellm_params:
          model: openai/gpt-5.6-terra
          api_key: os.environ/OPENAI_API_KEY

    litellm_settings:
      callbacks: ["prometheus"]
      custom_prometheus_metadata_labels: ["metadata.foo", "metadata.bar"]
      custom_prometheus_tags:
        - "prod"
        - "staging"
        - "batch-job"
        - "User-Agent: RooCode/*"
        - "User-Agent: claude-cli/*"

2. 태그로 요청을 보내요

    curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer ***' \
    -d '{
        "model": "openai/gpt-5.6-terra",
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What's in this image?"
              }
            ]
          }
        ],
        "max_tokens": 300,
        "metadata": {
            "tags": ["prod", "user-facing"]
        }
    }'

3. 커스텀 태그 메트릭을 위해 /metrics 엔드포인트를 확인해요

    ... "tag_prod": "true", "tag_staging": "false", "tag_batch_job": "false" ...

커스텀 태그 동작 방식:

• 구성된 각 태그는 prometheus 메트릭의 boolean 라벨이 돼요
• 태그가 일치하면(정확 또는 와일드카드) 라벨 값은 "true", 그렇지 않으면 "false"예요
• 태그 이름은 prometheus 호환성을 위해 정리돼요 (예: "batch-job" → "tag_batch_job")
• *를 사용한 와일드카드 패턴 지원 (예: "User-Agent: RooCode/*"는 "User-Agent: RooCode/1.0.0"와 일치)

와일드카드 예시:

    litellm_settings:
      callbacks: ["prometheus"]
      custom_prometheus_tags:
        - "User-Agent: RooCode/*"
        - "User-Agent: claude-cli/*"

사용 사례:

• 환경 추적 (prod, staging, dev)
• 요청 유형 분류 (batch-job, user-facing, background)
• 기능 플래그 (new-feature, beta-users)
• 팀·서비스 식별 (team-a, service-xyz)
• User-Agent 추적 - Roo Code, Claude Code, Gemini CLI가 얼마나 쓰이는지 추적 (User-Agent: RooCode/*, User-Agent: claude-cli/*, User-Agent: gemini-cli/*)

메트릭과 라벨 구성 (Configuring Metrics and Labels)

성능을 최적화하고 카디널리티를 줄이기 위해 특정 메트릭을 선택적으로 활성화하고 포함할 라벨을 제어할 수 있어요.

특정 메트릭·라벨 활성화

prometheus_metrics_config에서 지정해 발행할 메트릭을 구성해요. 각 구성 그룹은 (조직용) group 이름과 활성화할 metrics 목록이 필요해요. 선택적으로 메트릭의 라벨을 필터링할 include_labels 목록을 포함할 수 있어요.

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: gpt-5.6-terra

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_metrics_config:
        # High-cardinality metrics with minimal labels
        - group: "proxy_metrics"
          metrics:
            - "litellm_proxy_total_requests_metric"
            - "litellm_proxy_failed_requests_metric"
          include_labels:
            - "hashed_api_key"
            - "requested_model"
            - "model_group"

LiteLLM 시작 시 메트릭이 올바르게 구성됐다면 컨테이너 로그에서 다음을 볼 수 있어요.

메트릭별 라벨 필터링

각 메트릭에 포함할 라벨을 제어해 카디널리티를 줄여요:

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_metrics_config:
        - group: "token_consumption"
          metrics:
            - "litellm_input_tokens_metric"
            - "litellm_output_tokens_metric"
            - "litellm_total_tokens_metric"
          include_labels:
            - "model"
            - "team"
            - "hashed_api_key"
        - group: "request_tracking"
          metrics:
            - "litellm_proxy_total_requests_metric"
          include_labels:
            - "status_code"
            - "requested_model"

고급 구성

다른 라벨 집합으로 여러 구성 그룹을 만들 수 있어요:

    litellm_settings:
      callbacks: ["prometheus"]
      prometheus_metrics_config:
        # High-cardinality metrics with minimal labels
        - group: "deployment_health"
          metrics:
            - "litellm_deployment_success_responses"
            - "litellm_deployment_failure_responses"
          include_labels:
            - "api_provider"
            - "requested_model"

        # Budget metrics with full label set
        - group: "budget_tracking"
          metrics:
            - "litellm_remaining_team_budget_metric"
          include_labels:
            - "team"
            - "team_alias"
            - "hashed_api_key"
            - "api_key_alias"
            - "model"
            - "end_user"

        # Latency metrics with performance-focused labels
        - group: "performance"
          metrics:
            - "litellm_request_total_latency_metric"
            - "litellm_llm_api_latency_metric"
          include_labels:
            - "model"
            - "api_provider"
            - "requested_model"

구성 구조:

• group: 관련 메트릭을 조직하기 위한 설명 이름
• metrics: 이 그룹에 포함할 메트릭 이름 목록
• include_labels: (선택) 이 메트릭에 포함할 라벨 목록

기본 동작: prometheus_metrics_config를 지정하지 않으면 모든 메트릭이 기본 라벨로 활성화돼요 (하위 호환).

메트릭·라벨 전역 제외

prometheus_metrics_config는 include 기반이라 유지하려는 모든 메트릭을 나열해야 해요. 메트릭이나 라벨의 작은 집합만 버리려면 전역 prometheus_exclude_metrics와 prometheus_exclude_labels 옵션을 대신 사용하세요. 나열되지 않은 것은 모두 기본 라벨로 활성 상태로 남고, 향후 LiteLLM 릴리스에서 추가되는 메트릭은 추가 구성 변경 없이 자동으로 발행돼요.

    litellm_settings:
      callbacks: ["prometheus"]
      # Drop these metrics entirely
      prometheus_exclude_metrics:
        - "litellm_input_tokens_metric"
        - "litellm_output_tokens_metric"
      # Drop these labels from every metric that would otherwise emit them
      prometheus_exclude_labels:
        - "hashed_api_key"
        - "api_key_alias"

두 목록 모두 시작 시 검증돼요. 알 수 없는 메트릭·라벨 이름은 구성 오류를 일으켜 오타가 즉시 드러나요. 제외가 항상 우선하므로 prometheus_exclude_metrics에 명명된 메트릭은 prometheus_metrics_config 그룹이 활성화해도 버려지고, prometheus_exclude_labels의 라벨은 그룹의 include_labels가 나열해도 제거돼요.

시스템 헬스 모니터링 (Monitor System Health)

litellm 인접 서비스(redis / postgres)의 헬스를 모니터링하려면:

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: gpt-5.6-terra
    litellm_settings:
      service_callback: ["prometheus_system"]

모니터링되는 각 서비스는 litellm_<service>_<type> 이름의 세 메트릭을 발행해요:

메트릭 이름	타입	설명
litellm_<service>_latency	Histogram	서비스 호출의 레이턴시(초)
litellm_<service>_failed_requests_total	Counter	서비스 호출 실패 수. 라벨: "error_class", "function_name" (무엇이 실패하는지 디버깅용)
litellm_<service>_total_requests_total	Counter	서비스 호출 총 수. 실패 카운터와 함께 오류율 계산에 사용

모니터링되는 서비스:

서비스	설명
redis	Redis 호출 (캐싱, 레이트 리밋 상태)
postgres	Postgres DB 호출 (키, 팀, 지출 로그). 예: litellm_postgres_latency, litellm_postgres_failed_requests_total, litellm_postgres_total_requests_total
auth	요청 인증 검사. 과부하된 DB로 인한 인증 느려짐에 유용
batch_write_to_db	DB로의 배치 지출/사용량 쓰기
reset_budget_job	주기적 예산 리셋 잡
router	LiteLLM 라우터 연산
proxy_pre_call	LLM API를 치기 전에 프록시가 실행하는 pre-call 훅
self	LiteLLM 자체 API 호출 처리

DB 실패 또는 느림 알림 예시:

    rate(litellm_postgres_failed_requests_total[5m]) > 0
    histogram_quantile(0.95, sum by (le) (rate(litellm_postgres_latency_bucket[5m]))) > 1

DB 트랜잭션 큐 헬스 메트릭

DB 트랜잭션 큐의 헬스를 모니터링하는 데 사용해요. 예: 인메모리와 redis 버퍼의 크기 모니터링.

메트릭 이름	설명	스토리지 타입
litellm_pod_lock_manager_size	어떤 팟이 데이터베이스에 업데이트를 쓸 락을 가졌는지 표시	Redis
litellm_in_memory_daily_spend_update_queue_size	인메모리 일별 지출 업데이트 큐의 항목 수. 각 사용자의 집계 지출 로그	In-Memory
litellm_redis_daily_spend_update_queue_size	Redis 일별 지출 업데이트 큐의 항목 수. 각 사용자의 집계 지출 로그	Redis
litellm_redis_daily_end_user_spend_update_queue_size	Redis 일별 end user 지출 업데이트 큐의 항목 수	Redis
litellm_redis_daily_agent_spend_update_queue_size	Redis 일별 agent 지출 업데이트 큐의 항목 수	Redis
litellm_in_memory_spend_update_queue_size	키, 사용자, 팀, 팀 멤버 등의 인메모리 집계 지출 값	In-Memory
litellm_redis_spend_update_queue_size	키, 사용자, 팀 등의 Redis 집계 지출 값	Redis

🔥 LiteLLM 유지 Grafana 대시보드

LiteLLM은 이 페이지의 litellm_* 메트릭용 Grafana 대시보드 두 개를 cookbook/litellm_proxy_server/grafana_dashboard 폴더에 유지해요. Dashboards > New > Import에서 JSON을 가져오고 안내가 나오면 Prometheus 데이터 소스를 고르세요.

All Prometheus Metrics 대시보드는 위 표의 모든 메트릭에 대한 패널을 주제별로 그룹지어 가져요: 트래픽, 레이턴시, 지출·토큰, 캐시, 디플로이먼트, 레이트 리밋, 예산, 가드레일, MCP, 관리형 파일·배치, 사용자·팀, 그리고 prometheus_system 서비스 메트릭과 DB 트랜잭션 큐 크기까지. 활성화하지 않은 기능의 패널은 비워 있고, 그 readme는 각 행에 어떤 설정이 필요한지 나열해요.

v2 대시보드는 모델 그룹별 요청 속도, 실패, 레이턴시, 남은-요청·남은-토큰 게이지의 간결한 보기로, 아래에 보여요.

Deprecated 메트릭

메트릭 이름	설명
litellm_llm_api_failed_requests_metric	deprecated litellm_proxy_failed_requests_metric 사용

/metrics 엔드포인트 인증

기본적으로 /metrics는 LiteLLM API 키 인증을 요구해요 (v1.85.0부터).

Prometheus의 경우 스크레이프 구성에 authorization을 추가하세요:

    scrape_configs:
      - job_name: 'litellm'
        authorization:
          type: Bearer
          credentials: <LITELLM_API_KEY>
        static_configs:
          - targets: ['localhost:4000']

인증 없는 접근을 허용하려면:

    litellm_settings:
      require_auth_for_metrics_endpoint: false

FAQ

_created vs. _total 메트릭이 뭔가요?

Python Prometheus 클라이언트는 모든 카운터·히스토그램 옆에 _created 샘플을 발행해요. 그것은 해당 series가 생성된 Unix 타임스탬프(보통 프로세스 시작 또는 처음 보는 라벨 조합)를 담고, 어떤 것도 세지 않아요.

카운팅 목적에는 _total 메트릭을 사용해야 해요.

더 알아보기 (Learn more)

• 가상 키
• LiteLLM 관리형 배치
• 서버 튜닝: per-worker admission control
• 가드레일