Skip to content

kali20gakki/msAgent / skills/profiler/prometheus-metrics-analyzer

prometheus-metrics-analyzer

Verified

分析 SGLang、vLLM 和 vLLM-Ascend 推理服务的 Prometheus 原生历史 Runtime Metrics。通过动态发现指标、建立语义映射、查询核心指标和多轮补充证据,分析延迟、吞吐、调度及缓存等潜在瓶颈。不负责部署或参数优化。

Prometheus Runtime Metrics Analyzer

本 Skill 用于分析推理服务在指定历史时间区间内的运行状态,识别性能异常并分析可能原因。

支持 SGLang、vLLM 和 vLLM-Ascend。只使用推理引擎原生 Prometheus Metrics,不接入 MS Service Metric、自定义 Exporter 或 Grafana API。

职责划分

角色职责
Agent理解分析目标;发现并理解可用指标;建立语义映射;构造 PromQL;分析异常、提出假设并决定是否补充查询
Python提供 Prometheus API 访问、时间序列通用处理、查询结果持久化和分析文件管理

指标选择、PromQL 构造和瓶颈判断由 Agent 决策,不固化在 Python 脚本中。

1. 分析目标与关注指标

1.1 核心指标维度

分析时优先从以下维度理解服务状态。实际可用指标以 Discovery 结果为准。

维度关注指标主要反映的问题
LatencyTTFT、TPOT、ITL、Queue Time、Prefill / Decode Time请求延迟,以及 Prefill、排队和 Decode 阶段的表现
ThroughputPrompt Token Throughput、Generation Token Throughput、Request Throughput服务处理能力和单位时间内完成的工作量
SchedulerRunning Requests、Waiting Requests、Preemption请求排队、并发调度和资源竞争情况
KV CacheKV Cache Usage、Prefix Cache Hit Rate缓存资源使用情况和缓存命中行为
Workload请求数量、Prompt Tokens、Generation Tokens请求规模、输入输出长度及负载变化

这些是分析语义维度,不是固定指标清单。不同引擎、版本和部署配置暴露的指标可能不同。

1.2 常见瓶颈方向

下表用于形成初步分析方向,不能仅凭单个指标直接确认瓶颈。

瓶颈方向典型表现后续关注方向
请求排队 / 调度Waiting Requests 或 Queue Time 增加,TTFT 恶化Running、Waiting、Queue Time、请求负载
Prefill 性能TTFT 上升,且 Prefill Time 可能同步增加TTFT、Prefill Time、Prompt Tokens
Decode 性能TPOT / ITL 上升,Generation Throughput 下降TPOT、ITL、Decode Time、生成长度
KV Cache 压力Cache Usage 较高,并伴随 Preemption 或缓存命中异常Cache Usage、Preemption、Prefix Cache
服务吞吐受限请求持续增加,但处理吞吐增长有限,等待请求积累Running、Waiting、Token Throughput、Workload

分析时还需考虑并发、输入长度、输出长度、请求速率等 Workload 变化。负载变化本身可能解释部分性能变化,不应直接归因为引擎瓶颈。

1.3 SGLang / vLLM 常见指标参考

以下为常见指标名称示例,用于帮助 Agent 建立初始语义映射。不保证所有版本或部署配置均暴露这些指标,实际查询必须以 Discovery 结果为准。

分析语义vLLM / vLLM-Ascend 示例SGLang 示例
TTFTvllm:time_to_first_token_secondssglang:time_to_first_token_seconds
TPOTvllm:request_time_per_output_token_secondssglang:request_time_per_output_token_seconds
ITLvllm:inter_token_latency_secondssglang:inter_token_latency_seconds
Queue Timevllm:request_queue_time_secondssglang:queue_time_seconds
Running Requestsvllm:num_requests_runningsglang:num_running_reqs
Waiting Requestsvllm:num_requests_waitingsglang:num_queue_reqs
Generation Throughputvllm:generation_tokens(Counter)sglang:gen_throughput(Gauge)
KV Cache Usagevllm:kv_cache_usage_percsglang:token_usage

