🎯 今日核心问题
- 成功率的分母到底是「HTTP 请求数」还是「业务任务数」?两者差多少?
- 平均步数为什么比成功率更早暴露退化?它的异常长什么样?
- P95 延迟用 Micrometer 怎么算才不随重启丢失,为什么不能用平均值代替?
📖 精读提纲
【一】四个指标,四条不同的排查路径
一个 Agent 系统的健康度用四个数就够:任务成功率、平均步数、P95 端到端延迟、单次任务成本。它们之间不是并列关系,而是因果链——成功率掉是最下游的结果,平均步数涨往往是最早的征兆,延迟和成本是资源侧的投影。
成功率的口径必须钉死在「业务任务」上,而不是 HTTP 200。一次请求返回 200、body 里是「抱歉我无法完成」也算失败。正确做法是在 AgentResult 里显式带 outcome 枚举(SUCCESS/REFUSED/MAX_STEPS/TOOL_ERROR/GUARD_BLOCKED),成功率 = SUCCESS / 全部终态,且要把「用户主动中断」排除在分母外——那不是系统的锅。
【二】平均步数是 Agent 特有的「地雷探测仪」
传统服务的指标里没有「步数」这一项,但 Agent 有。平均步数从 2.8 涨到 4.5 意味着什么?大概率是某个工具的返回格式变了,模型看不懂,于是一遍遍重试;或者 Prompt 被改坏,模型忘了收尾。这类故障的延迟与成本会同比上涨 60%,但成功率可能还没掉——用户只是等得更久。
所以平均步数要设成窄幅告警:基线 ±20% 就报警。同时看分布而不是只看均值——正常是单峰偏左(大部分 2-3 步,少量 5-8 步),如果出现双峰(一堆 1 步 + 一堆 8 步),说明有一类请求压根没进入工具调用,另一类在死磕。
【三】P95 而不是平均:平均值会把灾难藏起来
平均延迟 2 秒听起来很好,但如果 5% 的请求耗时 30 秒,用户体验是「每 20 个人有 1 个投诉」。Agent 的延迟分布是典型长尾:模型调用本身就有秒级抖动,重试又会让尾巴更肥。所以必须看 P95 与 P99。
Micrometer 里用 Timer 的 publishPercentiles 或更准的 serviceLevelObjectives(SLO bucket)。前者是客户端估算,多实例聚合时会失真;后者产出 histogram bucket,Prometheus 侧用 histogram_quantile 聚合,跨实例才正确。多副本部署一律用 SLO bucket,不要用客户端 percentile。
【四】成本也要做成指标,而不是月底看账单
单次成本 = 该任务的 token 总花费 / 任务数,用 Counter 累计「微美元」这类整数单位(浮点 counter 会漂移),除以另一个 counter 得到均值。指标化之后你才能回答「昨天上线的 Prompt 改动让成本涨了 18%」这种问题——月底看账单只能回答「这个月超支了」。
【五】常见误区
- ❌ 把
userId、sessionId、query当指标 tag。这是基数炸弹,Prometheus 内存会爆。tag 只能是模型名、工具名、outcome 这类有限枚举。 - ❌ 成功率的分子包含「降级答复」。降级是兜底不是成功,必须单独一个 outcome,否则指标会掩盖质量下滑。
- ❌ 用
synchronized或自己写的滑动窗口算 P95。重启即丢,多实例还得自己合并,直接用 Micrometer + Prometheus。 - ❌ 延迟只统计模型调用。端到端才是用户感知的值,模型调用只是其中一个 span。
💻 代码示例
统一的指标门面,四个指标一次埋全:
@Component
@RequiredArgsConstructor
public class AgentMetrics {
private final MeterRegistry registry;
/** 任务终态计数:success / refused / max_steps / tool_error / guard_blocked */
public void outcome(String agent, Outcome outcome, String model) {
Counter.builder("agent.task.total")
.tag("agent", agent)
.tag("outcome", outcome.name().toLowerCase())
.tag("model", model)
.register(registry)
.increment();
}
/** 步数分布:用 TimeGauge 不合适,步数是计数,用 DistributionSummary */
public void steps(String agent, int steps) {
DistributionSummary.builder("agent.task.steps")
.tag("agent", agent)
.publishPercentileHistogram()
.serviceLevelObjectives(1, 2, 3, 5, 8, 13)
.register(registry)
.record(steps);
}
/** 端到端延迟:SLO bucket 保证多实例可聚合 */
public Timer endToEnd(String agent, String model) {
return Timer.builder("agent.task.duration")
.tag("agent", agent)
.tag("model", model)
.publishPercentileHistogram()
.serviceLevelObjectives(
Duration.ofMillis(800), Duration.ofSeconds(2),
Duration.ofSeconds(5), Duration.ofSeconds(15), Duration.ofSeconds(30))
.register(registry);
}
/** 成本用整数微美元累计,避免浮点漂移 */
public void cost(String agent, String model, long microUsd) {
Counter.builder("agent.cost.microusd")
.tag("agent", agent)
.tag("model", model)
.register(registry)
.increment(microUsd);
}
}
在 ReAct 出口统一结算,成败都记:
public AgentResult execute(AgentRequest req) {
Timer.Sample sample = Timer.start(registry);
AgentTrace trace = null;
try {
trace = loop.run(AgentTrace.start(req));
metrics.steps(req.agentName(), trace.stepCount());
metrics.outcome(req.agentName(), trace.outcome(), trace.model());
metrics.cost(req.agentName(), trace.model(), trace.costMicroUsd());
return AgentResult.of(trace);
} catch (MaxStepsExceeded e) {
metrics.steps(req.agentName(), req.maxSteps());
metrics.outcome(req.agentName(), Outcome.MAX_STEPS, req.model());
metrics.cost(req.agentName(), req.model(), e.trace().costMicroUsd());
throw e;
} finally {
sample.stop(metrics.endToEnd(req.agentName(), req.model()));
}
}
Prometheus 侧的三个核心查询,直接进 Grafana 面板:
# 任务成功率(5 分钟窗口)
sum(rate(agent_task_total{outcome="success"}[5m]))
/ sum(rate(agent_task_total{outcome!="user_abort"}[5m]))
# 平均步数
sum(rate(agent_task_steps_sum[5m])) / sum(rate(agent_task_steps_count[5m]))
# P95 端到端延迟(多实例正确聚合)
histogram_quantile(0.95,
sum by (le, agent) (rate(agent_task_duration_seconds_bucket[5m])))
# 单次任务平均成本(美元)
sum(rate(agent_cost_microusd_total[5m])) / sum(rate(agent_task_total[5m])) / 1e6
✏️ 今日动手
把 Outcome 枚举加进 AgentResult,接上 AgentMetrics,然后做一次「注入故障」实验:把某个工具的返回字段改名(模拟上游变更),观察 15 分钟内平均步数如何上涨、成功率多久之后才开始掉。把你看到的时间差写进 Runbook——这个时差就是「步数告警」能为你争取到的抢修时间,通常有 20 分钟以上。
🔖 明日预告
指标告诉你「哪里不对」,日志告诉你「具体是什么」。但 Agent 的日志里全是用户原话和工具返回,直接落盘等于把 PII 写进磁盘。明天讲日志分层、字段规范与脱敏管线。