跳至主要内容

📈 Prometheus metrics

LiteLLM 公开了一个 /metrics 端点供 Prometheus 轮询

快速入门​

如果您在使用 LiteLLM CLI 并执行 litellm --config proxy_config.yaml，则需要运行 pip install prometheus_client==0.20.0。该库已预装在 litellm Docker 镜像中

将以下内容添加到您的 proxy config.yaml 中

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
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-4o",
    "messages": [
        {
        "role": "user",
        "content": "what llm are you"
        }
    ]
}'

查看 /metrics 指标，请访问 https://:4000/metrics

https://:4000/metrics

# <proxy_base_url>/metrics

多工作进程 (Multiple Workers)​

当使用具有多个工作进程 (worker) 的 LiteLLM 时，您需要设置 PROMETHEUS_MULTIPROC_DIR 环境变量，以启用跨工作进程的聚合指标收集。

export PROMETHEUS_MULTIPROC_DIR="/prometheus_multiproc"

该目录由 Prometheus 客户端库用于存储可跨多个工作进程共享的指标文件。请确保该目录存在且 LiteLLM 进程对其具有写入权限。

虚拟密钥、团队、内部用户​

用于跟踪每个 用户、密钥、团队等 的使用情况。

指标名称描述
litellm_spend_metric总消费额，按 "end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user" 分类
litellm_total_tokens_metric输入 + 输出 token 总数，按 "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "model" 分类
litellm_input_tokens_metric输入 token 数，按 "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "model" 分类
litellm_output_tokens_metric输出 token 数，按 "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "model" 分类

团队 - 预算​

指标名称描述
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_metricAPI 密钥最大预算，标签："hashed_api_key", "api_key_alias"
litellm_remaining_api_key_budget_metricAPI 密钥剩余预算（LiteLLM 上创建的密钥），标签："hashed_api_key", "api_key_alias"
litellm_api_key_budget_remaining_hours_metric距离 API 密钥预算重置的小时数，标签："hashed_api_key", "api_key_alias"

虚拟密钥 - 速率限制​

指标名称描述
litellm_remaining_api_key_requests_for_modelLiteLLM 虚拟 API 密钥的剩余请求数，仅当该虚拟密钥设置了特定于模型的速率限制 (rpm) 时有效。标签："hashed_api_key", "api_key_alias", "model"
litellm_remaining_api_key_tokens_for_modelLiteLLM 虚拟 API 密钥的剩余 token 数，仅当该虚拟密钥设置了特定于模型的 token 限制 (tpm) 时有效。标签："hashed_api_key", "api_key_alias", "model"

启动时初始化预算指标​

如果您希望 LiteLLM 为所有密钥和团队输出预算指标（无论它们是否有请求），请在 config.yaml 中将 prometheus_initialize_budget_metrics 设置为 true

工作原理

  • 如果 prometheus_initialize_budget_metrics 设置为 true：
    • LiteLLM 每 5 分钟运行一次定时任务，从数据库读取所有密钥和团队信息
    • 随后为每个密钥和团队输出预算指标
    • 这用于填充 /metrics 端点上的预算指标
litellm_settings:
  callbacks: ["prometheus"]
  prometheus_initialize_budget_metrics: true

Pod 健康指标​

使用这些指标衡量每个 Pod 的队列深度，并诊断在 LiteLLM 开始处理请求之前发生的延迟。

指标名称类型描述
litellm_in_flight_requestsGauge（仪表盘类型）当前在该 uvicorn 工作进程中处于处理中的 HTTP 请求数。实时跟踪 Pod 的队列深度。使用多个工作进程时，数值会跨所有活跃工作进程求和 (livesum)。

何时使用​

LiteLLM 从其处理器 (handler) 启动时开始衡量延迟。如果请求在处理器运行前就在 uvicorn 的事件循环中等待，LiteLLM 的日志无法感知该等待时间。litellm_in_flight_requests 显示了 Pod 在任何时间点的负载情况。

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 https://:4000/health/backlog \
  -H "Authorization: Bearer sk-..."
# {"in_flight_requests": 47}

代理层跟踪指标​

用于跟踪 LiteLLM 代理的整体使用情况。

  • 跟踪代理的实际流量速率
  • 客户端向代理发出的请求数和失败数
指标名称描述
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", "model_id"
litellm_proxy_total_requests_metric向代理服务器发出的请求总数 - 跟踪客户端发出的请求数量。标签："end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "status_code", "user_email", "route", "model_id"。可选择包含 "stream" — 请参阅 Emit Stream Label。

