可观测性与稳定性 / 系统课时

启动第一个 Prometheus 实例

启动第一个 Prometheus 实例

本课从一个空运行目录开始,用最小配置启动 Prometheus,让它先抓取自己的 /metrics。完成后你将得到一个可访问的 Prometheus 实例,并能通过就绪端点、Targets 与 up 查询确认配置、服务和首次采集都已真正生效。

学习目标

  • 能写出只包含一个自抓取任务的最小 prometheus.yml
  • 能在启动前使用 promtool 校验配置,并指定配置与数据目录启动 Prometheus
  • 能通过就绪检查和 up 查询确认实例已经开始采集数据

准备运行目录

以下操作假设已经从 Prometheus 官方发布包解压得到 prometheus 与 promtool,并进入这两个可执行文件所在目录。先确认二进制可以正常运行,避免把后续问题误判成配置错误。

bash
./prometheus --version
./promtool --version

预期输出

text
prometheus, version <VERSION> ...
promtool, version <VERSION> ...

<VERSION> 取决于实际安装版本。Prometheus 官方文档也使用解压后的单文件二进制直接启动,并通过 --config.file 指定配置文件。([普罗米修斯][3])

写入最小抓取配置

创建 prometheus.yml。这里把全局抓取周期设为 15 秒,并定义一个名为 prometheus 的任务,让实例抓取自己默认暴露在 localhost:9090/metrics 的指标。Prometheus 的抓取任务由 scrape_configs 定义,静态目标可以放在 static_configs 中。([普罗米修斯][4])

yaml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets:
          - localhost:9090

配置文件本身没有“运行输出”,因此启动前用同一发行包中的 promtool 做语法和配置校验:

bash
./promtool check config prometheus.yml

预期输出

text
Checking prometheus.yml
 SUCCESS: prometheus.yml is valid prometheus config file syntax

校验通过只说明 Prometheus 能接受这份配置,不代表目标一定可达。网络、端口、TLS 或认证问题仍要在实例启动并实际抓取后验证。

启动 Prometheus 并等待就绪

把 TSDB 数据放到当前目录下的 data,日志写入 prometheus.log,并把进程号保存下来。随后最多等待约 30 秒,直到就绪端点返回成功。

bash
mkdir -p data

./prometheus \
  --config.file=prometheus.yml \
  --storage.tsdb.path=./data \
  >prometheus.log 2>&1 &

echo $! > prometheus.pid

ready=0
for i in $(seq 1 30); do
  if curl -fsS http://localhost:9090/-/ready; then
    ready=1
    break
  fi
  sleep 1
done

test "$ready" -eq 1

预期输出

text
Prometheus Server is Ready.

Prometheus 默认 Web 监听地址使用 9090 端口;启动成功后,可以直接访问 http://localhost:9090/。官方入门文档也使用同一端口访问 Web 界面和自身指标端点。([普罗米修斯][3])

确认自抓取已经发生

实例就绪后还要证明采集链路已经工作。在 Prometheus 查询页面执行下面的 PromQL,检查刚才配置的自抓取任务。

promql
up{job="prometheus"}

预期结果

text
up{instance="localhost:9090", job="prometheus"} 的当前值为 1。

1 表示最近一次抓取成功。如果短时间内还没有样本,可以等待一个抓取周期后再查询;如果持续为 0,应查看 Targets 页面和 prometheus.log 中的抓取错误,而不是反复重启服务。

处理常见启动失败

如果实例没有进入 Ready 状态,按最短证据链排查:

  • 配置无法加载:重新运行 ./promtool check config prometheus.yml,先修复 YAML 缩进、字段名或目标格式。
  • 端口被占用:日志通常会出现监听失败。若改用 --web.listen-address=:<PORT>,自抓取目标也必须同步改为 localhost:<PORT>。
  • 数据目录不可写:确认当前用户对 --storage.tsdb.path 指向目录具有写权限。
  • Web 能打开但 up 为 0:Prometheus 进程已启动,但抓取目标失败,应检查 Targets 中的错误信息,而不是把它当成启动失败。

到这里,一个最小 Prometheus 实例已经同时满足三项条件:配置能被解析、服务进入就绪状态、自抓取结果为 1。这三个条件比“浏览器能看到页面”更适合作为首次启动的验收标准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

启动第一个 Prometheus 实例

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通