Prometheus 入门实战：从零搭建、配置采集、PromQL 查询到记录规则

本文基于官方 入门指南 编写，完整走通 Prometheus 的安装运行、自我监控配置、Node Exporter 示例目标采集、表达式浏览器查询、图形界面绘图、记录规则与配置热加载的全流程。读完后，你将能够独立搭建一个可自监控、可抓取多目标、可通过规则预计算时序的 Prometheus 实例，并理解 cmd/prometheus/main.go 中信号处理、自动重载等底层机制如何支撑文档中的每一项操作。

下载并运行 Prometheus

入门教程以 "Hello World" 风格展开：下载并解压你平台对应的 Prometheus 发行包，然后进入目录准备启动：

tar xvfz prometheus-*.tar.gz
cd prometheus-*

在启动之前，先完成配置文件编写，这是官方推荐的顺序：先配置、再启动。

配置 Prometheus 监控自身

Prometheus 通过抓取（scrape）目标暴露的 metrics HTTP 端点来收集指标。由于 Prometheus 自身也以外暴露的方式暴露自己的运行数据，它完全可以抓取并监控自身。仅收集自身数据虽然用处有限，但作为起点示例非常合适。

将下面这份最小配置保存为 prometheus.yml：

global:
  scrape_interval:     15s # 默认每 15 秒抓取一次目标。

  # 与外部系统（联邦、远程存储、Alertmanager）通信时，
  # 将这些标签附加到任何时间序列或告警上。
  external_labels:
    monitor: 'codelab-monitor'

# 一个只包含一个端点的抓取配置：
# 这里是 Prometheus 自身。
scrape_configs:
  # job 名称会作为标签 `job=<job_name>` 添加到该配置抓取的每个时间序列上。
  - job_name: 'prometheus'

    # 覆盖全局默认值，每 5 秒抓取一次本 job 的目标。
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:9090']

各关键项的含义：

• global.scrape_interval：全局默认抓取间隔，示例中为 15s；
• global.external_labels：外部标签，只在向外部系统（联邦、远程存储、Alertmanager）通信时附加，不会出现在本实例查询结果中；
• scrape_configs[].job_name：job 名称会自动作为 job 标签附加到该 job 抓取的每个时间序列上；
• scrape_configs[].scrape_interval：job 级覆盖，本例将自身抓取加密到 5s；
• static_configs：静态目标发现配置，targets 为 host:port 列表。

完整的配置选项规范见 配置文档。

启动 Prometheus

进入包含 Prometheus 二进制的目录，用刚创建的配置文件启动：

# 启动 Prometheus。
# 默认情况下，Prometheus 将数据库存储在 ./data（即 --storage.tsdb.path 参数）。
./prometheus --config.file=prometheus.yml

从源码看，这些默认值在 cmd/prometheus/main.go 中定义：

• --config.file 默认值为 prometheus.yml；
• --storage.tsdb.path（"Base path for metrics storage."）默认值为 data/；
• --web.listen-address 默认值为 0.0.0.0:9090，即 UI、API 与遥测端点的监听地址，可重复指定多个监听地址。

启动成功后，浏览器访问 http://localhost:9090 可以看到 Prometheus 的自身状态页。稍等几秒让它完成对自身 metrics 端点的采集，再访问 http://localhost:9090/metrics 即可验证 Prometheus 正在对外提供关于自身的指标。

使用表达式浏览器

Prometheus 内置表达式浏览器，用于探索它收集到的数据。访问 http://localhost:9090/query 并选择 "Graph" 标签页。

从 /metrics 端点可以了解到，Prometheus 关于自身导出的一个指标名为 prometheus_target_interval_length_seconds（实际两次抓取目标之间的间隔时长）。在表达式控制台中输入并点击 "Execute"：

prometheus_target_interval_length_seconds

这会返回多条时间序列（各附最新记录值），它们指标名相同但标签不同——这些标签标识了不同的延迟分位数和目标组抓取间隔。该指标在源码中定义于 scrape/metrics.go：它是一个按 interval 标签分组的 Summary，Objectives 设置为 {0.01, 0.05, 0.5, 0.90, 0.99}，与查询结果中出现的 quantile 标签一一对应。

