📚 课程目录第4章 k6核心指标

4. k6 核心指标：内置指标与自定义指标

在 k6 压测中，指标（Metric）是衡量系统性能与稳定性的核心数据单元。k6 将指标分为内置指标和自定义指标两大类。内置指标由 k6 运行时自动采集，覆盖请求耗时、失败率、虚拟用户数等基础维度；自定义指标则允许测试脚本按业务逻辑定义专属度量，如队列深度、缓存命中率、业务成功率等。

本章将系统梳理这两类指标的定义、采集方式、适用场景，并通过对比表格和结构图帮助你在 P95 阈值校准实战中精准选型。

4.1 内置指标：开箱即用的性能基线

k6 内置指标在每次测试执行时自动记录，无需额外声明。以下四个指标是 P95 阈值校准中最常用的核心指标。

指标名称	类型	含义	P95 校准中的用途
`http_req_duration`	Trend（趋势）	HTTP 请求从发出到收到完整响应的总耗时（ms）	直接作为 P95 阈值计算的目标指标
`http_req_failed`	Rate（比率）	HTTP 请求失败的比例（基于非 2xx/3xx 状态码或超时）	作为阈值失效条件：失败率超过 1% 时 P95 阈值自动失效
`vus`	Gauge（瞬时值）	当前时刻活跃的虚拟用户数	判断压测水位是否达到目标并发数
`iterations`	Counter（计数器）	脚本迭代（VU 执行一次完整函数）的总次数	计算吞吐量（iterations / 时间），辅助判断压测是否达到稳态

实战提示：在 P95 阈值校准中，http_req_duration 是主指标，http_req_failed 是门禁指标。只有当失败率低于预设阈值（如 1%）时，P95 耗时数据才被视为有效。

4.2 自定义指标：按业务逻辑定义度量

当内置指标无法覆盖业务语义时（如“下单成功率”“缓存命中率”“队列等待时间”），k6 提供四种自定义指标类型：Trend、Counter、Gauge、Rate。它们与内置指标的类型系统完全一致，但由测试脚本显式创建和上报。

类型	数据结构	典型场景	P95 校准中的角色
Trend	记录一组数值，可计算 min/max/avg/p(95)/p(99)	业务耗时、数据库查询耗时、外部 API 调用耗时	扩展 P95 阈值到业务层，如“下单业务 P95 耗时”
Counter	单调递增的计数器	请求总数、错误总数、订单总数	计算吞吐量或错误率分母
Gauge	记录当前瞬时值	连接池大小、队列深度、内存使用率	监控压测过程中的资源水位
Rate	记录“成功/总次数”的比率	业务成功率、缓存命中率、接口可用率	作为 P95 阈值的辅助判定条件

  选型原则：需要计算百分位（如 P95）时用 Trend；需要统计总量时用 Counter；需要监控瞬时状态时用 Gauge；需要关注比率时用 Rate。切勿将 Trend 当作 Counter 使用，否则百分位计算会失真。

4.3 指标类型与数据流结构

下图展示了 k6 指标从采集到输出的完整数据流，以及内置指标与自定义指标在其中的位置关系。

4.4 自定义指标代码实战

以下示例展示如何在 k6 脚本中创建并使用四种自定义指标，并配合阈值进行 P95 校准。

import http from 'k6/http';
import { Trend, Counter, Gauge, Rate } from 'k6/metrics';
import { check, sleep } from 'k6';

// 自定义指标声明
const businessDuration = new Trend('business_duration');   // 业务耗时
const orderCount = new Counter('order_total');             // 订单总数
const queueDepth = new Gauge('queue_depth');               // 队列深度
const bizSuccessRate = new Rate('biz_success_rate');       // 业务成功率

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    // 内置指标阈值
    http_req_duration: ['p(95)<2000'],
    http_req_failed: ['rate<0.01'],
    // 自定义指标阈值
    business_duration: ['p(95)<1500'],
    biz_success_rate: ['rate>0.99'],
  },
};

export default function () {
  const start = Date.now();

  // 模拟业务请求
  const res = http.get('https://test.k6.io');
  const success = check(res, { 'status is 200': (r) => r.status === 200 });

  // 上报业务耗时（Trend）
  const elapsed = Date.now() - start;
  businessDuration.add(elapsed);

  // 上报订单总数（Counter）
  orderCount.add(1);

  // 上报队列深度（Gauge）—— 模拟从响应头获取
  const depth = parseInt(res.headers['X-Queue-Depth'] || '0');
  queueDepth.add(depth);

  // 上报业务成功率（Rate）
  bizSuccessRate.add(success);

  sleep(1);
}

常见误区：自定义指标名称不要与内置指标重名（如不要定义名为 http_req_duration 的 Trend），否则会导致数据覆盖或阈值冲突。建议使用业务前缀，如 order_、payment_、search_。

4.5 指标选型决策流程

在 P95 阈值校准实战中，面对一个具体的业务场景，可以按以下流程快速确定指标类型：

判断是否需要百分位统计（P50/P95/P99）？
是 → 使用 Trend；否 → 进入下一步。
判断是否关注“当前瞬时值”？
是 → 使用 Gauge；否 → 进入下一步。
判断是否关注“成功/总次数”的比率？
是 → 使用 Rate；否 → 使用 Counter。

  实战案例：在“下单链路 P95 校准”中，order_create_duration（Trend）是主指标，order_success_rate（Rate）是门禁指标，order_total（Counter）用于计算吞吐量，db_connection_pool（Gauge）用于监控数据库连接水位。四个指标协同完成一次完整的 P95 阈值校准。

4.6 本章小结

内置指标：http_req_duration（Trend）、http_req_failed（Rate）、vus（Gauge）、iterations（Counter）是 P95 校准的四大基础指标。
自定义指标：Trend 用于百分位统计，Counter 用于总量计数，Gauge 用于瞬时监控，Rate 用于比率判定。
选型原则：按“是否需要百分位 → 是否瞬时值 → 是否比率”的决策树快速定位。
阈值绑定：自定义指标同样支持 thresholds 配置，可与内置指标一起构成完整的 P95 校准体系。