promtool

Prometheus 监控系统的工具。

标志

标志 描述
-h, --help 显示上下文相关的帮助信息（也可以尝试 --help-long 和 --help-man）。
--version 显示应用程序版本。
--experimental 启用实验性命令。
--enable-feature ... 逗号分隔的要启用的特性名称。目前未使用。

命令

命令 描述
help 显示帮助。
check 检查资源的有效性。
query 针对 Prometheus 服务器运行查询。
debug 获取调试信息。
push 推送到 Prometheus 服务器。
test 单元测试。
tsdb 运行 tsdb 命令。
promql PromQL 格式化和编辑。需要 --experimental 标志。

promtool help

显示帮助。

参数

参数 描述
command 显示命令的帮助。

promtool check

检查资源的有效性。

标志

标志 描述 默认值
--query.lookback-delta 服务器的最大查询回溯持续时间。 5m
--extended 打印与指标基数相关的扩展信息。
promtool check service-discovery

为给定的作业名称执行服务发现，并报告结果，包括重新标记。

标志
标志 描述 默认值
--timeout 等待发现结果的时间。 30s
参数
参数 描述 必需
config-file Prometheus 配置文件。 是
job 要运行服务发现的作业。 是
promtool check config

检查配置文件是否有效。

标志
标志 描述 默认值
--syntax-only 仅检查配置文件语法，忽略配置文件中引用的文件和内容验证
--lint 应用于配置文件中指定的规则/抓取配置的 Lint 检查。可用选项有：all, duplicate-rules, none, too-long-scrape-interval。使用 --lint=none 禁用 linting duplicate-rules
--lint-fatal 使 lint 错误以退出代码 3 退出。 false
--ignore-unknown-fields 忽略配置文件读取的规则组中未知的字段。当您想要使用自定义元数据扩展规则文件时，这非常有用。确保在将这些字段加载到 Prometheus 服务器之前删除它们，因为默认情况下 Prometheus 服务器会执行严格的检查。 false
--agent 检查 Prometheus Agent 模式下的配置文件。
参数
参数 描述 必需
config-files 要检查的配置文件。 是
promtool check web-config

检查 Web 配置文件是否有效。

参数
参数 描述 必需
web-config-files 要检查的配置文件。 是
promtool check healthy

检查 Prometheus 服务器是否健康。

标志
标志 描述 默认值
--http.config.file Promtool 连接到 Prometheus 的 HTTP 客户端配置文件。
--url Prometheus 服务器的 URL。 http://localhost:9090
promtool check ready

检查 Prometheus 服务器是否准备就绪。

标志
标志 描述 默认值
--http.config.file Promtool 连接到 Prometheus 的 HTTP 客户端配置文件。
--url Prometheus 服务器的 URL。 http://localhost:9090
promtool check rules

检查规则文件是否有效。

标志
标志 描述 默认值
--lint 要应用的 Lint 检查。可用选项有：all, duplicate-rules, none。使用 --lint=none 禁用 linting duplicate-rules
--lint-fatal 使 lint 错误以退出代码 3 退出。 false
--ignore-unknown-fields 忽略规则文件中未知的字段。当您想要使用自定义元数据扩展规则文件时，这非常有用。确保在将这些字段加载到 Prometheus 服务器之前删除它们，因为默认情况下 Prometheus 服务器会执行严格的检查。 false
参数
参数 描述
rule-files 要检查的规则文件，默认从标准输入读取。
promtool check metrics

通过 stdin 传递 Prometheus 指标以检查其一致性和正确性。

示例

$ cat metrics.prom | promtool check metrics

$ curl -s http://localhost:9090/metrics | promtool check metrics

promtool query

针对 Prometheus 服务器运行查询。

标志

标志 描述 默认值
-o, --format 查询的输出格式。 promql
--http.config.file Promtool 连接到 Prometheus 的 HTTP 客户端配置文件。
promtool query instant

运行即时查询。

标志
标志 描述
--time 查询评估时间（RFC3339 或 Unix 时间戳）。
参数
参数 描述 必需
server 要查询的 Prometheus 服务器。 是
expr PromQL 查询表达式。 是
promtool query range

