promtool 完整命令参考与实战指南：Prometheus 的配置校验、查询诊断、TSDB 运维与 PromQL 编辑

promtool 是 Prometheus 官方随发行版提供的命令行工具，覆盖配置与规则文件校验、服务端健康探测、即时/范围查询、指标推送、规则单元测试、TSDB 数据运维以及实验性 PromQL 编辑等场景。本文基于 docs/command-line/promtool.md 的完整命令参考展开，并结合 cmd/promtool/main.go 等源码补充每个命令的默认值、退出码与底层实现机制，帮助你把 promtool 真正用进日常运维与 CI 流程。

一、全局标志与命令总览

promtool 基于 kingpin 框架构建（见 cmd/promtool/main.go），顶层支持以下标志：

标志	说明
-h, --help	显示上下文相关帮助（还支持 --help-long 与 --help-man）
--version	显示版本号
--experimental	启用实验性命令（目前主要是 promtool promql 子命令族）
--enable-feature ...	以逗号分隔启用功能特性，有效选项：promql-experimental-functions、promql-delayed-name-removal、promql-extended-range-selectors，更多细节可参考仓库中的 功能特性文档

命令族全景如下：

命令	说明
help	显示帮助
check	校验各类资源的合法性
query	对 Prometheus 服务器执行查询
debug	拉取调试信息
push	向 Prometheus 服务器推送数据
test	单元测试（规则测试）
tsdb	执行 TSDB 相关操作
promql	PromQL 格式化与编辑（需要 --experimental 标志）

实验性命令的守卫逻辑在 cmd/promtool/main.go 中实现：未设置 --experimental 时直接提示并以退出码 1 退出。

二、与受保护服务器通信：--http.config.file

check healthy、check ready、query、push、tsdb create-blocks-from rules 等需要连接服务器的命令，都支持 --http.config.file 指定一个 HTTP 客户端配置文件，用于提供 Basic 认证、Bearer 令牌、OAuth2 或 TLS 证书等凭据。例如：

promtool check healthy --url=http://localhost:9090 --http.config.file=http-config-file.yml

该文件的完整 YAML schema、oauth2 与 tls_config 子结构，见仓库文档 docs/configuration/promtool.md，可直接复制的示例文件位于 documentation/examples/promtool-http-config-file.yml。关键要点：

• basic_auth 与 authorization 互斥；password、password_file、password_ref 三者互斥；
• authorization 默认类型为 Bearer，credentials 与 credentials_file 互斥；
• tls_config 支持 ca/cert/key 的文件或内联文本三种形式，min_version/max_version 接受 TLS10～TLS13；
• follow_redirects 与 enable_http2 默认均为 true，还支持 proxy_url、no_proxy、proxy_from_environment、http_headers 等代理与请求头配置。

从源码看，该文件通过 promconfig.LoadHTTPConfigFile 加载并构造 RoundTripper（cmd/promtool/main.go），且“文件在每次 HTTP 请求时读取”的特性意味着证书与配置变更可即时生效；同时源码明确禁止在 server URL 中内嵌 Basic 认证与 --http.config.file 同时使用。

三、promtool check 家族：配置、规则、指标与服务器状态

promtool check 本身带一个父级标志：

标志	说明	默认值
--query.lookback-delta	服务器的最大查询回溯时长（用于 lint 时判断抓取间隔是否过长）	5m

以下逐个子命令展开。

3.1 promtool check service-discovery

对给定 job 执行一次服务发现并报告结果（包含 relabeling 后的最终标签）：

promtool check service-discovery my-config.yml my-job

标志/参数	说明	默认值
--timeout	等待发现结果的时间	30s
config-file（必填）	Prometheus 配置文件	-
job（必填）	要执行发现的 job 名	-

