Lazy loaded image
运维管理
Prometheus 命令行工具 promtool
Words 4489Read Time≈ 12 min
2026-1-10
2026-1-10
date
related_level
slug
type
relate_date
summary
status
tags
category
last_updated
Jan 10, 2026 07:17 PM
是否已更新
orginal_page
是否推荐
参考资料
功能：用于验证配置与规则、测试指标、执行查询、调试 TSDB 及性能分析
  • 验证 Prometheus 配置文件
  • 验证告警规则（Alerting Rules）和记录规则（Recording Rules）
  • 校验指标格式
  • 对 Prometheus 服务执行查询
    • 直接通过命令行执行 PromQL 表达式
  • 规则单元测试
    • 编写测试用例，验证告警/记录规则在给定模拟数据下的行为是否符合预期
  • 调试与性能分析（Debugging & Profiling）
    • 获取 Prometheus 的运行时状态（如 TSDB 快照信息）
    • 触发 pprof 性能分析（需配合 Web API）
    • 检查 WAL 或 block 数据
安装 promtool 二进制工具
  • export PROM_VER=3.9.1
  • curl -Lo prometheus.tar.gz https://github.com/prometheus/prometheus/releases/download/v$PROM_VER/prometheus-$PROM_VER.linux-amd64.tar.gz
  • tar -xzf prometheus.tar.gz --wildcards "*/promtool" --strip-components=1
  • chmod +x ./promtool
  • mv ./promtool /usr/local/bin/
promtool 的 HTTP 客户端配置文件
参考资料
  • 用于配置 HTTP 客户端 YAML 格式配置文件
    • 不是所有指令都会用到该配置，需要连接到 Prometheus 服务器才会用到
  • 配置章节：basic_auth, authorization, oauth2, tls_config, header
basic_auth, authorization 配置认证方式
  • 这两者互斥只能配置一个
oauth2 配置使用客户端凭据授权类型的 OAuth 2.0 身份验证
tls_config 配置 TLS 认证
http_headers.header 配置单个 HTTP header 的配置
其他：重定向，代理，HTTP2
promtool check 检查资源配置的有效性
通用选项
  • --query.lookback-delta 服务器 lookback 窗口，默认为 5 分钟
promtool check config <config-file> 检查配置文件有效性
  • 可用选项
    • --syntax-only 仅检查配置文件的语法，跳过对引用的外部资源（如规则文件、服务发现文件等）的内容验证
    • --lint 对配置中的规则（rules）和抓取（scrape）设置执行额外的“最佳实践”检查
      • 可选值：默认为 duplicate-rules
        • all：启用所有 lint 规则。
        • duplicate-rules：检查是否有重复的记录规则或告警规则名
        • too-long-scrape-interval：检查抓取间隔是否过长（例如 > 10m，可能影响数据精度）
        • none：禁用所有 lint 检查
    • --lint-fatal 如果 lint 检查失败（如发现重复规则），则以退出码 3 退出
      • 默认为 false
    • --ignore-unknown-fields 忽略规则文件（rule files）中的未知字段
      • 默认为 false
      • 允许在规则文件中添加自定义元数据（如 team: backend, owner: alice），便于团队管理，但必须在加载到 Prometheus 前移除否则会报错
    • --agent 以 Prometheus Agent 模式检查配置文件
  • promtool check web-config <web-config-files> 检查 web 配置文件有效性
  • promtool check rules [<rule-files>...] 检查规则文件是否有效
promtool check metrics 从 stdin 获取文本验证指标的一致性和正确性，并可选择执行基数分析
  • 可用选项
    • --extended 打印与指标基数相关的扩展信息
    • --lint 控制 lint 规则
      • 可选值（默认为 all）：all, none
  • 样例
    • cat metrics.prom | promtool check metrics
    • curl -s http://localhost:9090/metrics | promtool check metrics --extended
    • curl -s http://localhost:9090/metrics | promtool check metrics --extended --lint=none
promtool check healthy 检查服务器是否有效
promtool check ready 检查服务器是否就绪
promtool query 执行各种查询
通用选项
promtool query instant <server> <expr>
  • 可用选项
    • --time 查询的执行时间（RFC3339 或 UNIX 时间戳）
promtool query range <server> <expr>
  • 可用选项
    • --start, --end：查询时间范围（RFC3339 或 UNIX 时间戳）
    • --step：查询步长
    • --header：添加自定义 HTTP 请求头
promtool query series <server> --match=MATCH [--match=MATCH ...] 查询匹配的时间序列元数据
  • 可用选项
    • --match 一个或多个时间序列选择器
    • --start, --end：查询时间范围（RFC3339 或 UNIX 时间戳）
promtool query labels <server> <name> 查询标签
  • 可用选项
    • --match 一个或多个时间序列选择器
    • --start, --end：查询时间范围（RFC3339 或 UNIX 时间戳）
promtool query analyze --server=SERVER --type=TYPE --match=MATCH 针对 Prometheus 服务器运行查询以分析某些指标的使用模式
  • 可用选项
    • --match 一个或多个时间序列选择器
    • --type 指标类型：histogram
    • --time 查询的执行时间（RFC3339 或 UNIX 时间戳）
    • --duration 分析的时间范围，默认为 1h
promtool promql 格式化或编辑现有 PromQL 查询
  • 均需要启用 --experimental 标志
  • promtool promql format <query> 将 PromQL 查询格式化
promtool promql label-matchers set <query> <name> <value> 在现有 PromQL 查询中添加或修改某个标签匹配器
  • 可用选项
    • -t, --type 要设置的标签匹配器的类型，默认为 =
        • 标签匹配运算符 =, !=, =~, !~
        操作符
        含义
        =
        精确等于
        !=
        不等于
        =～
        正则匹配（完全锚定，等价于 ^...$）
        !～
        正则不匹配
  • promtool promql delete <query> <name> 从现有 PromQL 查询中移除指定标签匹配器