运行范围查询。

标志
标志 描述
--header 要发送到服务器的额外标头。
--start 查询范围开始时间（RFC3339 或 Unix 时间戳）。
--end 查询范围结束时间（RFC3339 或 Unix 时间戳）。
--step 查询步长（持续时间）。
参数
参数 描述 必需
server 要查询的 Prometheus 服务器。 是
expr PromQL 查询表达式。 是
promtool query series

运行序列查询。

标志
标志 描述
--match ... 序列选择器。可以多次指定。
--start 开始时间（RFC3339 或 Unix 时间戳）。
--end 结束时间（RFC3339 或 Unix 时间戳）。
参数
参数 描述 必需
server 要查询的 Prometheus 服务器。 是
promtool query labels

运行标签查询。

标志
标志 描述
--start 开始时间（RFC3339 或 Unix 时间戳）。
--end 结束时间（RFC3339 或 Unix 时间戳）。
--match ... 序列选择器。可以多次指定。
参数
参数 描述 必需
server 要查询的 Prometheus 服务器。 是
name 要为其提供标签值的标签名称。 是
promtool query analyze

针对您的 Prometheus 运行查询，以分析某些指标的使用模式。

标志
标志 描述 默认值
--server 要查询的 Prometheus 服务器。
--type 指标类型：histogram。
--duration 要分析的时间范围。 1h
--time 查询时间（RFC3339 或 Unix 时间戳），默认为现在。
--match ... 序列选择器。可以多次指定。

promtool debug

获取调试信息。

promtool debug pprof

获取性能分析调试信息。

参数
参数 描述 必需
server 要从中获取 pprof 文件的 Prometheus 服务器。 是
promtool debug metrics

获取指标调试信息。

参数
参数 描述 必需
server 要从中获取指标的 Prometheus 服务器。 是
promtool debug all

获取所有调试信息。

参数
参数 描述 必需
server 要从中获取所有调试信息的 Prometheus 服务器。 是

promtool push

推送到 Prometheus 服务器。

标志

标志 描述
--http.config.file Promtool 连接到 Prometheus 的 HTTP 客户端配置文件。
promtool push metrics

将指标推送到 Prometheus 远程写入（仅用于测试目的）。

标志
标志 描述 默认值
--label 要附加到指标的标签。可以多次指定。 job=promtool
--timeout 等待推送指标的时间。 30s
--header Prometheus 远程写入标头。
参数
参数 描述 必需
remote-write-url 要推送指标的 Prometheus 远程写入 URL。 是
metric-files 要推送的指标文件，默认从标准输入读取。

promtool test

单元测试。

标志

标志 描述
--junit 用于存储 JUnit XML 测试结果的文件路径。
promtool test rules

规则的单元测试。

标志
标志 描述 默认值
--run ... 如果设置，则仅运行名称与正则表达式匹配的测试组。可以多次指定。
--debug 启用单元测试调试。 false
--diff [实验性] 打印预期输出和接收输出之间彩色差异输出。 false
--ignore-unknown-fields 忽略测试文件中未知的字段。当您想要使用自定义元数据扩展规则文件时，这非常有用。确保在将这些字段加载到 Prometheus 服务器之前删除它们，因为默认情况下 Prometheus 服务器会执行严格的检查。 false
参数
参数 描述 必需
test-rule-file 单元测试文件。 是

promtool tsdb

运行 tsdb 命令。

promtool tsdb bench

运行基准测试。

promtool tsdb bench write

运行写入性能基准测试。

标志
标志 描述 默认值
--out 设置输出路径。 benchout
--metrics 要读取的指标数量。 10000
--scrapes 要模拟的抓取数量。 3000
参数
参数 描述 默认值
file 包含样本数据的输入文件，默认为 (../../tsdb/testdata/20kseries.json)。 ../../tsdb/testdata/20kseries.json
promtool tsdb analyze

分析流失率、标签对基数和压缩效率。

标志
标志 描述 默认值
--limit 每个列表中要显示的项目数。 20
--extended 运行扩展分析。
--match 要分析的序列选择器。现在仅支持 1 组匹配器。
参数
参数 描述 默认值
db path 数据库路径（默认为 data/）。 data/
block id 要分析的块（默认为最后一个块）。
promtool tsdb list