注意:

  • vLLM-Ascend 以实际部署版本的 Metadata 为准,不假设与上游 vLLM 完全一致。
  • SGLang 的 token_usage 不应直接视为与 vLLM KV Cache Usage 完全等价;混合缓存模型还可能暴露 full_token_usage、swa_token_usage、mamba_usage 等指标。
  • TPOT 和 ITL 相关但不完全相同,应结合 HELP 和实际统计口径判断。
  • Counter、Gauge、Histogram 的查询方式不同,不能只根据指标名称构造 PromQL。

参考文档:

2. 输入与环境准备

2.1 分析输入

分析任务需要明确以下信息:

字段必需性说明
prometheus_url必填Prometheus 服务地址
target必填需要分析的单个服务 Target,使用实际存在的 Labels 定位,通常为 job、instance
start必填分析开始时间
end必填分析结束时间
step可选Query Range 采样间隔,单位为秒
engine可选引擎类型,如 sglang、vllm、vllm-ascend
symptom可选用户观察到的异常,如 TTFT 上升
reference_window可选用于对比的参考时间区间
slo可选TTFT、TPOT 等服务目标或告警阈值

输入格式和字段结构参考 config/request-input.example.json。填写实际信息后保存为 request-input.json。

时间必须明确时区,支持带时区的 RFC3339 格式或 Unix 时间戳。用户提供当地时间时,转换为带时区的 RFC3339;存在歧义时先向用户确认。

认证信息仅从环境变量 PROMETHEUS_BEARER_TOKEN 读取,不得写入输入文件、URL、PromQL 或 Labels。

一次分析绑定一个 Prometheus 和一个 Target。跨服务分析时分别创建分析工作区,不在同一个任务中混合不同服务的数据。

2.2 确认 Prometheus Target

如果用户已提供 Prometheus URL 和精确 Target,可以直接使用。

如果 Target 不明确,先查询当前 Prometheus 的 Active Targets:

python3 scripts/prometheus_client.py targets \
  --url http://npu-server-a:9090

根据实际 Labels 选择与分析目标一致的服务;存在多个匹配项时先确认,不要随意选择。

targets 只反映当前 Active Targets。历史服务已经停止或从抓取配置移除时,可以使用用户提供的历史 Labels 继续分析,不要求 Target 当前处于 UP 状态。

3. 分析工作流

整体流程:

flowchart TD
    A["用户输入分析目标"] --> B["确认 Prometheus 和 Target"]
    B --> C["创建分析工作区"]
    C --> D["Discovery:获取可用 Metrics"]
    D --> E["Agent:建立指标语义映射"]
    E --> F["选择首轮核心指标"]
    F --> G["PromQL 查询"]
    G --> H["Python:处理时间序列"]
    H --> I["Agent:性能画像与瓶颈假设"]
    I --> J{"是否需要更多证据?"}
    J -->|需要| K["选择下一轮指标"]
    K --> G
    J -->|不需要| L["输出分析报告"]

3.1 创建分析工作区

ANALYSIS_DIR=$(python3 scripts/run_manager.py create \
  --request request-input.json \
  --output outputs)

目的: 为本次分析创建独立工作区,固定 Prometheus URL、Target 和主分析时间区间,并提供统一的数据保存位置。

后续查询继承该上下文。原始响应、处理结果、指标映射、分析证据和最终报告均保存在工作区中。整个分析过程只创建一次;更换 Prometheus、Target 或主分析时间区间时,创建新的工作区。

典型目录结构:

outputs/
└── metrics-analysis/
    └── analysis_<timestamp>_<id>/
        ├── request.json
        ├── manifest.json
        ├── metric_catalog.json
        ├── queries/
        │   └── round_01/
        │       └── query_001/
        │           ├── request.json
        │           ├── response.json.gz
        │           └── processed.json
        └── analysis/
            ├── metric_mapping.md
            ├── evidence.json
            └── report.md