promtool test rule <test-rule-file>… 执行单元规则
可用选项
  • --run <regex> 可多次使用，仅运行名称匹配正则表达式的测试组
  • --junit 存放 JUnix XML 测试结果的路径
  • --diff 以彩色差异格式显示预期 vs 实际结果，提升可读性
    • 实验性
  • --ignore-unknown-fields 忽略测试文件或规则文件中的自定义字段
    • 方便扩展元数据（如 team: backend，但需在部署前清理）
  • --debug 启用调试模式
单元测试文件格式及样例
单元测试文件格式
<test_group> 测试组，包括模拟输入，告警规则，需要评估的表达式以及期望样本
<series> 用于模拟时间序列数据的输入格式
  • series: <string> 时间序列标识
  • values: <string> 样本值序列
<alert_test_case> 要评估的告警规则
<alert> 告警应包含的标签和注解
<promql_test_case> 要评估的 PromQL 表达式以及期望返回的样本
<sample>
单元测试的时间处理机制
  • time() 返回值为 start_timestamp + eval_time
    • 所有测试（包括 alert_test_case 和 promql_test_case）中，与当前时间相关的函数的默认起始时间（start_timestamp）为 Unix 时间 0
    • eval_time 是相对于 start_timestamp 的持续时间（如 5m）
  • 通过在测试组（test group）中设置 start_timestamp 来改变基准时间
    • Unix 时间戳：如 1609459200（对应 2021-01-01T00:00:00Z）
    • RFC3339 字符串：如 "2021-01-01T00:00:00Z"
单元测试文件样例
  • 两个文件在同一目录
test.yml
alerts.yml
  • ./promtool test rules test.yml
promtool push metrics <remote-write-url> [<metric-files>...] 推送数据
  • 将指标数据以 Prometheus Remote Write 协议推送到指定端点，主要用于远程写入（Remote Write）测试
  • 可用选项
    • --http.config.file HTTP 客户端配置文件
    • --label 为所有指标添加固定标签
    • --timeout 超时时间，默认为 30s
    • --header 添加自定义 HTTP 请求头
    • --protobuf_message 指定使用的 Protobuf 消息格式
      • 默认为 prometheus.WriteRequest，还支持 io.prometheus.write.v2.Request
promtool tsdb 操作 TSDB 数据库
promtool tsdb bench write [<file>] 模拟写入负载，测试 TSDB 写入性能
  • 需要提供样本数据文件
  • 可用选项
    • --metrics 模拟的指标数量（默认 10,000）
    • --scrapes 模拟抓取次数（默认 3,000）
    • --out 输出结果目录（默认 benchout）
promtool tsdb analyze [<db path>] [<block id>] 分析 TSDB 块（block）
  • 分析内容包括标签对基数（高基数风险），时间序列变更率（churn）和压缩效率
  • 可用选项
    • --extended 启用更深入分析
    • --match 一个或多个时间序列选择器
    • --limit 每类结果最多显示条目数（默认 20）
promtool tsdb list [<db path>] 列出所有 TSDB 块（block）及其元数据
  • 可用选项
    • -r, --human-readable 以易读格式（如 MB、时间）显示
promtool tsdb dump [<db path>] 将 TSDB 中的时间序列和样本数据导出为文本
  • 可用选项
    • --format 输出 dump 文件格式
      • 默认为 prom，可选时间序列 json
    • --match 一个或多个时间序列选择器
    • --min-time, --max-time 按时间范围筛选（UNIX 时间戳）
    • --sandbox-dir-root 根目录，用于创建沙盒目录（沙盒最后会被清理干净），以防 WAL 重放生成区块（默认为数据库路径）
promtool tsdb dump-openmetrics [<db path>] 以 OpenMetrics 文本格式导出样本
  • 不支持 native histograms 和过期标记
  • 可用选项
    • --match 一个或多个时间序列选择器
    • --min-time, --max-time 按时间范围筛选（UNIX 时间戳）
    • --sandbox-dir-root 根目录，用于创建沙盒目录（沙盒最后会被清理干净），以防 WAL 重放生成区块（默认为数据库路径）
promtool tsdb create-blocks-from openmetrics <input file> [<output directory>] 从 OpenMetrics 文件生成标准 TSDB 块
  • 可用选项
    • -r, --human-readable 以易读格式（如 MB、时间）显示
    • -q, --quiet 静默输出，不显示创建的块
    • --label 为所有指标添加固定标签
promtool tsdb create-blocks-from rules <rule-files>… 为新的 recording rules 创建块
  • 默认只对新的生效，补全历史聚合规则
  • 可用选项
    • --http.config.file HTTP 客户端配置文件
    • --url 服务器 URL
    • --start(必须), --end 需要回填（backfill）记录规则的时间范围（RFC3339 或 UNIX 时间戳）
    • --output-dir 生成 TSDB 块的存放目录，默认为 /data
    • --eval-interval 如果 recording rules 中没有设置值时应多久评估一次规则
promtool debug 获取服务器信息用于调试
  • promtool debug pprof <server> 获取 pprof 性能剖析数据
  • promtool debug metrics <server> 获取 Prometheus 服务器暴露的完整指标文本
  • promtool debug all <server> 同时获取 pprof 和 metrics 等所有可用的调试信息
 
 
上一篇
Pushgateway 推送无法通过抓取方式获取的作业指标
下一篇
指标（Metric）和 Promethues 概述
Comments
Loading...