列出 tsdb 块。

标志
标志 描述
-r, --human-readable 打印人类可读的值。
参数
参数 描述 默认值
db path 数据库路径（默认为 data/）。 data/
promtool tsdb dump

从 TSDB 转储样本。

标志
标志 描述 默认值
--sandbox-dir-root 将创建沙箱目录的根目录，此沙箱用于处理 WAL 重放生成 chunk 的情况（默认为数据库路径）。沙箱在最后会被清理。
--min-time 要转储的最小时间戳。 -9223372036854775808
--max-time 要转储的最大时间戳。 9223372036854775807
--match ... 序列选择器。可以多次指定。 {__name__=~'(?s:.*)'}
参数
参数 描述 默认值
db path 数据库路径（默认为 data/）。 data/
promtool tsdb dump-openmetrics

[实验性] 将 TSDB 中的样本转储为 OpenMetrics 文本格式，排除原生直方图和过时标记，这些在 OpenMetrics 中无法表示。

标志
标志 描述 默认值
--sandbox-dir-root 将创建沙箱目录的根目录，此沙箱用于处理 WAL 重放生成 chunk 的情况（默认为数据库路径）。沙箱在最后会被清理。
--min-time 要转储的最小时间戳。 -9223372036854775808
--max-time 要转储的最大时间戳。 9223372036854775807
--match ... 序列选择器。可以多次指定。 {__name__=~'(?s:.*)'}
参数
参数 描述 默认值
db path 数据库路径（默认为 data/）。 data/
promtool tsdb create-blocks-from

[实验性] 从输入导入样本并生成 TSDB 块。请参考存储文档以获取更多详细信息。

标志
标志 描述
-r, --human-readable 打印人类可读的值。
-q, --quiet 不打印创建的块。
promtool tsdb create-blocks-from openmetrics

从 OpenMetrics 输入导入样本并生成 TSDB 块。请参考存储文档以获取更多详细信息。

标志
标志 描述
--label 要附加到指标的标签。可以多次指定。示例 --label=label_name=label_value
参数
参数 描述 默认值 必需
input file 要从中读取样本的 OpenMetrics 文件。 是
output directory 生成的块的输出目录。 data/
promtool tsdb create-blocks-from rules

为新的记录规则创建数据块。

标志
标志 描述 默认值
--http.config.file Promtool 连接到 Prometheus 的 HTTP 客户端配置文件。
--url 用于回填规则数据的 Prometheus API 的 URL。 http://localhost:9090
--start 开始回填新规则的时间。必须是 RFC3339 格式的日期或 Unix 时间戳。必需。
--end 如果提供了结束时间，则将规则文件中提供的所有记录规则回填到结束时间。默认将回填到 3 小时前。必须是 RFC3339 格式的日期或 Unix 时间戳。
--output-dir 生成的块的输出目录。 data/
--eval-interval 如果在记录规则文件中未设置值，则在回填时评估规则的频率。 60s
参数
参数 描述 必需
rule-files 包含要回填的记录规则的一个或多个文件的列表。文件中列出的所有记录规则都将被回填。告警规则不会被评估。 是

promtool promql

PromQL 格式化和编辑。需要 --experimental 标志。

promtool promql format

将 PromQL 查询格式化为美观的打印形式。

参数
参数 描述 必需
query PromQL 查询。 是
promtool promql label-matchers

编辑现有 PromQL 查询中包含的标签匹配器。

promtool promql label-matchers set

在查询中设置标签匹配器。

标志
标志 描述 默认值
-t, --type 要设置的标签匹配器的类型。 =
参数
参数 描述 必需
query PromQL 查询。 是
name 要设置的标签匹配器的名称。 是
value 要设置的标签匹配器的值。 是
promtool promql label-matchers delete

从查询中删除标签。

参数
参数 描述 必需
query PromQL 查询。 是
name 要删除的标签的名称。 是

本文档是开源的。请提交 issue 或 pull request 来帮助改进它。