17.3.7 常见问题排查与最佳实践

常见问题排查与最佳实践#

原理草图：服务发现到抓取的链路#

文章图片

环境与安装快速确认（Prometheus 自身）#

# 1) 确认 Prometheus 版本与运行状态
prometheus --version
systemctl status prometheus

# 2) 检查配置语法（需要安装 promtool）
promtool check config /etc/prometheus/prometheus.yml

# 3) 热加载配置（不重启）
curl -X POST http://127.0.0.1:9090/-/reload
  • promtool check config：验证 YAML 结构与 scrape 配置是否合法。
  • /-/reload：对 Prometheus 进程发送配置重载信号，保持采集不中断。

常见问题快速定位（带命令与示例）#

  • 目标缺失或状态为 Down
# 从 Prometheus 节点直接验证目标可达性
curl -sS http://10.0.0.12:9100/metrics | head -n 5

# 查看 Prometheus 目标页面（可在浏览器或 curl 获取）
curl -sS http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, instance: .labels.instance, health: .health, lastError: .lastError}'
  • 若 curl /metrics 失败：检查目标端口、服务状态、网络与防火墙。

  • 若 lastError 显示认证/协议错误：确认 scheme、metrics_path、basic_auth。

  • 发现数量异常（file_sd_config）

# 校验文件发现配置是否被 Prometheus 读取
ls -l /etc/prometheus/file_sd/
cat /etc/prometheus/file_sd/node_exporter.json

示例（可执行 JSON）：

[
  {
    "targets": ["10.0.0.12:9100", "10.0.0.13:9100"],
    "labels": { "job": "node", "env": "prod", "cluster": "c1" }
  }
]
  • 变更后需触发 reload：
curl -X POST http://127.0.0.1:9090/-/reload
  • 标签膨胀与高基数问题
# 使用 PromQL 在 Web UI 中检查高基数
# 在浏览器输入：http://127.0.0.1:9090/graph
# 查询：topk(10, count by(__name__)({job="api"}))

示例：过滤高基数标签

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: "api"
    static_configs:
      - targets: ["10.0.0.21:8080"]
    metric_relabel_configs:
      - source_labels: [request_id]
        action: drop

  • metric_relabel_configs 对指标级别生效，删除动态标签防止时序爆炸。

  • 抓取延迟与超时

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: "slow_exporter"
    scrape_interval: 30s
    scrape_timeout: 10s
  • scrape_timeout 必须小于 scrape_interval，避免重叠采集。
  • 排查 exporter 响应时间：
time curl -sS http://10.0.0.30:9100/metrics >/dev/null

典型配置与排错示例（完整可执行）#

场景：目标被 relabel 误过滤导致消失

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: "k8s-node"
    kubernetes_sd_configs:
      - role: node
    relabel_configs:
      - source_labels: [__meta_kubernetes_node_label_env]
        regex: prod
        action: keep

排错步骤：

# 1) 查看目标是否带 env 标签
curl -sS http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | {instance: .labels.instance, labels: .labels}'
# 2) 若 env 标签不存在，调整 relabel 或补齐标签

排查流程建议（命令化流程）#

  1. 确认目标可达
    bash curl -sS http://<target_ip>:<port>/metrics | head
  2. 检查发现来源与数量
    bash curl -sS http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets | length'
  3. 验证重写链路
    bash promtool check config /etc/prometheus/prometheus.yml
  4. 查看 Prometheus 自身指标
    bash curl -sS http://127.0.0.1:9090/metrics | egrep 'scrape_duration_seconds|scrape_samples_scraped|tsdb_head_series'

最佳实践（带示例与命令说明）#

  • 统一标签标准
  • 必备：job、instance、env、cluster、region
  • 禁止：request_id、trace_id、pod_uid 等高基数标签
  • 合理使用 relabel
relabel_configs:
  - source_labels: [__meta_kubernetes_namespace]
    regex: kube-system|monitoring
    action: keep
  - source_labels: [__address__]
    target_label: instance
  • 分层发现策略
  • 核心基础设施：静态/文件发现
  • 动态平台：K8s SD/注册中心
  • 告警联动（目标稳定性）
# /etc/prometheus/rules/targets.rules.yml
groups:
  - name: target-stability
    rules:
      - alert: TargetDown
        expr: up == 0
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Target down: {{ $labels.instance }}"

练习与验证#

  1. 练习 1：模拟目标消失
    - 临时停止 node_exporter：
    bash systemctl stop node_exporter
    - 观察 targets 页面与告警触发。
  2. 练习 2：制造高基数标签
    - 在业务 exporter 暂时添加 request_id 标签。
    - 观察 tsdb_head_series 增长，并用 metric_relabel_configs 修复。
  3. 练习 3：relabel 过滤排错
    - 增加 action: keep 规则并故意写错标签名。
    - 使用 api/v1/targets 排查为何目标被过滤。