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	Show help on command.

promtool check

检查资源的有效性。

Flags

标志	描述	Default
--query.lookback-delta	The server's maximum query lookback duration.	5m

promtool check service-discovery

Perform service discovery for the given job name and report the results, including relabeling.

Flags

标志	描述	Default
--timeout	The time to wait for discovery results.	30s

Arguments

参数	描述	Required
config-file	The prometheus config file.	Yes
job	The job to run service discovery for.	Yes

promtool check config

Check if the config files are valid or not.

Flags

标志	描述	Default
--syntax-only	Only check the config file syntax, ignoring file and content validation referenced in the config
--lint	Linting checks to apply to the rules/scrape configs specified in the config. Available options are: all, duplicate-rules, none, too-long-scrape-interval. Use --lint=none to disable linting	duplicate-rules
--lint-fatal	Make lint errors exit with exit code 3.	false
--ignore-unknown-fields	Ignore unknown fields in the rule groups read by the config files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.	false
--agent	Check config file for Prometheus in Agent mode.

Arguments

参数	描述	Required
config-files	The config files to check.	Yes

promtool check web-config

Check if the web config files are valid or not.

Arguments

参数	描述	Required
web-config-files	The config files to check.	Yes

promtool check healthy

Check if the Prometheus server is healthy.

Flags

标志	描述	Default
--http.config.file	HTTP client configuration file, see details at https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool
--url	The URL for the Prometheus server.	https://:9090

promtool check ready

Check if the Prometheus server is ready.

Flags

标志	描述	Default
--http.config.file	HTTP client configuration file, see details at https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool
--url	The URL for the Prometheus server.	https://:9090

promtool check rules

Check if the rule files are valid or not.

Flags

标志	描述	Default
--lint	Linting checks to apply. Available options are: all, duplicate-rules, none. Use --lint=none to disable linting	duplicate-rules
--lint-fatal	Make lint errors exit with exit code 3.	false
--ignore-unknown-fields	Ignore unknown fields in the rule files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.	false

Arguments

参数	描述
rule-files	The rule files to check, default is read from standard input.

promtool check metrics

Pass Prometheus metrics over stdin to lint them for consistency and correctness, and optionally perform cardinality analysis.

examples

$ 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

Flags

标志	描述	Default
--extended	Print extended information related to the cardinality of the metrics.
--lint	Linting checks to apply for metrics. Available options are: all, none. Use --lint=none to disable metrics linting.	all

promtool query

针对 Prometheus 服务器运行查询。

Flags

标志	描述	Default
-o, --format	Output format of the query.	promql
--http.config.file	HTTP client configuration file, see details at https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool

promtool query instant

Run instant query.

Flags

标志	描述
--time	Query evaluation time (RFC3339 or Unix timestamp).

Arguments

参数	描述	Required
server	Prometheus server to query.	Yes
expr	PromQL query expression.	Yes

promtool query range

Run range query.

Flags

标志	描述
--header	Extra headers to send to server.
--start	Query range start time (RFC3339 or Unix timestamp).
--end	Query range end time (RFC3339 or Unix timestamp).
--step	Query step size (duration).

Arguments

参数	描述	Required
server	Prometheus server to query.	Yes
expr	PromQL query expression.	Yes

promtool query series

Run series query.

Flags

标志	描述
--match ...	Series selector. Can be specified multiple times.
--start	Start time (RFC3339 or Unix timestamp).
--end	End time (RFC3339 or Unix timestamp).

Arguments

参数	描述	Required
server	Prometheus server to query.	Yes

promtool query labels

Run labels query.

Flags

标志	描述
--start	Start time (RFC3339 or Unix timestamp).
--end	End time (RFC3339 or Unix timestamp).
--match ...	Series selector. Can be specified multiple times.

Arguments

参数	描述	Required
server	Prometheus server to query.	Yes
name	Label name to provide label values for.	Yes

promtool query analyze

Run queries against your Prometheus to analyze the usage pattern of certain metrics.

Flags

标志	描述	Default
--server	Prometheus server to query.
--type	Type of metric: histogram.
--duration	Time frame to analyze.	1h
--time	Query time (RFC3339 or Unix timestamp), defaults to now.
--match ...	Series selector. Can be specified multiple times.

promtool debug

获取调试信息。

promtool debug pprof

Fetch profiling debug information.

Arguments

参数	描述	Required
server	Prometheus server to get pprof files from.	Yes

promtool debug metrics

Fetch metrics debug information.

Arguments

参数	描述	Required
server	Prometheus server to get metrics from.	Yes

promtool debug all

Fetch all debug information.

Arguments

参数	描述	Required
server	Prometheus server to get all debug information from.	Yes

promtool push

推送到 Prometheus 服务器。

Flags

标志	描述
--http.config.file	HTTP client configuration file, see details at https://prometheus.ac.cn/docs/prometheus/latest/configuration/promtool

promtool push metrics

Push metrics to a prometheus remote write (for testing purpose only).