实现位于 cmd/promtool/sd.go：加载配置后按 job_name 精确匹配（找不到时会列出全部可选 job 并以退出码 1 结束），然后为每个 ServiceDiscoveryConfig 创建 Discoverer 并在超时窗口内收集 target group；getSDCheckResult 会调用 scrape.PopulateDiscoveredLabels 与 scrape.PopulateLabels，因此输出 JSON 同时包含 discoveredLabels（relabel 前）与 labels（relabel 后）两组数据，正是排查“目标为什么没被抓到/标签为什么不对”的关键工具。

3.2 promtool check config

校验主配置文件的合法性：

promtool check config prometheus.yml

标志	说明	默认值
--syntax-only	只检查语法，忽略配置中引用的文件与内容校验	-
--lint	对配置中的规则/抓取配置应用的 lint 检查，可选 all、duplicate-rules、none、too-long-scrape-interval；--lint=none 关闭	duplicate-rules
--lint-fatal	lint 错误时以退出码 3 退出	false
--ignore-unknown-fields	忽略规则组中的未知字段（适合给规则文件附加自定义元数据；注意 Prometheus 服务器加载时默认严格检查，需自行去除这些字段）	false
--agent	以 Agent 模式校验配置文件	-
config-files（必填）	要检查的配置文件	-

从 cmd/promtool/main.go 的 CheckConfig 与 checkConfig 可以看到，非 --syntax-only 模式下它不仅做语法解析，还会：

• 展开 rule_files 的 glob 并逐个校验可访问性（显式指定的文件不存在直接报错）；
• 通过 cfg.GetScrapeConfigs() 加载全部抓取配置（含 scrape_config_files 引入），检查 authorization credentials 文件、TLS 证书/密钥成对出现且存在；
• 对 file_sd 引用的 JSON/YAML 文件按严格模式反序列化并校验 target group；对静态配置与 Alertmanager 的 file_sd 同样做 target 合法性检查（复用 scrape.TargetsFromGroup）；
• 对规则文件执行重复规则 lint（checkDuplicates 会按“指标名+标签集”排序去重，报告“Might cause inconsistency while recording expressions”）；
• 当 lint 选项包含 all 或 too-long-scrape-interval 时，启用 lintScrapeConfigs：若 scrape_interval >= --query.lookback-delta 则报“数据点将被标记为 stale”，这正是该父级标志的用途。

3.3 promtool check web-config

校验 web 配置文件（如 TLS 证书、外链管理等 web 段配置）：

promtool check web-config web-config.yml

参数 web-config-files 必填。源码实现非常薄：逐文件调用 exporter-toolkit 的 web.Validate（cmd/promtool/main.go），任一失败即以退出码 1 结束。

3.4 promtool check healthy / promtool check ready

探测 Prometheus 服务器的健康/就绪状态：

标志	说明	默认值
--http.config.file	HTTP 客户端配置文件（见上文第二节）	-
--url	Prometheus 服务器 URL	http://localhost:9090

实现上两者共用 CheckServerStatus（cmd/promtool/main.go）：healthy 请求 /-/healthy、ready 请求 /-/ready，使用 URL.JoinPath 拼接以避免尾斜杠产生 //-/healthy 这类路由不匹配问题；请求超时 10 秒，非 200 响应会打印 check failed: URL=..., status=...。这两个子命令是容器编排与 CI 中最常用的存活探测手段。

3.5 promtool check rules

校验规则文件，不传文件时从标准输入读取：

promtool check rules recording-rules.yml
cat alert-rules.yml | promtool check rules

标志	说明	默认值
--lint	可选 all、duplicate-rules、none；--lint=none 关闭	duplicate-rules
--lint-fatal	lint 错误时以退出码 3 退出	false
--ignore-unknown-fields	忽略规则文件中的未知字段（同 check config 的说明）	false
rule-files	要检查的规则文件，缺省读 stdin	-

解析走 model/rulefmt 包的 ParseFile/Parse，错误会区分“真实错误”与 errLint：有真实错误时退出码 1；仅有 lint 问题且 --lint-fatal 时退出码 3；都干净则退出码 0（cmd/promtool/main.go）。