实际目录和文件名以脚本实现为准;Agent 不需要手动创建或维护这些目录。

3.2 Discovery:了解有哪些指标

python3 scripts/prometheus_client.py discover \
  --analysis-dir "$ANALYSIS_DIR"

目的: 在查询指标前了解目标服务实际暴露了哪些 Metrics,避免根据经验猜测指标名称和类型。

Discovery 获取 Prometheus readiness、当前 Target 状态、Target-scoped Metrics Metadata,以及指定时间区间内的历史 Series。结果保存到:

$ANALYSIS_DIR/metric_catalog.json

Agent 重点查看实际 Metric Name、TYPE、HELP、Unit 和 Labels,并确认以下状态:

字段含义
target_currently_up当前匹配的 Target 是否 UP
metadata_available是否获取到 Target-scoped Metadata
historical_series_discovered是否发现指定区间的历史序列
warningsDiscovery 过程中的异常或限制

注意:

  • Prometheus 未 Ready 时,先解决连接或服务问题。
  • Target 当前 DOWN 不代表历史数据不可用,不能仅因此终止分析。
  • 当前 Metadata 不一定代表历史时段运行的版本或模型。
  • 历史 Series 只代表候选指标,不保证整个区间都有样本。
  • 无法确认指标类型时标记为 unknown,不要根据名称或后缀猜测。
  • 必要时查询历史 up 指标,辅助判断目标服务在分析区间内的抓取状态。

3.3 Agent 建立指标语义映射

目的: 将 Discovery 得到的实际指标与性能分析语义对应起来,为首轮查询和后续补充证据提供依据。

Agent 根据 metric_catalog.json 中的 Metric Name、TYPE、HELP、Unit 和 Labels,结合引擎信息及第 1.3 节的指标参考,识别与本次分析相关的指标。

映射示例:

分析语义实际 MetricTYPE备注
TTFTDiscovery 中实际发现的指标Histogram请求首 Token 延迟
TPOTDiscovery 中实际发现的指标Histogram请求级输出 Token 延迟
Running RequestsDiscovery 中实际发现的指标Gauge正在运行的请求数
Generation ThroughputDiscovery 中实际发现的指标Gauge / Counter生成吞吐或 Token 累计量

映射时注意:

  • 只映射本次分析相关的指标,不要求覆盖整个 Catalog。
  • 相同语义可能对应不同统计口径,应结合 HELP 判断。
  • 不同引擎的相似指标不一定完全等价。
  • 保留有意义的 Model、Rank、Instance 等 Labels,后续查询时避免误聚合。
  • 找不到对应指标时标记为 unavailable,不要猜测替代项。

将本次分析的指标映射保存到:

$ANALYSIS_DIR/analysis/metric_mapping.md

映射由 Agent 动态生成。Python 不维护 SGLang / vLLM 专属指标名称或适配规则。

3.4 选择首轮核心指标

目的: 先通过少量指标建立整体性能画像,再根据初步结果决定是否深入,避免无差别拉取全部 Metrics。

分析场景首轮查询思路
用户未指定异常方向从 Latency、Throughput、Scheduler、KV Cache 和 Workload 中选择实际可用的核心指标
用户明确指出异常优先查询异常指标及其相关指标,不必机械覆盖所有维度
用户提供 SLO 或告警阈值优先查询与目标指标直接相关的数据,并判断是否违反 SLO
用户提供参考时间区间首轮查询当前区间;必要时使用相同表达式补充参考区间

首轮指标应根据实际 Catalog 选择,不要求每类指标都存在,也不要求一次性查询全部指标。

3.5 构造 PromQL 并执行查询

目的: 根据实际指标类型和分析目标,将需要验证的问题转化为 PromQL,并获取指定时间区间内的时间序列。

根据 Discovery 得到的实际 TYPE 构造 PromQL:

