promtool

Prometheus 监控系统的工具。

标志

标志 描述
-h, --help 显示上下文相关的帮助（也可尝试 --help-long 和 --help-man）。
--version 显示应用程序版本。
--experimental 启用实验性命令。
--enable-feature ... 要启用的逗号分隔的特性名称。有效选项：promql-experimental-functions, promql-delayed-name-removal。更多详情请参阅 https://prometheus.ac.cn/docs/prometheus/latest/feature_flags/

命令

命令 描述
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

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

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

检查配置文件是否有效。

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

通过标准输入传递 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

运行 series 查询。

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

运行 labels 查询。

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

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

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

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

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

标志
标志 描述 默认值
--limit 每个列表中显示的条目数量。 20
--extended 运行扩展分析。
--match 要分析的 series 选择器。目前只支持 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 要导出的最小时间戳，单位为自 Unix 纪元以来的毫秒。 -9223372036854775808
--max-time 要导出的最大时间戳，单位为自 Unix 纪元以来的毫秒。 9223372036854775807
--match ... series 选择器。可多次指定。 {__name__=~'(?s:.*)'}
参数
参数 描述 默认值
db path 数据库路径（默认为 data/）。 data/
promtool tsdb dump-openmetrics

[实验性] 从 TSDB 导出样本到 OpenMetrics 文本格式，不包含原生直方图和过期标记，这些在 OpenMetrics 中无法表示。

标志
标志 描述 默认值
--sandbox-dir-root 将创建沙箱目录的根目录，此沙箱用于 WAL 重放生成 chunk 的情况（默认为数据库路径）。沙箱在结束时会被清理。
--min-time 要导出的最小时间戳，单位为自 Unix 纪元以来的毫秒。 -9223372036854775808
--max-time 要导出的最大时间戳，单位为自 Unix 纪元以来的毫秒。 9223372036854775807
--match ... series 选择器。可多次指定。 {__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 要删除的标签名称。 是

本文档是开源的。请通过提交问题或拉取请求帮助改进它。