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	对配置中指定的规则/采集配置应用的 Linting 检查。可用选项有：all、duplicate-rules、none、too-long-scrape-interval。使用 --lint=none 禁用 Linting。	duplicate-rules
--lint-fatal	使 Linting 错误以退出码 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	要应用的 Linting 检查。可用选项有：all、duplicate-rules、none。使用 --lint=none 禁用 Linting。	duplicate-rules
--lint-fatal	使 Linting 错误以退出码 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

promtool query

针对 Prometheus 服务器运行查询。

标志

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

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	HTTP 客户端配置文件，详情请见 https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool

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 服务器之前将其删除，因为默认情况下它会执行严格检查。	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

参数

参数	描述	默认值	必填
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	要删除的标签的名称。	是