Metric TYPE常见查询方式注意事项
Gauge通常直接查询关注时间趋势、峰值和变化
Counterrate() 或 increase()获取单位时间速率或区间增量,不直接把累计值当吞吐
Histogramhistogram_quantile(),或查询 _sum / _count确认实际指标族及 _bucket、_sum、_count 序列
Summary结合实际暴露的数据和 HELP 确定不假设所有 Summary 都能从原始序列重新计算任意分位数

经典 Histogram P95 示例:

histogram_quantile(
  0.95,
  sum by (le, model_name) (
    rate(<actual_metric_family>_bucket{
      job="...",
      instance="..."
    }[5m])
  )
)

指标名称、Labels、聚合维度和 Rate Window 必须根据实际 Catalog 调整。

查询时注意:

  • 每个原始 Metric Selector 都必须包含当前工作区的精确 Target Labels。
  • 聚合前考虑 Model、Rank、Instance 等维度,不能默认合并不同序列。
  • 不要直接平均多个实例的延迟分位数。
  • Rate Window 应考虑 Scrape Interval 和边界采样。
  • 指标不可用或类型未知时,不要强行构造查询。
  • 原生 Histogram 优先通过 PromQL 转换为数值;Processor 对未转换的原生 Histogram 样本只统计数量,不将其当作 0。

参考 config/queries.example.json 中的 Gauge、Counter Rate 和 Histogram P95 写法。该文件用于参考查询结构,示例中的指标名称和 Labels 不应直接执行。

将本轮查询保存为 JSON 数组,例如:

$ANALYSIS_DIR/queries_round_01.json

每项查询包含实际 PromQL,可按需提供 unit、start、end 和 step。具体结构参考 config/queries.example.json。

执行本轮批量查询:

python3 scripts/prometheus_client.py query \
  --analysis-dir "$ANALYSIS_DIR" \
  --round 1 \
  --queries-file "$ANALYSIS_DIR/queries_round_01.json" \
  > "$ANALYSIS_DIR/queries_round_01_result.json"

每条查询自动分配 query_id,请求和原始响应自动落盘。处理成功项;失败项查看错误信息,不要因部分失败而重跑整个批次。后续查询使用新的查询文件并递增 --round。Round 只是查询批次标识,不代表固定诊断轮数。

3.6 Python 处理时间序列

目的: 将 Prometheus 返回的原始时间序列转换为便于 Agent 判断的统计特征和趋势信息。

对每条成功查询执行:

python3 scripts/metrics_processor.py \
  --analysis-dir "$ANALYSIS_DIR" \
  --query-id query_001 \
  --trend-window 60

Processor 按 Labels 独立处理时间序列,主要输出:

输出内容用途
Data Quality预期采样点、实际采样点、有效采样点、缺失比例、时间覆盖情况判断数据是否足以支撑结论
StatisticsMean、Median、Min、Max、Start、End、Delta、Relative Change、Slope、Peak Timestamp、Sample P95识别异常幅度和趋势
Trend按时间窗口统计 Mean、Min、Max 和样本数量观察持续恶化、突增和恢复
Reference Comparison与参考查询按 Labels 对齐后的统计比较判断相对基线是否退化

结果自动保存为对应查询目录下的 processed.json。Processor 只负责通用数据处理,不判断性能瓶颈。

数据处理注意事项:

  • 按 Labels 独立处理,不默认合并不同时间序列。
  • 缺失数据不能当作 0;NaN、Inf 不参与统计。
  • 空结果标记为 no_data。
  • time_coverage 是首末有效采样点的时间跨度占比,不代表内部没有缺口或底层 Scrape 完整。
  • sample_p95 是时间序列采样值的 P95,不是请求延迟 P95。
  • 不为无采样的时间窗口生成虚构零值。

3.7 Agent 分析并补充证据

目的: 根据本轮处理结果形成初步性能判断,并选择最有价值的下一组指标验证或排除假设。