回调日志记录指标​

监控将日志发送到下游回调（如 s3_v3 冷存储）时的失败情况

指标名称描述
litellm_callback_logging_failures_metric向已配置的回调发出日志的失败尝试总数。标签："callback_name"。使用此指标对回调交付问题发出警报，例如写入 s3_v3, langfuse, 或 langfuse_otel 及其他 otel 提供商时出现的重复失败。

支持的回调

  • S3Logger - S3 v2 冷存储失败
  • langfuse - Langfuse 日志记录失败
  • otel - OpenTelemetry 日志记录失败

LLM 提供商指标​

用于 LLM API 错误监控，以及跟踪剩余速率限制和 token 限制

已跟踪的标签​

标签描述
litellm_model_nameLiteLLM 使用的 LLM 模型名称
requested_model请求中发送的模型
model_id部署的 model_id。由 LiteLLM 自动生成，每个部署都有唯一的 model_id
api_base部署的 API Base
api_providerLLM 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"
litellm_deployment_failure_responses特定 LLM 部署的失败 LLM API 调用总数。标签："requested_model", "litellm_model_name", "model_id", "api_base", "api_provider", "hashed_api_key", "api_key_alias", "team", "team_alias", "exception_status", "exception_class"
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"

剩余请求与 Token​

指标名称描述
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"
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"

部署状态​

指标名称描述
litellm_deployment_state部署状态：0 = 健康，1 = 部分中断，2 = 完全中断。标签："litellm_model_name", "model_id", "api_base", "api_provider"
litellm_deployment_latency_per_output_token部署的每个输出 token 的延迟。标签："litellm_model_name", "model_id", "api_base", "api_provider", "hashed_api_key", "api_key_alias", "team", "team_alias"

回退 (Failover) 指标​

指标名称描述
litellm_deployment_cooled_down部署被 LiteLLM 负载均衡逻辑冷却 (cool down) 的次数。标签："litellm_model_name", "model_id", "api_base", "api_provider"
litellm_deployment_successful_fallbacks从主模型成功回退到备用模型的请求数。标签："requested_model", "fallback_model", "hashed_api_key", "api_key_alias", "team", "team_alias", "exception_status", "exception_class"
litellm_deployment_failed_fallbacks从主模型回退到备用模型失败的请求数。标签："requested_model", "fallback_model", "hashed_api_key", "api_key_alias", "team", "team_alias", "exception_status", "exception_class"

请求计数指标​

指标名称描述
litellm_requests_metric按端点跟踪的请求总数。标签："end_user", "hashed_api_key", "api_key_alias", "model", "team", "team_alias", "user", "user_email"

请求延迟指标​

指标名称描述
litellm_request_total_latency_metric请求到达 LiteLLM 代理服务器的总延迟（秒）- 跟踪标签 "end_user", "hashed_api_key", "api_key_alias", "requested_model", "team", "team_alias", "user", "model", "model_id"
litellm_overhead_latency_metric由 LiteLLM 处理增加的延迟开销（秒）- 跟踪标签 "model_group", "api_provider", "api_base", "litellm_model_name", "hashed_api_key", "api_key_alias"
litellm_llm_api_latency_metric仅 LLM API 调用的延迟（秒）- 跟踪标签 "model", "hashed_api_key", "api_key_alias", "team", "team_alias", "requested_model", "end_user", "user"
litellm_llm_api_time_to_first_token_metricLLM API 调用的首 token 延迟 (TTFT) - 跟踪标签 model, hashed_api_key, api_key_alias, team, team_alias, requested_model, end_user, user, model_id [注：仅在流式请求时输出]

在 Prometheus 上跟踪 end_user​

默认情况下，LiteLLM 不会在 Prometheus 上跟踪 end_user，这是为了降低 LiteLLM 代理指标的基数 (cardinality)。

如果您想在 Prometheus 上跟踪 end_user，可以执行以下操作：

config.yaml
litellm_settings:
  callbacks: ["prometheus"]
  enable_end_user_cost_tracking_prometheus_only: true

输出 Stream 标签​

将 stream 标签添加到 litellm_proxy_total_requests_metric，以区分流式与非流式请求。默认禁用。

config.yaml
litellm_settings:
  callbacks: ["prometheus"]
  prometheus_emit_stream_label: true

启用后，litellm_proxy_total_requests_metric 将获得一个 stream 标签，其值为 "True", "False" 或 "None"。

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

