Prometheus 远程写入

Prometheus remote write 是一种协议，可将数据从发送方可靠地实时传送到接收方。它有多种兼容实现及存储集成。

例如，使用 experimental-prometheus-rw 输出时，k6 可以将测试结果指标发送到远程写入端点，并存储到 Prometheus。

在 k6 run 执行期间，这个输出会取得 k6 指标生成的全部时间序列数据点，再生成等价的 Prometheus 时间序列，并发送到 Prometheus 远程写入端点。

指标映射

所有 k6 指标类型都会转换成等价的 Prometheus 指标类型。该输出将指标映射为带有 Name 标签的时间序列。k6 会尽可能遵循 Prometheus 项目定义的命名最佳实践：

• 所有时间序列都使用 k6_ 命名空间前缀。
• 所有时间序列都以样本值的基本单位作为后缀，前提是 k6 知道这个基本单位。
• Trend 和 Rate 使用相应的后缀，以便更容易发现。

Trend 指标转换

该输出提供两种不同的机制，将 k6 Trend 指标发送到 Prometheus：

1. Counter 和 Gauge 指标（默认）
2. Prometheus 原生直方图

这两个选项都能高效存储测试结果，并提供高精度查询。

注意，无论使用哪个选项，k6 都会先聚合趋势指标数据，再发送给 Prometheus。聚合的原因如下：

• Prometheus 以毫秒（ms）精度存储数据，而 k6 指标以更高的纳秒（ns）精度收集数据点。
• 负载测试可能生成大量数据点。高精度原始数据的成本和扩展复杂度可能迅速增加，而且分析性能趋势时并不需要如此高的精度。

1. Counter 和 Gauge

默认情况下，Prometheus 支持 Counter 和 Gauge 指标类型。因此，这是该输出的默认选项，它将所有 k6 Trend 指标转换成 Prometheus Counter 和 Gauge 指标。

可以通过 K6_PROMETHEUS_RW_TREND_STATS 选项配置所有 k6 趋势指标的转换方式。它接受以逗号分隔的统计函数列表：count、sum、min、max、avg、med、p(x)。默认值为 p(99)。

根据提供的统计函数列表，k6 将所有趋势指标转换为对应数学函数的 Prometheus 指标。

例如，K6_PROMETHEUS_RW_TREND_STATS=p(90),p(95),max 将每个趋势指标转换成以下三个 Prometheus 指标：

• k6_*_p90
• k6_*_p95
• k6_*_max

这个选项提供了一种可配置的方案，在 Prometheus 中表示 Trend 指标，但有以下缺点：

• 一个 k6 Trend 指标会转换为多个 Prometheus 指标。
• 某些 Gauge 值无法聚合，尤其是百分位数。
• 它使用的 k6 数据结构消耗较多内存。

2. Prometheus 原生直方图

为解决前一个选项的限制，可以启用 Prometheus 原生直方图，将 k6 趋势指标转换为高保真直方图。

使用此选项时，每个 k6 趋势指标都映射到对应的 Prometheus 直方图指标 k6_*。随后可以使用 histogram_quantile() 等 Prometheus 直方图函数查询。

将测试指标发送到远程写入端点

在 Prometheus 2.x 中使用远程写入，需要启用功能标志 –web.enable-remote-write-receiver。远程写入存储选项请参阅 Prometheus 文档。

1. 不使用原生直方图，将 k6 指标发送到远程写入端点：

   • 建立运行中的远程写入端点，并确保 k6 可以访问它。
   • 使用 –out 标志及 RW 端点 URL，按以下方式运行 k6 脚本：

   趋势统计值

   K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
   k6 run -o experimental-prometheus-rw script.js

   HTTP Basic 身份验证

   K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
   K6_PROMETHEUS_RW_USERNAME=USERNAME \
   K6_PROMETHEUS_RW_PASSWORD=PASSWORD \
   k6 run -o experimental-prometheus-rw script.js

   • 可选地传入 K6_PROMETHEUS_RW_TREND_STATS，以便查询趋势指标的其他统计值。默认值为 p(99)。

   K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
   K6_PROMETHEUS_RW_TREND_STATS=p(95),p(99),min,max \
   k6 run -o experimental-prometheus-rw script.js

2. 使用原生直方图，将 k6 指标发送到远程写入端点：

   • 在 Prometheus 2.40.0 或更高版本中启用功能标志 –enable-feature=native-histograms。建立运行中的远程写入端点，并确保 k6 可以访问它。
   • 使用 –out 标志，启用 K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM 选项，并按以下方式指定 RW 端点 URL，运行 k6 脚本：

   原生直方图

   K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
   K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM=true \
   k6 run -o experimental-prometheus-rw script.js

   HTTP Basic 身份验证

   K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write \
   K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM=true \
   K6_PROMETHEUS_RW_USERNAME=USERNAME \
   K6_PROMETHEUS_RW_PASSWORD=PASSWORD \
   k6 run -o experimental-prometheus-rw script.js

