菜单
文档breadcrumb arrow Grafana k6breadcrumb arrow 结果输出breadcrumb arrow 实时breadcrumb arrow Prometheus remote write
开源

Prometheus remote write

注意

这是一个实验性模块。

虽然我们力求保持实验性模块的稳定性，但可能需要引入破坏性更改。这可能会在未来的 k6 版本中发生，直到该模块完全稳定并作为 k6 核心模块“毕业”。有关更多信息，请参阅扩展毕业流程。

实验性模块保持高度稳定性，并遵循常规维护和安全措施。如果您有任何反馈或建议，请随时提交问题。

Prometheus remote write 是一种协议，可以实现在发送方和接收方之间可靠地实时传播数据。它有多种兼容的实现和存储集成。

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

在 k6 run 执行期间，该输出会获取为k6 指标生成的所有时间序列数据点。然后，它生成等效的 Prometheus 时间序列并将其发送到 Prometheus remote write 端点。

指标映射

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

  • 所有时间序列都带有 k6_ 命名空间前缀。
  • 所有时间序列都以后缀形式带有样本值的基本单位（如果 k6 知道该基本单位）。
  • 趋势和速率指标带有相应的后缀，以便更容易发现。
k6PrometheusName 标签
CounterCounterk6_*_total
GaugeGaugek6_*_<单位后缀>
RateGaugek6_*_rate
TrendCounter 和 Gauge (默认) 或 原生 Histogramk6_*_<单位后缀>

Trend 指标转换

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

  1. Counter 和 Gauge 指标 (默认)
  2. Prometheus 原生 Histogram

这两种选项都提供了高效的测试结果存储，同时支持高精度查询。

请注意，在这两种选项中，k6 都会在将 Trend 指标数据发送到 Prometheus 之前进行聚合。聚合数据的原因如下：

  • Prometheus 以毫秒精度 (ms) 存储数据，而 k6 指标以更高的精度（纳秒，ns）收集数据点。
  • 负载测试可能会生成大量数据点。高精度原始数据可能很快变得昂贵且难以扩展，并且在分析性能趋势时是不必要的。

1. Counter 和 Gauge

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

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

根据统计函数列表，k6 将所有 Trend 指标转换为相应的数学函数作为 Prometheus 指标。

例如，K6_PROMETHEUS_RW_TREND_STATS=p(90),p(95),max 将每个 Trend 指标转换为三个 Prometheus 指标，如下所示：

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

此选项提供了一种可配置的解决方案，用于在 Prometheus 中表示 Trend 指标，但存在以下缺点：

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

2. Prometheus 原生 Histogram

为了解决前一个选项的局限性，您可以将 k6 Trend 指标转换为高精度直方图，从而启用Prometheus 原生 Histogram。

使用此选项，每个 k6 Trend 指标都会映射到其对应的 Prometheus Histogram 指标：k6_*。然后，您可以使用 Prometheus Histogram 函数（例如 histogram_quantile()）进行查询。

注意

🌟 要了解使用 Histograms 的益处和结果，请观看Prometheus 中的高分辨率 Histograms。

⚠️ 请注意，原生 Histogram 是 Prometheus v2.40.0 中发布的实验性功能，其他 remote write 实现可能尚不支持它。未来，当 Prometheus 使此功能稳定时，k6 将考虑将其作为 Trend 指标的默认转换方法。

将测试指标发送到 remote write 端点

要在 Prometheus 2.x 中使用 remote write，请启用功能标志 --web.enable-remote-write-receiver。有关 remote write 存储选项，请参阅Prometheus 文档。

  1. 将 k6 指标发送到不带原生 Histogram 的 remote write 端点

    • 设置正在运行的 remote write 端点，并确保 k6 可以访问它。

    • 使用 --out 标志和 RW 端点的 URL 运行 k6 脚本，如下所示：

    Trend 统计

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

    HTTP 基本身份验证

    bash 
    K6_PROMETHEUS_RW_SERVER_URL=https://: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 以便能够查询 Trend 指标的附加统计信息。默认值为 p(99)。
    bash 
    K6_PROMETHEUS_RW_SERVER_URL=https://: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 指标发送到带原生 Histogram 的 remote write 端点

    • 在 Prometheus 2.40.0 或更高版本中启用功能标志 --enable-feature=native-histograms。设置正在运行的 remote write 端点，并确保 k6 可以访问它。

    • 使用 --out 标志、启用 K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM 选项以及 RW 端点的 URL 运行 k6 脚本，如下所示：

    原生 Histogram

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

    HTTP 基本身份验证

    bash 
    K6_PROMETHEUS_RW_SERVER_URL=https://: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 metrics as seen in the Prometheus UI

选项

k6 为 remote write 输出提供了特殊选项。