如果只关心 99 分位延迟，可以这样查询：

prometheus_target_interval_length_seconds{quantile="0.99"}

统计返回的时间序列条数，可以写：

count(prometheus_target_interval_length_seconds)

更多表达式语言内容见 查询语言文档。

使用图形界面

要绘制表达式图形，同样访问 http://localhost:9090/query 并使用 "Graph" 标签页。

例如，输入下面表达式，绘制被自抓取的 Prometheus 每秒创建 chunk 的速率：

rate(prometheus_tsdb_head_chunks_created_total[1m])

可以自行调整图形范围参数和其他设置进行实验。

启动若干示例目标

接下来为 Prometheus 添加更多抓取目标。官方示例使用 Node Exporter，下载解压后启动 3 个示例目标：

tar -xzvf node_exporter-*.*.tar.gz
cd node_exporter-*.*

# 在 3 个独立终端中分别启动 3 个示例目标：
./node_exporter --web.listen-address 127.0.0.1:8080
./node_exporter --web.listen-address 127.0.0.1:8081
./node_exporter --web.listen-address 127.0.0.1:8082

此时应能看到 3 个示例目标分别监听在 http://localhost:8080/metrics、http://localhost:8081/metrics 和 http://localhost:8082/metrics。

配置 Prometheus 监控示例目标

现在把 3 个端点归入一个名为 node 的 job。假设前两个端点是生产目标，第三个是金丝雀（canary）实例。要在 Prometheus 中建模这种关系，可以为单个 job 添加多组端点分组，并对每组目标附加额外标签：第一组打 group="production" 标签，第二组打 group="canary" 标签。

将下面的 job 定义追加到 prometheus.yml 的 scrape_configs 部分，然后重启 Prometheus：

scrape_configs:
  - job_name:       'node'

    # 覆盖全局默认值，每 5 秒抓取一次本 job 的目标。
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'

      - targets: ['localhost:8082']
        labels:
          group: 'canary'

验证步骤：

1. 打开表达式浏览器，确认 Prometheus 已掌握这些端点暴露的时间序列，例如 node_cpu_seconds_total；
2. 访问 http://localhost:9090/targets，或打开 Status 菜单选择 Target health。在 node job 下应看到 3 个端点，状态均为 UP。按上述配置，localhost:8080 和 localhost:8081 带 group="production" 标签，localhost:8082 带 group="canary" 标签。若某端点显示 DOWN，请确认对应端口的 Node Exporter 仍在运行；
3. 先直接打开某个目标的 /metrics 端点（例如 http://localhost:8080/metrics）查看其暴露的原始指标名，再把其中一个（如 node_cpu_seconds_total）输入表达式浏览器并点击 "Execute"。应返回每个实例按 CPU 和模式划分的时间序列，例如：

node_cpu_seconds_total{cpu="0",group="production",instance="localhost:8080",job="node",mode="idle"}

要浏览当前所有可用指标名，打开查询选项菜单（表达式输入框右侧的三点按钮），选择 Explore metrics。

配置记录规则：把抓取数据聚合为新时间序列

虽然示例中不构成问题，但对数千条时间序列做聚合的查询，临时（ad-hoc）计算可能变慢。为了更高效，Prometheus 可以通过 recording rules（记录规则）将表达式预计算并持久化为新的时间序列。假设我们要记录：CPU 时间每秒速率（node_cpu_seconds_total）在 5 分钟窗口内、按实例对所有 CPU 求平均的结果（保留 job、instance、mode 三个维度）。表达式为：

avg by (job, instance, mode) (rate(node_cpu_seconds_total[5m]))

可以先试着用图形界面画一下这个表达式。

要将其结果记录为名为 job_instance_mode:node_cpu_seconds:avg_rate5m 的新指标，创建如下记录规则文件并保存为 prometheus.rules.yml：

groups:
- name: cpu-node
  rules:
  - record: job_instance_mode:node_cpu_seconds:avg_rate5m
    expr: avg by (job, instance, mode) (rate(node_cpu_seconds_total[5m]))

要让 Prometheus 加载新规则，需在 prometheus.yml 中添加 rule_files 配置。此时完整配置应如下所示（注意新增的 evaluation_interval: 15s，表示每 15 秒评估一次规则）：

global:
  scrape_interval:     15s # 默认每 15 秒抓取一次目标。
  evaluation_interval: 15s # 每 15 秒评估一次规则。

  # 将这些额外标签附加到该 Prometheus 实例收集的所有时间序列上。
  external_labels:
    monitor: 'codelab-monitor'

rule_files:
  - 'prometheus.rules.yml'

scrape_configs:
  - job_name: 'prometheus'

    # 覆盖全局默认值，每 5 秒抓取一次本 job 的目标。
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:9090']

  - job_name:       'node'

    # 覆盖全局默认值，每 5 秒抓取一次本 job 的目标。
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'

      - targets: ['localhost:8082']
        labels:
          group: 'canary'

用新配置重启 Prometheus 后，通过表达式浏览器查询或图形界面绘图，验证名为 job_instance_mode:node_cpu_seconds:avg_rate5m 的新时间序列已经可用。

重载配置（热加载）

如 配置文档 所述，Prometheus 实例无需重启进程即可重载配置：向其发送 SIGHUP 信号。在 Linux 上可用 kill -s SIGHUP <PID> 完成，<PID> 替换为 Prometheus 进程 ID。

从源码结构看，该机制在 cmd/prometheus/main.go 的 Reload handler 中实现：通过 signal.Notify(hup, syscall.SIGHUP) 注册信号监听，收到信号后调用 reloadConfig 重新加载配置文件，并将新配置分发到各个 reloader（抓取管理器、规则管理器等）。此外，当前版本还支持通过 Web 端点触发重载（webHandler.Reload() 分支，需配合 --web.enable-lifecycle 启用），以及基于文件校验和的自动重载——在 命令行参数定义 中可以看到：

• --config.auto-reload（默认 false）：启用配置文件自动重载；
• --config.auto-reload-interval（默认 30s）：检测配置文件变更的间隔，仅在开启 --config.auto-reload 时生效。

开启自动重载后，进程会周期性比较配置文件校验和，发现变更即触发 reloadConfig，无需手动发信号。

优雅关闭实例

虽然 Prometheus 在进程意外崩溃时具备恢复机制，但仍建议通过信号或中断实现干净关闭。在 Linux 上，向 Prometheus 进程发送 SIGTERM 或 SIGINT 信号即可，例如使用 kill -s <SIGNAL> <PID>，将 <SIGNAL> 替换为信号名、<PID> 替换为进程 ID。也可以在控制终端按下中断字符，默认为 ^C（Control-C）。

源码层面，终止处理器在 cmd/prometheus/main.go 中通过 signal.Notify(term, os.Interrupt, syscall.SIGTERM) 同时监听这两个信号（os.Interrupt 即 SIGINT）。收到信号后，Prometheus 会按 run.Group 的既定顺序协调停止各子组件：先停抓取发现管理器与抓取管理器（注释中特别说明必须在关闭本地 TSDB 之前停止，以免向已关闭的存储写入样本），再停规则管理器，确保干净退出、数据落盘完整。

小结

本教程走完了 Prometheus 的典型使用闭环：

1. 下载并解压发行包；
2. 用 prometheus.yml 配置自我监控（global + scrape_configs + static_configs）；
3. 通过 --config.file 启动，数据库默认落盘到 --storage.tsdb.path（./data）；
4. 在表达式浏览器与 Graph 标签页中练习 PromQL（rate、count、标签选择器等）；
5. 引入 Node Exporter 示例目标，用多组静态配置与分组标签（production/canary）建模目标拓扑；
6. 用 rule_files + 记录规则预计算聚合序列，配合 evaluation_interval 控制评估节奏；
7. 用 SIGHUP、Web 端点或 --config.auto-reload 三种方式热加载配置，用 SIGTERM/SIGINT 优雅关闭。

配置细节可进一步参阅 配置文档 与 查询语言文档，命令行参数全览见 命令参考。