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

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

标志

标志	描述	默认值
--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	在代理模式下检查 Prometheus 的配置文件。

参数

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

promtool check web-config

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

参数

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

promtool check healthy

检查 Prometheus 服务器是否健康。

标志

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

promtool check ready

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

标志

标志	描述	默认值
--http.config.file	promtool 连接 Prometheus 的 HTTP 客户端配置文件。
--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 服务器之前，请确保将其删除，因为 Prometheus 服务器默认执行严格检查。	false

参数

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

promtool check metrics

通过标准输入传递 Prometheus 指标，以检查其一致性和正确性。

示例

$ cat metrics.prom | promtool check metrics

$ curl -s https://: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	指标类型：直方图。
--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 重放生成块的情况（默认为数据库路径）。沙盒在结束时会被清理。
--min-time	要转储的最小时间戳，以 Unix 纪元以来的毫秒数表示。	-9223372036854775808
--max-time	要转储的最大时间戳，以 Unix 纪元以来的毫秒数表示。	9223372036854775807
--match ...	序列选择器。可多次指定。	{__name__=~'(?s:.*)'}

参数

参数	描述	默认值
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

参数

参数	描述	默认值	必需
输入文件	从中读取样本的 OpenMetrics 文件。		是
输出目录	生成块的输出目录。	data/

promtool tsdb create-blocks-from rules

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

标志

标志	描述	默认值
--http.config.file	promtool 连接 Prometheus 的 HTTP 客户端配置文件。
--url	Prometheus API 的 URL，用于回填规则的数据源。	https://:9090
--start	开始回填新规则的时间。必须是 RFC3339 格式的日期或 Unix 时间戳。必需。
--end	如果提供了结束时间，则规则文件中提供的所有录制规则都将回填到该结束时间。默认情况下，将回填到3小时前。必须是 RFC3339 格式的日期或 Unix 时间戳。
--output-dir	生成块的输出目录。	data/
--eval-interval	如果在录制规则文件中未设置值，回填时评估规则的频率。	60秒

参数

参数	描述	必需
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	要设置的标签匹配器的名称。	是
值	要设置的标签匹配器的值。	是

promtool promql label-matchers delete

从查询中删除标签。

参数

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