名称类型描述
K6_PROMETHEUS_RW_SERVER_URLstringPrometheus remote write 实现端点的 URL。默认值为 https://:9090/api/v1/write
K6_PROMETHEUS_RW_HEADERS_<header-key>string要在 HTTP 请求中包含的其他 header。可以使用指定格式设置，例如 K6_PROMETHEUS_RW_HEADERS_CUSTOM-HEADER-KEY=custom-header-value。
K6_PROMETHEUS_RW_HTTP_HEADERS逗号分隔的键值列表要在 HTTP 请求中包含的其他 header。K6_PROMETHEUS_RW_HTTP_HEADERS=key1:value1,key2:value2。
K6_PROMETHEUS_RW_PUSH_INTERVALstring指标聚合和上传到端点之间的间隔。默认值为 5s。
K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM布尔值如果为 true，则将所有定义的 trend 指标映射为原生 Histograms。默认值为 false。
K6_PROMETHEUS_RW_TREND_STATS字符串列表如果未启用原生 Histogram，则此选项定义要为所有定义的 trend 指标映射的统计函数。它是要包含的统计函数的逗号分隔列表（例如 p(90),avg,sum）。查看 trend 部分以获取支持的统计函数列表。默认值为 p(99)。
K6_PROMETHEUS_RW_INSECURE_SKIP_TLS_VERIFY布尔值如果为 true，则 HTTP 客户端会跳过端点上的 TLS 验证。默认值为 false。
K6_PROMETHEUS_RW_STALE_MARKERS布尔值如果为 true，则测试结束时会将所有已见的时间序列标记为 stale（过时）。默认值为 false。
K6_PROMETHEUS_RW_USERNAMEstringPrometheus remote write 端点 HTTP 基本身份验证的用户名。
K6_PROMETHEUS_RW_PASSWORDstringPrometheus remote write 端点 HTTP 基本身份验证的密码。
K6_PROMETHEUS_RW_CLIENT_CERTIFICATEstringPEM（Privacy-Enhanced Mail）格式客户端证书的路径。
K6_PROMETHEUS_RW_CLIENT_CERTIFICATE_KEYstringPEM 格式客户端私钥的路径。
K6_PROMETHEUS_RW_BEARER_TOKENstring设置 Authorization Bearer Token Header。
K6_PROMETHEUS_RW_SIGV4_REGIONstring设置工作区所在的 AWS 区域。与其他的 K6_PROMETHEUS_RW_SIGV4_* 配置一起启用请求签名。
K6_PROMETHEUS_RW_SIGV4_ACCESS_KEYstring设置 AWS 访问密钥。
K6_PROMETHEUS_RW_SIGV4_SECRET_KEYstring设置 AWS 秘密密钥。

Stale trend 指标

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

默认情况下，指标在最后一次刷新样本后的 5 分钟内处于活动状态。之后它们会自动标记为 stale。有关 staleness 的详细信息，请参阅Prometheus 文档。

时间序列可视化

要使用 Grafana 可视化时间序列，可以使用Explore UI 或导入任何现有的预建 Dashboard：

如果您是 Grafana Cloud 用户，请参考Grafana Cloud Prometheus 文档。

对于本地环境，xk6-output-prometheus-remote 仓库包含一个 docker-compose 设置，该设置会配置 k6 Prometheus 和 k6 Prometheus (Native Histograms) 仪表盘

Provisioned k6 Prometheus Dashboards

Docker Compose 示例

克隆仓库以开始使用，并按照以下步骤使用启动 Prometheus 和 Grafana 的docker-compose.yml文件

  1. 启动 Docker Compose 环境。

    shell 
    docker compose up -d prometheus grafana
    shell 
    # Output
Creating xk6-output-prometheus-remote_grafana_1     ... done
Creating xk6-output-prometheus-remote_prometheus_1  ... done

    Prometheus 启动时已启用原生直方图 (Native Histogram)。您可以使用同一个 Prometheus 实例接收 k6 趋势指标作为原生直方图或多种指标统计信息。

  2. 使用发送测试指标到远程写入端点中详细介绍的选项之一运行 k6 测试。

    Trend 统计

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

    原生直方图 (Native Histograms)

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

    可选地，您可以将 testid 标签设置为全量测试标签，以将指标分割到离散的测试运行中，并在预构建的 Grafana 仪表盘或 PromQL 查询中过滤特定测试结果。testid 可以是任何唯一的字符串，以便您清楚地识别测试运行。

    Trend 统计

    bash 
    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

    原生直方图 (Native Histograms)

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

  3. 运行测试后，访问https://:3000。如果您启用了原生直方图，请选择 k6 Prometheus (Native Histograms) 仪表盘；否则，请选择 k6 Prometheus 仪表盘。

    k6 Prometheus Dashboard