该标签需要手动选择启用，因为向现有指标添加新标签会改变其基数，并可能导致现有的 Prometheus 查询/Grafana 仪表盘失效。仅在全新部署或准备好更新仪表盘时启用。

[BETA] 自定义指标​

在上述所有事件中跟踪 Prometheus 自定义指标。

自定义元数据标签​

  1. 在 config.yaml 中定义自定义元数据标签
model_list:
  - model_name: openai/gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  callbacks: ["prometheus"]
  custom_prometheus_metadata_labels: ["metadata.foo", "metadata.bar"]
  1. 携带自定义元数据标签发出请求
curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <LITELLM_API_KEY>' \
-d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What's in this image?"
          }
        ]
      }
    ],
    "max_tokens": 300,
    "metadata": {
        "foo": "hello world"
    }
}'
  1. 在 /metrics 端点检查自定义指标
... "metadata_foo": "hello world" ...

自定义标签​

将特定标签跟踪为 Prometheus 标签，以便进行更好的过滤和监控。

  1. 在 config.yaml 中定义自定义标签
model_list:
  - model_name: openai/gpt-4o
    litellm_params:
      model: openai/gpt-4o
      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/*"
  1. 携带标签发出请求
curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <LITELLM_API_KEY>' \
-d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What's in this image?"
          }
        ]
      }
    ],
    "max_tokens": 300,
    "metadata": {
        "tags": ["prod", "user-facing"]
    }
}'
  1. 在 /metrics 端点检查自定义标签指标
... "tag_prod": "true", "tag_staging": "false", "tag_batch_job": "false" ...

自定义标签的工作原理

  • 每个配置的标签都将成为 Prometheus 指标中的布尔标签
  • 如果标签匹配（精确或通配符），标签值为 "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/*)

配置指标和标签​

您可以选择性地启用特定指标并控制包含哪些标签，以优化性能并减少基数。

启用特定指标和标签​

通过在 prometheus_metrics_config 中指定指标来配置要输出的内容。每个配置组都需要一个 group 名称（用于组织）以及要启用的 metrics 列表。您可以选择性地包含 include_labels 列表来过滤指标的标签。

model_list:
 - model_name: gpt-4o
    litellm_params:
      model: gpt-4o

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，则启用所有指标及其默认标签（向后兼容）。

监控系统健康​

要监控 litellm 相关服务（redis / postgres）的健康状况，请执行：

model_list:
 - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
litellm_settings:
  service_callback: ["prometheus_system"]
指标名称描述
litellm_redis_latencyredis 调用的直方图延迟
litellm_redis_failsredis 调用失败次数
litellm_self_latency成功 litellm api 调用的直方图延迟

数据库事务队列健康指标​

使用这些指标监控数据库事务队列的健康状况。例如，监控内存和 redis 缓冲区的大小。

指标名称描述存储类型
litellm_pod_lock_manager_size指示哪个 pod 拥有写入数据库更新的锁。Redis
litellm_in_memory_daily_spend_update_queue_size内存中每日消费更新队列的大小。这些是每个用户的聚合消费日志。内存中
litellm_redis_daily_spend_update_queue_sizeRedis 每日消费更新队列的大小。这些是每个用户的聚合消费日志。Redis
litellm_in_memory_spend_update_queue_size密钥、用户、团队、团队成员等的内存中聚合消费值。内存中
litellm_redis_spend_update_queue_size密钥、用户、团队等的 Redis 聚合消费值。Redis

🔥 LiteLLM 维护的 Grafana 仪表盘​

LiteLLM 维护的 Grafana 仪表盘链接

https://github.com/BerriAI/litellm/tree/main/cookbook/litellm_proxy_server/grafana_dashboard

以下是您可以使用 LiteLLM Grafana 仪表盘监控的指标截图

已废弃指标​

指标名称描述
litellm_llm_api_failed_requests_metric已废弃，请使用 litellm_proxy_failed_requests_metric

为 /metrics 端点添加身份验证​

默认情况下，/metrics 端点无需身份验证。

您可以通过在配置中设置以下内容，选择对 /metrics 端点运行 litellm 身份验证

litellm_settings:
  require_auth_for_metrics_endpoint: true

常见问题解答​

什么是 _created 与 _total 指标？​

  • _created 指标是在代理启动时创建的指标
  • _total 指标是针对每个请求递增的指标

您应该使用 _total 指标进行计数分析

🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →