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 要删除的标签名称。

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