🎯 今日核心问题

  1. 成功率的分母到底是「HTTP 请求数」还是「业务任务数」?两者差多少?
  2. 平均步数为什么比成功率更早暴露退化?它的异常长什么样?
  3. 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%」这种问题——月底看账单只能回答「这个月超支了」。

【五】常见误区

💻 代码示例

统一的指标门面,四个指标一次埋全:

@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 写进磁盘。明天讲日志分层、字段规范与脱敏管线。