Flags

标志	描述	Default
--label	Label to attach to metrics. Can be specified multiple times.	job=promtool
--timeout	The time to wait for pushing metrics.	30s
--header	Prometheus remote write header.
--protobuf_message	Protobuf message to use when writing (prometheus.WriteRequest or io.prometheus.write.v2.Request).	prometheus.WriteRequest

Arguments

参数	描述	Required
remote-write-url	Prometheus remote write url to push metrics.	Yes
metric-files	The metric files to push, default is read from standard input.

promtool test

单元测试。

Flags

标志	描述
--junit	File path to store JUnit XML test results.

promtool test rules

Unit tests for rules.

Flags

标志	描述	Default
--run ...	If set, will only run test groups whose names match the regular expression. Can be specified multiple times.
--debug	Enable unit test debugging.	false
--diff	[Experimental] Print colored differential output between expected & received output.	false
--ignore-unknown-fields	Ignore unknown fields in the test files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.	false

Arguments

参数	描述	Required
test-rule-file	The unit test file.	Yes

promtool tsdb

运行 tsdb 命令。

promtool tsdb bench

Run benchmarks.

promtool tsdb bench write

Run a write performance benchmark.

Flags

标志	描述	Default
--out	Set the output path.	benchout
--metrics	Number of metrics to read.	10000
--scrapes	Number of scrapes to simulate.	3000

Arguments

参数	描述	Default
file	Input file with samples data, default is (../../tsdb/testdata/20kseries.json).	../../tsdb/testdata/20kseries.json

promtool tsdb analyze

分析告警、标签对基数和压缩效率。

命令行参数

标志	描述	Default
--limit	每个列表显示多少项。	20
--extended	运行扩展分析。
--match	要分析的序列选择器。目前只支持1组匹配器。

参数

参数	描述	Default
db 路径	数据库路径 (默认为 data/）。	data/
块 ID	要分析的块 (默认为最后一个块）。

promtool tsdb list

列出 tsdb 块。

命令行参数

标志	描述
-r, --human-readable	打印人类可读的值。

参数

参数	描述	Default
db 路径	数据库路径 (默认为 data/）。	data/

promtool tsdb dump

从 TSDB 转储数据 (序列+样本，或可选仅序列）。

命令行参数

标志	描述	Default
--sandbox-dir-root	将创建沙盒目录的根目录，如果 WAL 重放生成了块，则使用此沙盒（默认为数据库路径）。沙盒将在最后被清理。
--min-time	要转储的最小时间戳，以自 Unix 纪元以来的毫秒为单位。	-9223372036854775808
--max-time	要转储的最大时间戳，以自 Unix 纪元以来的毫秒为单位。	9223372036854775807
--match ...	Series selector. Can be specified multiple times.	{__name__=~'(?s:.*)'}
--format	转储的输出格式 (prom (默认) 或 seriesjson)。	prom

参数

参数	描述	Default
db 路径	数据库路径 (默认为 data/）。	data/

promtool tsdb dump-openmetrics

[实验性] 从 TSDB 转储样本到 OpenMetrics 文本格式，排除在本机直方图和陈旧标记中无法表示的内容。

命令行参数

标志	描述	Default
--sandbox-dir-root	将创建沙盒目录的根目录，如果 WAL 重放生成了块，则使用此沙盒（默认为数据库路径）。沙盒将在最后被清理。
--min-time	要转储的最小时间戳，以自 Unix 纪元以来的毫秒为单位。	-9223372036854775808
--max-time	要转储的最大时间戳，以自 Unix 纪元以来的毫秒为单位。	9223372036854775807
--match ...	Series selector. Can be specified multiple times.	{__name__=~'(?s:.*)'}

参数

参数	描述	Default
db 路径	数据库路径 (默认为 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

参数

参数	描述	Default	Required
输入文件	要从中读取样本的 OpenMetrics 文件。		Yes
输出目录	生成块的输出目录。	data/

promtool tsdb create-blocks-from rules

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

命令行参数

标志	描述	Default
--http.config.file	HTTP client configuration file, see details at 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

参数

参数	描述	Required
rule-files	一个或多个包含要回填的记录规则的文件。文件中的所有记录规则都将被回填。警报规则不会被评估。	Yes

promtool promql

PromQL 格式化和编辑。需要 --experimental 标志。

promtool promql format

将 PromQL 查询格式化为美观打印形式。

参数

参数	描述	Required
query	PromQL 查询。	Yes

promtool promql label-matchers

编辑现有 PromQL 查询中的标签匹配器。

promtool promql label-matchers set

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

命令行参数

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

参数

参数	描述	Required
query	PromQL 查询。	Yes
name	要设置的标签匹配器的名称。	Yes
value	要设置的标签匹配器的值。	Yes

promtool promql label-matchers delete

从查询中删除标签。

参数

参数	描述	Required
query	PromQL 查询。	Yes
name	要删除的标签的名称。	Yes