3.6 promtool check metrics

通过 stdin 对 Prometheus 文本指标做一致性/正确性 lint，并可做基数分析。文档给出的典型用法：

$ cat metrics.prom | promtool check metrics

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

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

标志	说明	默认值
--extended	输出与指标基数相关的扩展信息	-
--lint	可选 all、none	all

从 CheckMetrics 源码 可确认几个行为细节：

• --extended 与 --lint=none 不能同时关闭，否则报错退出（必须至少启用其一）；
• lint 使用 client_golang 的 promlint，发现规范问题时退出码为 3（与 lint-fatal 一致的 lintErrExitCode）；
• --extended 输出“Metric / Cardinality / Percentage”表格，其中 histogram 按 2 + buckets 条 series 计、summary 按 2 + quantiles 条计（见 checkMetricsExtended），可用于快速定位高基数指标族。

四、promtool query 家族：命令行上的 HTTP API

query 组带一个输出格式标志：-o, --format，取值 promql（默认，人类可读）或 json（机器可读，走 jsonPrinter），以及统一的 --http.config.file。

4.1 promtool query instant

promtool query instant http://localhost:9090 'up == 1'

标志	说明
--time	查询评估时间（RFC3339 或 Unix 时间戳）
--header	附加请求头，可多次指定
server（必填）	目标服务器
expr（必填）	PromQL 表达式

4.2 promtool query range

promtool query range http://localhost:9090 'rate(http_requests_total[5m])' \
  --start='2026-09-03T00:00:00Z' --end='2026-09-03T01:00:00Z' --step=30s

标志：--header、--start（RFC3339 或 Unix 时间戳）、--end、--step（duration）；参数同为必填的 server 与 expr。

4.3 promtool query series

列出匹配 selector 的所有 series：

标志	说明
--match ...（必填）	series selector，可多次指定
--start / --end	起止时间（RFC3339 或 Unix 时间戳）

参数 server 必填。

4.4 promtool query labels

查询某标签的所有取值：

promtool query labels http://localhost:9090 job

标志	说明
--start / --end	起止时间
--match ...	series selector，可多次指定

参数 server 与 name（要查询取值的标签名）均必填。

4.5 promtool query analyze

分析特定指标的使用模式（当前支持 histogram 类型）：

标志	说明	默认值
--server（必填）	目标服务器	-
--type（必填）	指标类型：histogram	-
--duration	分析时间窗	1h
--time	查询时间，默认当前	-
--match ...（必填）	series selector，可多次指定	-

五、promtool debug：一键打包诊断信息

三个子命令都要求一个必填参数 server：

命令	说明
promtool debug pprof	拉取 profiling 调试信息
promtool debug metrics	拉取 metrics 调试信息
promtool debug all	拉取全部调试信息

从 endpoints 定义 可以看到具体抓取内容：

• debug pprof 依次请求 /debug/pprof/profile?seconds=30（存为 cpu.pb）、/debug/pprof/block、/debug/pprof/goroutine、/debug/pprof/heap、/debug/pprof/mutex、/debug/pprof/threadcreate，并对 profile 数据做解压再重新编码，另加 /debug/pprof/trace?seconds=30（trace.pb），最终打包成 debug.tar.gz；
• debug metrics 只抓取 /metrics 存为 metrics.txt；
• debug all 是二者的并集。

这意味着 promtool debug pprof <server> 一次执行会产生约 30 秒 CPU 采样 + 30 秒 trace 的等待，适合在报障时完整留证。

六、promtool push metrics：向 remote write 端点推送测试数据

cat metrics.prom | promtool push metrics http://localhost:9090/api/v1/write

标志	说明	默认值
--label	附加到指标上的标签，可多次指定	job=promtool
--timeout	推送等待时间	30s
--header	remote write 请求头，可多次指定	-
--protobuf_message	写入使用的 Protobuf 消息（prometheus.WriteRequest 或 io.prometheus.write.v2.Request）	prometheus.WriteRequest
--remote-write.path	覆盖默认 remote write API 路径	/api/v1/write
remote-write-url（必填）	remote write 地址	-
metric-files	指标文件，缺省读 stdin	-

注意其定位是“for testing purpose only”——用于向任意 remote write 接收端灌入受控数据，配合 --protobuf_message 还能验证 v2 write 协议链路。

七、promtool test rules：规则文件的单元测试

promtool test rules unittest.yml

标志	说明	默认值
--junit	生成 JUnit XML 测试结果的输出路径	-
--run ...	只运行名称匹配正则的测试组，可多次指定	-
--debug	开启单元测试调试	false
--diff	[Experimental] 以彩色 diff 输出期望与实际差异	false
--ignore-unknown-fields	忽略测试文件中的未知字段	false
test-rule-file（必填）	单元测试文件	-

测试文件格式见 docs/configuration/unit_testing_rules.md，仓库自带示例可参考 cmd/promtool/testdata/unittest.yml 与 cmd/promtool/testdata/rules_run.yml。从 main.go 的调用 可以看到，测试加载器默认启用 at 修饰符（EnableAtModifier: true）与负 offset（EnableNegativeOffset: true），--enable-feature=promql-delayed-name-removal 时还会启用延迟名字移除——所以用 promtool 写的规则单测比服务器默认解析器覆盖更多现代 PromQL 语法。

八、promtool tsdb：数据库块运维

8.1 promtool tsdb bench write

写入性能基准测试：

promtool tsdb bench write --out=benchout --metrics=10000 --scrapes=3000

标志	说明	默认值
--out	输出路径	benchout
--metrics	读取的指标数量	10000
--scrapes	模拟的抓取次数	3000
file	样例数据输入文件	../../tsdb/testdata/20kseries.json

8.2 promtool tsdb analyze

分析块内 churn（churn rate）、标签对基数与压缩效率：

标志	说明	默认值
--limit	每个列表展示多少条	20
--extended	运行扩展分析	-
--match	要分析的 series selector（当前仅支持一组 matcher）	-
db path	数据库路径	data/
block id	要分析的块 ID	最后一个块

8.3 promtool tsdb list

列出 TSDB 块，-r/--human-readable 以人类可读格式打印大小。参数 db path 默认 data/。

8.4 promtool tsdb dump

从 TSDB 导出数据（series+samples，或仅 series）：

标志	说明	默认值
--sandbox-dir-root	创建 sandbox 目录的根路径（WAL replay 产生 chunk 时使用），结束后自动清理	数据库路径
--min-time / --max-time	时间窗（Unix epoch 毫秒）	最小/最大 int64
--match ...	series selector，可多次指定	{__name__=~'(?s:.*)'}
--format	输出格式：prom 或 seriesjson	prom

参数 db path 默认 data/。seriesjson 模式只输出 series 的标签集合（formatSeriesSetLabelsToJSON，见 cmd/promtool/main.go），适合做标签基数盘点；仓库中的 cmd/promtool/testdata/dump-test-1.prom 等文件即为 dump 的期望输出样例。

8.5 promtool tsdb dump-openmetrics

[Experimental] 将 TSDB 中的 sample 导出为 OpenMetrics 文本格式；由于 OpenMetrics 无法表示，原生直方图与 staleness marker 会被排除。标志与 dump 相同（--sandbox-dir-root、--min-time、--max-time、--match），无 --format。

8.6 promtool tsdb create-blocks-from

[Experimental] 从输入导入样本并生成 TSDB 块，更多背景见 docs/storage.md。父命令带 -r/--human-readable 与 -q/--quiet 两个标志。

create-blocks-from openmetrics：从 OpenMetrics 文件导入：

promtool tsdb create-blocks-from openmetrics samples.om data/ --label=job=backfill

标志	说明
--label	附加标签，可多次指定，格式 --label=label_name=label_value
input file（必填）	OpenMetrics 输入文件
output directory	块输出目录，默认 data/

create-blocks-from rules：为新 recording rule 回填历史数据（backfill）：

promtool tsdb create-blocks-from rules \
  --start='2026-08-01T00:00:00Z' \
  --url=http://localhost:9090 \
  recording-rules.yml

标志	说明	默认值
--http.config.file	HTTP 客户端配置文件	-
--url	提供回填数据源的 Prometheus API 地址	http://localhost:9090
--start（必填）	回填起点，RFC3339 或 Unix 时间戳	-
--end	回填终点；不提供时回填到 3 小时前	3 小时前
--output-dir	块输出目录	data/
--eval-interval	规则文件未指定 interval 时的回填评估频率	60s
rule-files（必填）	一个或多个 recording rule 文件；仅回填 recording rule，不评估 alerting rule	-

从 importRules 源码 可确认：--end 缺省值确实由 time.Now().UTC().Add(-3 * time.Hour) 计算，且 start 必须早于 end。

九、promtool promql：实验性的 PromQL 格式化与编辑

以下命令都需要 --experimental 标志（缺失时输出 “This command is experimental and requires the --experimental flag to be set.”）。

9.1 promtool promql format

将 PromQL 查询格式化为 pretty-print 形式：

promtool --experimental promql format 'up{job="node"}'

参数 query 必填。实现即 ParseExpr 后打印 expr.Pretty(0)（cmd/promtool/main.go）。

9.2 promtool promql label-matchers set

在查询中设置一个 label matcher：

标志	说明	默认值
-t, --type	matcher 类型，取值 =、!=、=~、!~	=
query（必填）	PromQL 查询	-
name（必填）	要设置的标签名	-
value（必填）	要设置的标签值	-

9.3 promtool promql label-matchers delete

删除查询中的某个标签：参数 query 与 name 均必填。

从 labelsSetPromQL / labelsDeletePromQL 实现 看，二者通过 parser.Inspect 遍历 AST，对所有 VectorSelector 节点上同名的 matcher 做原位修改（已存在则替换，否则追加），再打印 expr.Pretty(0)——因此它们会作用于查询中所有向量选择器，而非仅第一个。

十、退出码约定与 CI 集成

文档未列出，但从 cmd/promtool/main.go 可以确认 promtool 使用三档退出码：

退出码	含义
0	成功
1	检查/操作失败（真实错误）
3	仅发现 lint 问题（--lint-fatal 的 check config/check rules，以及 check metrics 的 lint 问题）

因此一个常见的 CI 模式是：提交前运行 promtool check config prometheus.yml（语法错误退出码 1 阻断合并），并对 --lint=all --lint-fatal 的告警（退出码 3）做独立提醒级处理。

十一、参考资料与仓库路径索引

资源	路径
本文对应的命令参考文档	docs/command-line/promtool.md
--http.config.file 配置 schema	docs/configuration/promtool.md
HTTP 配置示例文件	documentation/examples/promtool-http-config-file.yml
promtool 入口与核心实现	cmd/promtool/main.go
服务发现检查实现	cmd/promtool/sd.go
规则单测示例	cmd/promtool/testdata/unittest.yml、docs/configuration/unit_testing_rules.md
合法配置示例	cmd/promtool/testdata/prometheus-config.good.yml
规则文件示例	cmd/promtool/testdata/rules.yml
规则 lint 示例	cmd/promtool/testdata/prometheus-rules.lint.yml
存储与 backfill 背景文档	docs/storage.md

promtool 的设计哲学是“服务器能做的校验，命令行先做一遍”：从 cmd/promtool/main.go 的结构可以看到，它直接复用与 Prometheus 主程序相同的 config.LoadFile、rulefmt.Parse、parser 与 scrape 目标构造逻辑，因此用它通过的配置文件与规则文件，几乎可以等价地通过服务器自身的加载检查——这也是把它放进部署流水线的前置环节的底气所在。