尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

LiteLLM Grafana 监控看板实战:导入 gen_ai 与 litellm_* 指标 JSON,读懂每一块 Panel 的 PromQL

LiteLLM Grafana 监控看板实战:导入 gen_ai 与 litellm_* 指标 JSON,读懂每一块 Panel 的 PromQL LiteLLM Grafana 监控看板实战导入 gen_ai 与 litellm_* 指标 JSON读懂每一块 Panel 的 PromQL【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellmcookbook/litellm_proxy_server/grafana_dashboard目录是 LiteLLM 官方维护的 Grafana 看板集合目录下存放的是可直接导入 Grafana 的grafana_dashboard.json文件覆盖两套指标体系——基于 OpenTelemetry v2 集成上报的gen_ai.*语义指标看板以及基于 Proxy/metrics端点暴露的litellm_*Prometheus 指标看板。读完本文你可以把三套看板一次性导入 Grafana 并绑定自己的 Prometheus 数据源理解每个面板背后的 PromQL 在统计什么请求速率、花费、Token、p95 延迟、限流余量、团队/Key 维度并排查“指标全是零线”这类常见坑。目录结构与三套看板一览整个目录由一个总入口 readme 和三个子看板组成看板目录看板标题JSON 内 title指标体系适用场景dashboard_genai_otelLiteLLM GenAI (OpenTelemetry)gen_ai.*OpenTelemetry v2按模型观测花费、Token、请求速率、延迟分位数、TTFTdashboard_v2LiteLLM Prod v2litellm_*Prometheus生产级 Proxy 观测成功率、错误分类、延迟、限流余量、Key/Team 维度dashboard_1LLM Proxylitellm_*Prometheus经典看板按模型看请求、Token、花费、TTFT 与失败数总入口 readme 对三者的划分给出了明确定义dashboard_genai_otel统计 OpenTelemetry v2 集成输出的gen_ai.*指标spend、tokens、request rate、按模型拆分的延迟分位数而dashboard_v2与dashboard_1统计的是litellm_*Prometheus 指标——两套看板查询完全不同的指标名不能混用数据源。所有看板的导入方式一致在 Grafana 中进入Dashboards New Import选择对应的grafana_dashboard.json文件再选定你的 Prometheus 数据源即可。前置条件让 Proxy 输出指标litellm_*看板的前置条件是先在 LiteLLM Proxy 上启用 Prometheus 指标总 readme 中写明的 Pre-Requisites 即“Setup LiteLLM Proxy Prometheus Metrics”。开启后 Proxy 会在/metrics端点暴露指标由 Prometheus 周期性抓取。从源码结构看这些指标全部定义在 prometheus.py 中它是 Proxy/metrics端点的日志集成实现注册的指标名与看板 PromQL 完全对应例如litellm_proxy_total_requests_metric/litellm_proxy_failed_requests_metricProxy 层总请求与失败请求Counter抓取后带_total后缀litellm_request_total_latency_metric请求总延迟Histogram含_sum/_count/_bucketlitellm_requests_metric、litellm_spend_metric、litellm_total_tokens_total按模型维度的请求量、花费与 Tokenlitellm_remaining_requests_metric、litellm_remaining_tokens_metric剩余限流配额对应响应头x-ratelimit-remaining-*litellm_llm_api_failed_requests_metricLLM API 调用失败数。即只要 Proxy 正常暴露这些指标且 Prometheus 抓取成功两套 Prometheus 看板即可直接出图无需任何额外标签配置。dashboard_v2LiteLLM Prod v2生产级 Proxy 观测这是面向生产环境的看板按三条逻辑 Row 组织每块面板的查询语句都写在其targets.expr中见 grafana_dashboard.json。Row 1Proxy 层指标Requests per second (success failure)sum(rate(litellm_proxy_total_requests_metric_total[2m]))对总请求 Counter 做 2 分钟窗口rate()得到整个 Proxy 的总 RPS成功与失败都计入。Failure Responses / Second By Exception Classsum(rate(litellm_proxy_failed_requests_metric_total[2m])) by (exception_class)按exception_class标签拆分失败速率。从源码可见失败 Counter 在 prometheus.py 中与总请求 Counter 成对注册按异常类别分线后可以直观区分是超时、鉴权还是上游 5xx 在贡献错误。Average Median Response Latency (seconds)# 平均延迟sum / count sum(rate(litellm_request_total_latency_metric_sum[2m])) / sum(rate(litellm_request_total_latency_metric_count[2m])) # 中位数histogram_quantile histogram_quantile(0.5, sum(rate(litellm_request_total_latency_metric_bucket[2m])) by (le))同一块面板同时给出平均值_sum/_count之比与 p50histogram_quantile(0.5, ...)分别基于 Histogram 的三种子序列这是 Prometheus 延迟分析的标准写法。Row 2LLM API 限流余量x-ratelimit-remaining-requests与x-ratelimit-remaining-tokenstopk(5, sort(litellm_remaining_requests)) topk(5, sort(litellm_remaining_tokens))这两个面板对应 Proxy 响应头中的x-ratelimit-remaining-requests/x-ratelimit-remaining-tokens展示剩余请求数与剩余 Token 数最少的 5 个配额对象topk(5, ...)。从源码结构看它们分别对应 prometheus.py 中注册的litellm_remaining_requests_metricGauge约 L2952/L3033与litellm_remaining_tokens_metric约 L2944/L3041。当曲线逼近 0即说明某个 Key/团队的配额即将耗尽是容量预警信号。Row 3按虚拟 Key 与团队维度Requests per second by Key Alias / by Team Aliassum(rate(litellm_proxy_total_requests_metric_total[2m])) by (api_key_alias) sum(rate(litellm_proxy_total_requests_metric_total[2m])) by (team_alias)同一总请求 Counter 按api_key_alias和team_alias标签分别聚合用于定位“哪个 Key、哪个团队在打流量”。整个看板只有一个模板变量DS_PROMETHEUS类型prometheus导入时由 Grafana 提示你选择 Prometheus 数据源即可。dashboard_1LLM Proxy经典模型维度看板dashboard_1 的 readme 说明该目录包含下面这块看板的 JSON同样以“启用 Proxy Prometheus 指标”为前置条件。其面板见 grafana_dashboard.json以模型维度为主面板PromQL含义Requests by modelsum by (model) (increase(litellm_requests_metric_total[5m]))每 5 分钟各模型新增请求数Tokens by modelsum(increase(litellm_total_tokens_total[5m])) by (model)每 5 分钟各模型消耗 TokenSpend by modelsum(increase(litellm_spend_metric_total[30d])) by (model)30 天窗口各模型花费Spend by teamsum(increase(litellm_spend_metric_total[30d])) by (hashed_api_key)30 天窗口按哈希后的API Key 花费用于团队/Key 成本归因Failed Requestsstatsum(increase(litellm_llm_api_failed_requests_metric_total[1h]))近 1 小时 LLM API 失败总数单值面板Time to first token (latency)histogram_quantile(0.99, sum(rate(litellm_self_latency_bucket{selfself}[1m])) by (le))p99 首 Token 延迟selfself标签过滤自监控序列其中“Spend by model / team”使用 30 天长窗口increase()适合做周/月成本趋势“Failed Requests”是 stat 类型面板只展示一个数字适合作为告警前的视觉哨点。dashboard_genai_otel基于 OpenTelemetry v2 的 GenAI 看板这套看板与litellm_*体系完全独立它统计的是 OpenTelemetry v2 集成发出的gen_ai.*指标OpenTelemetry 语义约定的 GenAI 命名见 dashboard 说明。开启指标上报默认关闭v2 集成的指标默认不输出需要设置 Proxy 环境变量LITELLM_OTEL_V2true LITELLM_OTEL_INTEGRATION_ENABLE_METRICStrue OTEL_EXPORTERotlp_http OTEL_ENDPOINTyour OTLP endpoint从源码结构可以印证这两个开关的实现位置config.py 中定义了OTEL_V2_ENV LITELLM_OTEL_V2并以LITELLM_OTEL_INTEGRATION_ENABLE_METRICS作为指标开关的校验别名validation_aliasAliasChoices(...)约 L17、L139。必须配置指标属性过滤器否则面板全是零线这是该看板最重要的前置配置。说明文档明确指出LiteLLM 默认的 OTEL 属性集包含 per-request 字段导致几乎每个请求都会落到一条只含单个样本的独立时间序列上rate()没有足够的点可供计算面板就是一条贴在 0 的直线。解决办法是在config.yaml中显式收窄上报的属性白名单callback_settings: otel: attributes: include_list: - gen_ai.operation.name - gen_ai.system - gen_ai.request.model - gen_ai.framework只保留gen_ai.operation.name、gen_ai.system、gen_ai.request.model、gen_ai.framework四个标签维度后同一模型的请求才会汇聚到同一条时间序列rate()、increase()、histogram_quantile()才能正常工作。看板结构与模板变量导入grafana_dashboard.jsonDashboards New Import后选择 Prometheus 数据源。看板带三个模板变量其中service与model通过label_values()从指标本身动态取值见 grafana_dashboard.jsondatasourcePrometheus 数据源选择器servicelabel_values(gen_ai_client_operation_duration_seconds_count, service_name)列出上报该指标的所有服务名modellabel_values(gen_ai_client_operation_duration_seconds_count{service_name~$service}, gen_ai_request_model)按选中的 service 列出模型。十块面板按“概览统计 分模型趋势”两层组织概览stat 面板统计$__range区间累计值面板PromQL 核心Requestssum(increase(gen_ai_client_operation_duration_seconds_count{...}[$__range]))Spendsum(increase(gen_ai_usage_cost_USD_sum{...}[$__range]))Tokenssum(increase(gen_ai_client_token_usage_sum{...}[$__range]))p95 request durationhistogram_quantile(0.95, sum by (le) (rate(gen_ai_client_operation_duration_seconds_bucket{...}[$__range])))分模型趋势timeseries 面板面板PromQL 核心Request rate by modelsum by (gen_ai_request_model) (rate(...duration_seconds_count...[$__rate_interval])) * 60每分钟请求数Spend rate by modelsum by (gen_ai_request_model) (rate(gen_ai_usage_cost_USD_sum...[$__rate_interval])) * 3600每小时花费速率Tokens per minute by model and typesum by (gen_ai_request_model, gen_ai_token_type) (rate(gen_ai_client_token_usage_sum...[$__rate_interval])) * 60按gen_ai_token_type区分输入/输出 Tokenp95 request duration by modelhistogram_quantile(0.95, sum by (le, gen_ai_request_model) (rate(...duration_seconds_bucket...)))p95 time to first token (streaming)基于gen_ai_server_time_to_first_token_seconds_bucket的 p95p95 provider generation time基于gen_ai_client_response_duration_seconds_bucket的 p95即供应商侧生成耗时注意$__rate_interval是 Grafana 内置变量会随刷新间隔自动调整rate()窗口保证曲线平滑且不过度滞后这是该看板相对手写查询的一个细节优势。关于 Grafana Cloud 预置 GenAI 看板的兼容性问题说明文档特别提示Grafana Cloud 自带预置的 GenAI 看板查询的是同名gen_ai.*指标看似可以直接替代本目录看板但实际上其 22 块面板中有 20 块写死了telemetry_sdk_nameopenlit过滤条件——这是 LiteLLM 不会携带、也无法配置添加的标签因此这些面板会保持空白。若你的目标是 LiteLLM建议直接导入本仓库的dashboard_genai_otel看板。两套看板怎么选、怎么对照想按模型维度看花费、Token、延迟分位、TTFT且团队已接 OpenTelemetryOTLP HTTP 导出到 Prometheus/兼容后端用dashboard_genai_otel指标语义遵循 GenAI 语义约定便于与其他 APM 生态对齐。想看Proxy 运营视角整体成功率、按异常类别的错误速率、限流余量、按 Key/团队维度的流量拆分用dashboard_v2或经典版dashboard_1数据来自 Proxy 自有的litellm_*Prometheus 指标只需/metrics被抓取即可配置成本最低。两套看板可以同时存在、各查各的指标族互不冲突。排障提示若 GenAI 看板出零线优先检查callback_settings.otel.attributes.include_list是否已收窄见上文若litellm_*看板无数据检查 Proxy 是否启用 Prometheus 回调以及 Prometheus 抓取任务是否指向了/metrics端点——指标名与注册位置均可在 prometheus.py 中逐一核对。延伸阅读路径指标注册与标签实现litellm/integrations/prometheus.py、prometheus 类型定义OpenTelemetry v2 集成与环境开关litellm/integrations/otel/model/config.py、otel 包说明三份可导入看板 JSONdashboard_v2、dashboard_genai_otel、dashboard_1看板总入口与前置条件cookbook/litellm_proxy_server/grafana_dashboard/readme.md【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表