promtool

Prometheus 监控系统的 promtool 使用指南。

标志

标志（flags）	描述
`-h`, `--help`	显示上下文相关的帮助（也尝试使用`--help-long`和`--help-man`）。
`--version`	显示应用程序版本。
`--experimental`	启用实验性命令。
`--enable-feature <...>`	指定启用的逗号分隔功能名称列表（仅限与 PromQL 相关且无默认端口）。有关选项和更多详细信息，请参阅特性标志。

命令

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

`promtool help`

显示帮助。

参数

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

`promtool check`

检查资源的有效性。

标志

标志	描述
`--extended`	打印与指标基数相关的额外信息。

`promtool check service-discovery`

对给定的采集任务（job）名称执行服务发现并报告结果，包括重标记（relabeling）。

标志

标志	描述	默认值
`<font style="color:rgb(51, 51, 51);background-color:rgb(249, 242, 244);">--timeout</font>`	等待发现的超时时间。	`<font style="color:rgb(51, 51, 51);background-color:rgb(249, 242, 244);">30s</font>`

参数

参数	描述	是否必需
config-file	需要检查的配置文件。	是
job	要运行服务发现的采集任务。	是

`promtool check config`

检查配置文件是否有效。

标志

标志	描述	默认值
`--syntax-only`	只检查配置文件的语法，忽略配置中引用的文件和内容验证。
`--lint`	应用于配置中指定规则的校验检查。可用选项是：all, duplicate-rules, none。使用`--lint=none` 来禁用校验。	`duplicate-rules`
`--lint-fatal`	当校验错误时，以退出码3退出。	`false`
`--agent`	检查 Prometheus 在 Agent 模式的配置文件。

参数

参数	描述	是否必需
config-files	需要检查的配置文件。	是

`promtool check web-config`

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

参数

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

`promtool check healthy`

检查 Prometheus 服务器是否健康。

标志

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

`promtool check ready`

检查 Prometheus 服务器是否就绪。

标志

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

`promtool check rules`

检查规则文件是否有效。

参数

参数	描述
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`	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 remote write 端点（仅用于测试目的）。

标志

标志	描述	默认值
`--label` `...`	附加到指标的标签。可以指定多次。	`job=promtool`
`--timeout`	推送指标的等待时间。	`30s`
`--header`	Remote write 头部。

参数

参数	描述	是否必要
remote-write-url	要推送指标的 Prometheus remote write URL。	是
metric-files	要推送的指标文件，默认从标准输入读取。

`promtool test`

单元测试。

`promtool test rules`

规则的单元测试。

标志

标志	描述	默认值
`--run` `...`	如果设置了，则只运行匹配正则表达式的测试组。可以指定多次。
`--diff`	[实验性] 打印预期与接收输出之间的彩色差异输出。	`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`	需要进行分析的序列匹配器。目前只支持一组匹配器。

参数

参数	描述	默认值
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 回放生成块的情况下，沙盒目录会在结束时被清理。	`data/`
`--min-time`	dump 的最小时间戳。	`-9223372036854775808`
`--max-time`	dump 的最大时间戳。	`9223372036854775807`
`--match`	序列选择器。可以多次指定。	`{__name__=~'(?s:.*)'}`

参数

参数	描述	默认值
db path	数据库路径（默认是`data/`）。	`data/`

`promtool tsdb dump-openmetrics`

(实验性) 将样本从 TSDB 导出到 OpenMetrics 文本格式，排除原生 Histogram 和过期标记，这些在OpenMetrics 中都不可表示。

标志

标志	描述	默认值
`--sandbox-dir-root`	创建沙盒目录的根目录，在 WAL 回放生成块的情况下，沙盒目录会在结束时被清理。	`data/`
`--min-time`	dump 的最小时间戳。	`-9223372036854775808`
`--max-time`	dump 的最大时间戳。	`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`。	`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`

编辑查询内包含的标签匹配器。

`promtool promql label-matchers set`

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

标志

标志	描述	默认值
`-t`, `--type`	要设置的标签匹配器类型。	`=`

参数

参数	描述	是否必填
query	PromQL 查询。	是
name	设置的标签匹配器名称。	是
value	设置的标签匹配器值。	是

`promtool promql label-matchers delete`

删除查询中的标签。

参数

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

该文档基于 Prometheus 官方文档翻译而成。