Agent 阅读本轮 processed.json,结合指标语义、趋势、Labels 和数据质量,形成性能画像及初步假设。每轮分析应区分:

分析内容含义
Observations实际观察到的指标变化、时间范围和数值
Hypotheses基于当前证据提出的可能原因
Supporting Evidence支持某个假设的指标及其变化
Counter Evidence不支持或与假设矛盾的证据
Next Evidence下一轮最值得获取的指标及查询目的

例如:

当前观察可进一步验证的方向
TTFT 上升而 TPOT 相对稳定检查 Queue Time、Waiting Requests 和 Prefill Time
TPOT / ITL 恶化而 TTFT 相对稳定检查 Decode 相关指标及 Generation Throughput
KV Cache Usage 较高结合 Preemption、Prefix Cache 等指标判断是否存在缓存压力
Throughput 下降且 Waiting 增加结合 Running、请求量和 Token Throughput 判断服务负载与处理能力变化

Agent 自主决定是否继续:

  1. 假设需要验证时,选择能够支持或反驳它的指标,进入下一轮 Query → Processing → Analysis。
  2. 证据充分或进一步查询没有明显价值时停止。
  3. 相同 PromQL、时间区间和 step 已有成功响应时复用已保存结果(包括空结果);失败查询允许在同一 Run 内重试,保留每次尝试及错误记录。
  4. 不设置固定诊断轮数或查询数量。

需要参考区间对比时,使用相同 PromQL、Target 和查询粒度单独查询参考区间,再通过 --reference-query-id 处理。比较前判断两个区间的 Workload 是否可比。

每轮查询结果自动落盘。将重要观察、假设、查询 ID 和证据引用持续整理到:

$ANALYSIS_DIR/analysis/evidence.json

4. 判断原则与输出报告

4.1 判断原则

  • 不设置统一的 TTFT / TPOT 绝对异常阈值,优先参考用户提供的 SLO 或告警阈值。
  • 对比参考区间时,判断 Workload 是否可比;没有参考区间时,关注当前区间内的趋势、突增、持续恶化和恢复。
  • 区分 Performance Degradation 与 SLO Violation。
  • 指标相关性不代表因果关系;单独的 KV Cache Usage 高不能证明缓存是性能瓶颈。
  • 结合数据质量判断结论可信度;证据不足时保留为可能原因,不将推测写成确定结论。

本 Skill 只分析性能异常及可能原因,不提供推理引擎参数优化建议。

4.2 输出分析报告

分析结束后,Agent 生成:

$ANALYSIS_DIR/analysis/evidence.json
$ANALYSIS_DIR/analysis/report.md

报告至少包括:

章节内容
Analysis ScopePrometheus、Target、引擎和分析时间范围
Summary整体表现和主要异常
Observations & Evidence关键指标变化、查询 ID、Labels、时间和数值
Possible Causes可能原因及证据强弱
Counter Evidence不支持当前假设的证据
Limitations缺失指标、数据缺口、Workload 不可比等限制

完成后执行:

python3 scripts/run_manager.py finalize \
  --analysis-dir "$ANALYSIS_DIR" \
  --evidence "$ANALYSIS_DIR/analysis/evidence.json" \
  --report "$ANALYSIS_DIR/analysis/report.md"

该命令只保存最终证据和报告并更新工作区记录,不负责生成诊断结论。最终交付工作区路径及 analysis/report.md。

5. Prometheus 环境部署参考

Prometheus 和 Grafana 的部署、配置与排障不属于本 Skill 的主要分析流程。需要搭建监控环境或排查连接、抓取和历史数据问题时,按需阅读 references/prometheus_setup.md。

已有环境直接复用,不自动安装或启动服务。Prometheus 应独立于推理服务长期运行;vLLM / SGLang 停止、重启或切换时通常不需要重启 Prometheus。Target DOWN 不代表历史数据丢失。

Grafana 是可选展示组件。Metrics Analyzer 直接访问 Prometheus HTTP API,不依赖 Grafana。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall