17.3.2 静态目标配置与文件发现

静态目标配置适用于目标数量稳定、拓扑变化少的场景，通过在 Prometheus 配置文件中声明抓取目标实现；文件发现适用于目标变化频繁但缺乏服务注册中心的场景，通过外部文件动态加载目标清单。两者常与统一标签策略、变更管理与告警联动配合使用，保障采集可控与告警可复用。

原理草图（静态配置与文件发现的数据流）：

安装与准备（示例基于二进制包安装，已安装可跳过）：

# 1) 下载并解压
wget https://github.com/prometheus/prometheus/releases/download/v2.49.1/prometheus-2.49.1.linux-amd64.tar.gz
tar -xzf prometheus-2.49.1.linux-amd64.tar.gz
sudo mv prometheus-2.49.1.linux-amd64 /opt/prometheus

# 2) 创建配置与数据目录
sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo cp /opt/prometheus/prometheus.yml /etc/prometheus/prometheus.yml

命令说明：下载对应版本、解压到 /opt/prometheus，配置文件放在 /etc/prometheus，数据目录在 /var/lib/prometheus。

静态目标配置示例（完整可执行，含关键参数）：

# /etc/prometheus/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 30s

scrape_configs:
  - job_name: "node-static-prod"
    metrics_path: /metrics
    scheme: http
    scrape_interval: 10s
    static_configs:
      - targets:
          - "10.0.0.11:9100"
          - "10.0.0.12:9100"
        labels:
          env: "prod"
          app: "node"
          role: "worker"

关键参数解释：
- job_name：作业名，告警与查询的聚合维度
- targets：主机:端口
- labels：统一标签，便于 PromQL 聚合
- scrape_interval：覆盖全局采集频率

文件发现配置示例（Prometheus 主配置 + 目标文件）：

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: "node-file-sd-staging"
    file_sd_configs:
      - files:
          - /etc/prometheus/targets/node-staging.yml
        refresh_interval: 30s
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
      - target_label: env
        replacement: "staging"

# /etc/prometheus/targets/node-staging.yml
- targets:
  - "10.0.1.21:9100"
  - "10.0.1.22:9100"
  labels:
    app: "node"
    role: "worker"

命令说明：refresh_interval 指定扫描文件的周期；relabel_configs 统一设置标签与 instance。

启动与验证（含预期效果）：

# 启动 Prometheus
/opt/prometheus/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus

# 验证配置是否生效（Prometheus 2.48+）
/opt/prometheus/promtool check config /etc/prometheus/prometheus.yml

# 使用 API 检查目标状态
curl -s http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, instance: .labels.instance, health: .health}'

预期效果：health 为 up，并看到 job 与 instance 标签。

文件发现的自动更新（脚本示例，配合 CMDB/清单）：

#!/usr/bin/env bash
# /usr/local/bin/gen_targets.sh
cat > /etc/prometheus/targets/node-staging.yml <<'EOF'
- targets:
  - "10.0.1.21:9100"
  - "10.0.1.23:9100"
  labels:
    app: "node"
    role: "worker"
EOF

命令说明：更新目标文件后无需重启 Prometheus，等待 refresh_interval 自动加载。

常见排错与定位（含明确命令）：

# 1) 检查目标是否在线
curl -s http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | select(.health!="up")'

# 2) 检查目标端口连通
nc -vz 10.0.0.11 9100

# 3) 检查 exporter 是否返回指标
curl -s http://10.0.0.11:9100/metrics | head

# 4) 检查文件发现格式（YAML/JSON）
python3 - <<'PY'
import yaml,sys
print(yaml.safe_load(open('/etc/prometheus/targets/node-staging.yml')))
PY

# 5) Prometheus 日志中查找加载错误
grep -i "file_sd" -n /var/log/prometheus.log

排错要点：目标 up=0 多为端口不通/路径错；文件发现失败多为 YAML 格式错误或路径不存在。

告警与验证示例（监控失联目标）：

# /etc/prometheus/rules/targets.rules.yml
groups:
- name: target-health
  rules:
  - alert: TargetDown
    expr: up == 0
    for: 2m
    labels:
      severity: critical
    annotations:
      summary: "Target down: {{ $labels.instance }}"
      description: "Job={{ $labels.job }}, env={{ $labels.env }}"

# /etc/prometheus/prometheus.yml 中加载规则
rule_files:
  - /etc/prometheus/rules/*.yml

标签策略与变更管理建议（落地示例）：

# 统一标签规范示例
labels:
  env: "prod"
  region: "cn-bj"
  app: "payment"
  role: "api"

避免将高基数标签（如 request_id）写入 labels，仅保留稳定维度。

练习（动手完成并验证）：
1. 在静态配置中新增一个 job_name: "node-static-test"，目标为本机 127.0.0.1:9100，验证 up=1。
2. 使用文件发现新增一台测试主机，观察 30 秒内自动加载，无需重启 Prometheus。
3. 故意写错文件发现的 YAML（如缩进错误），使用 promtool check config 与日志定位问题。
4. 编写 PromQL 查询：up{job="node-file-sd-staging"}，确认标签 env 被正确注入。