promtool

Prometheus 监控系统的工具集。

标志

标志	描述
-h, --help	显示上下文相关的帮助信息（也可以尝试 --help-long 和 --help-man）。
--version	显示应用程序版本。
--experimental	启用实验性命令。
--enable-feature ...	启用功能的逗号分隔列表。有效选项：promql-experimental-functions, promql-delayed-name-removal, promql-duration-expr, promql-extended-range-selectors。详情请参阅 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

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 服务器之前，请确保移除这些字段，因为服务器默认执行严格检查。	false
--agent	检查以 Agent 模式运行的 Prometheus 配置文件。

参数

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

promtool check web-config

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

参数

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

promtool check healthy

检查 Prometheus 服务器是否健康。

标志

标志	描述	默认值
--http.config.file	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool
--url	Prometheus 服务器的 URL。	https://:9090

promtool check ready

检查 Prometheus 服务器是否就绪。

标志

标志	描述	默认值
--http.config.file	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool
--url	Prometheus 服务器的 URL。	https://:9090

promtool check rules

检查规则文件是否有效。

标志

标志	描述	默认值
--lint	要应用的 Lint 检查。可用选项有：all, duplicate-rules, none。使用 --lint=none 禁用 Lint。	duplicate-rules
--lint-fatal	若发生 Lint 错误，则以退出码 3 退出。	false
--ignore-unknown-fields	忽略规则文件中的未知字段。当你想用自定义元数据扩展规则文件时，这很有用。在将它们加载到 Prometheus 服务器之前，请确保移除这些字段，因为服务器默认执行严格检查。	false

参数

参数	描述
rule-files	要检查的规则文件，默认为从标准输入读取。

promtool check metrics

通过标准输入传递 Prometheus 指标以进行一致性和正确性检查，并可选地执行基数分析。

示例

$ cat metrics.prom | promtool check metrics

$ curl -s https://:9090/metrics  | promtool check metrics --extended

$ curl -s https://:9100/metrics  | promtool check metrics --extended --lint=none

标志

标志	描述	默认值
--extended	打印与指标基数相关的扩展信息。
--lint	应用于指标的 Lint 检查。可用选项有：all, none。使用 --lint=none 禁用指标 Lint。	all

promtool query

针对 Prometheus 服务器运行查询。

标志

标志	描述	默认值
-o, --format	查询的输出格式。	promql
--http.config.file	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool

promtool query instant

执行即时查询 (instant query)。

标志

标志	描述
--time	查询评估时间（RFC3339 或 Unix 时间戳）。

参数

参数	描述	必需
server	要查询的 Prometheus 服务器。	是
expr	PromQL 查询表达式。	是

promtool query range

执行范围查询 (range query)。

标志

标志	描述
--header	发送到服务器的额外请求头。
--start	查询范围的开始时间（RFC3339 或 Unix 时间戳）。
--end	查询范围的结束时间（RFC3339 或 Unix 时间戳）。
--step	查询步长（持续时间）。

参数

参数	描述	必需
server	要查询的 Prometheus 服务器。	是
expr	PromQL 查询表达式。	是

promtool query series

执行序列查询 (series query)。

标志

标志	描述
--match ...	序列选择器。可以多次指定。
--start	开始时间（RFC3339 或 Unix 时间戳）。
--end	结束时间（RFC3339 或 Unix 时间戳）。

参数

参数	描述	必需
server	要查询的 Prometheus 服务器。	是

promtool query labels

执行标签查询 (labels query)。

标志

标志	描述
--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

获取性能分析 (pprof) 调试信息。

参数

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

promtool debug metrics

获取指标调试信息。

参数

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

promtool debug all

获取所有调试信息。

参数

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

promtool push

推送到 Prometheus 服务器。

标志

标志	描述
--http.config.file	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool

promtool push metrics

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

标志

标志	描述	默认值
--label	附加到指标的标签。可以多次指定。	job=promtool
--timeout	等待推送指标的超时时间。	30s
--header	Prometheus 远程写入请求头。
--protobuf_message	写入时使用的 Protobuf 消息类型 (prometheus.WriteRequest 或 io.prometheus.write.v2.Request)。	prometheus.WriteRequest

参数

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

promtool test

单元测试。

标志

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

promtool test rules

规则的单元测试。

标志

标志	描述	默认值
--run ...	如果设置，将仅运行名称与正则表达式匹配的测试组。可以多次指定。
--debug	启用单元测试调试。	false
--diff	[实验性] 打印预期输出与实际输出之间的彩色差异输出。	false
--ignore-unknown-fields	忽略测试文件中的未知字段。当你想用自定义元数据扩展规则文件时，这很有用。在将它们加载到 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	要分析的序列选择器。目前仅支持一组匹配器。

参数

参数	描述	默认值
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 重放生成数据块的情况（默认为数据库路径）。沙盒会在结束时进行清理。
--min-time	要转储的最小时间戳（以 Unix 纪元以来的毫秒数为单位）。	-9223372036854775808
--max-time	要转储的最大时间戳（以 Unix 纪元以来的毫秒数为单位）。	9223372036854775807
--match ...	序列选择器。可以多次指定。	{__name__=~'(?s:.*)'}
--format	转储的输出格式（prom（默认）或 seriesjson）。	prom

参数

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

promtool tsdb dump-openmetrics

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

标志

标志	描述	默认值
--sandbox-dir-root	将要创建沙盒目录的根目录。此沙盒用于 WAL 重放生成数据块的情况（默认为数据库路径）。沙盒会在结束时进行清理。
--min-time	要转储的最小时间戳（以 Unix 纪元以来的毫秒数为单位）。	-9223372036854775808
--max-time	要转储的最大时间戳（以 Unix 纪元以来的毫秒数为单位）。	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	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool
--url	Prometheus API 的 URL，用于回填规则的数据。	https://: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	要删除的标签名称。	是