运行前面的 k6 run 命令后，k6 开始向 Prometheus 发送时间序列指标。所有时间序列都有 k6_ 前缀。它们在 Prometheus Web UI 中如下所示：

选项

k6 为远程写入输出提供专用选项。

添加静态标签

多个 k6 进程向同一个 Prometheus 端点发送指标时，可以使用 server 或 job_id 等标签区分时间序列。为每个需要独立标识的进程或任务设置不同的值。这样可以在部署或 CI 任务中配置标签，而无需修改测试脚本。

设置 K6_PROMETHEUS_RW_LABELS，为发送到远程写入端点的每个时间序列添加静态标签。使用逗号分隔的 key=value 对列表：

K6_PROMETHEUS_RW_LABELS="environment=production,server=srv1" \
k6 run -o experimental-prometheus-rw script.js

将 script.js 替换成你的测试脚本，并按照“将测试指标发送到远程写入端点”配置远程写入端点。

也可以在 JSON 配置文件中设置 collectors.experimental-prometheus-rw.labels：

{
  "collectors": {
    "experimental-prometheus-rw": {
      "labels": {
        "environment": "production",
        "server": "srv1"
      }
    }
  }
}

将它保存为 config.json，然后运行测试：

k6 run --config config.json -o experimental-prometheus-rw script.js

如果两个位置配置了同一个标签，K6_PROMETHEUS_RW_LABELS 的优先级高于 JSON 配置。

这些标签仅应用于远程写入输出。已有的时间序列标签，包括来自脚本 tags 的标签，优先于同名静态标签。k6 会忽略名称或值为空的标签，也会忽略保留标签 __name__。

过时的趋势指标

这个 k6 输出可以在测试结束时将时间序列标记为过时。要启用此选项，将环境变量 K6_PROMETHEUS_RW_STALE_MARKERS 设置为 true。

默认情况下，指标在最后一个样本被刷新后保持活跃 5 分钟，此后会自动标记为过时。有关过时状态的详细信息，请参阅 Prometheus 文档。

时间序列可视化

使用 Grafana 可视化时间序列时，可以使用 Explore UI，或导入已有的预构建仪表板：

• Grafana k6 提供的 k6 Prometheus 仪表板
• Grafana k6 提供的 k6 Prometheus（原生直方图）仪表板
• 社区提供的其他公开仪表板

如果你使用 Grafana Cloud，请参阅 Grafana Cloud Prometheus 文档。

对于本地环境，xk6-output-prometheus-remote 仓库包含一个 docker-compose 配置，用来创建 k6 Prometheus 和 k6 Prometheus（原生直方图）仪表板：

Docker Compose 示例

先克隆仓库，然后按以下步骤使用启动 Prometheus 和 Grafana 的 docker-compose.yml 文件：

1. 启动 Docker Compose 环境。

   docker compose up -d prometheus grafana

   # Output
   Creating xk6-output-prometheus-remote_grafana_1     ... done
   Creating xk6-output-prometheus-remote_prometheus_1  ... done

   Prometheus 启动时已启用原生直方图。可以使用同一个 Prometheus 实例，将 k6 趋势指标接收为原生直方图，或多个指标统计值。

2. 按照“将测试指标发送到远程写入端点”中的一个选项运行 k6 测试。

   趋势统计值

   K6_PROMETHEUS_RW_TREND_STATS=p(95),p(99),min,max \
   k6 run -o experimental-prometheus-rw script.js

   原生直方图

   K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM=true \
   k6 run -o experimental-prometheus-rw script.js

   可选地将 testid 标签设置为测试全局标签，将指标划分成独立的测试运行，并在预构建 Grafana 仪表板或 PromQL 查询中筛选具体测试结果。testid 可以是任何能够清楚标识测试运行的唯一字符串。

   趋势统计值

   K6_PROMETHEUS_RW_TREND_STATS=p(95),p(99),min,max \
   k6 run -o experimental-prometheus-rw --tag testid=<SET-HERE-A-UNIQUE-ID> script.js

   原生直方图

   K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM=true \
   k6 run -o experimental-prometheus-rw --tag testid=<SET-HERE-A-UNIQUE-ID> script.js

3. 测试运行后，访问 http://localhost:3000。如果启用了原生直方图，选择 k6 Prometheus（Native Histograms）仪表板；否则选择 k6 Prometheus Dashboard。