4. 常见采集链路故障分类
在 Exporter 指标采集链路中，故障可能发生在从目标服务暴露指标到 Prometheus 成功抓取并存储的任意环节。根据生产环境故障根因统计，可将常见故障归纳为以下五类：Exporter 进程崩溃、端口不可达、指标格式错误、抓取超时、数据丢失。每类故障的触发条件、影响范围及排查手段均有显著差异。
4.1 Exporter 进程崩溃
Exporter 进程因内部错误、资源耗尽或外部依赖中断而异常退出，导致 Prometheus 无法建立 TCP 连接或 HTTP 响应。此类故障通常表现为 up{job="xxx"} == 0 且 scrape_duration_seconds 为 0。
| 故障子类型 | 典型根因 | 排查命令 / 手段 |
|---|---|---|
| OOM Kill | 内存泄漏、指标基数过大 | dmesg | grep -i oom、journalctl -u exporter.service |
| Panic / 未捕获异常 | 依赖库版本冲突、nil 指针 | Exporter 自身日志 --log.level=debug |
| 健康检查失败 | 后端服务不可用导致 Exporter 主动退出 | 检查 Exporter 配置中的 --web.healthz-url |
排查建议： 为 Exporter 配置 systemd 自动重启策略（
Restart=always），并设置 RestartSec=5 避免频繁重启。同时监控 process_exporter_process_start_time_seconds 的突变。
4.2 端口不可达
Exporter 进程正常运行，但 Prometheus 无法通过指定 IP:Port 建立连接。常见原因包括：防火墙规则变更、容器端口映射错误、Kubernetes Service 端点未就绪、网络策略阻断。
- 防火墙 / 安全组： 检查 iptables、云厂商安全组入站规则是否放通 Prometheus 源 IP。
- 容器 / K8s 环境： 使用
kubectl get endpoints <service>确认后端 Pod 地址是否正确；检查 NetworkPolicy 是否允许 Prometheus 命名空间访问。 - 端口监听验证： 在目标节点执行
ss -tlnp | grep <port>确认 Exporter 是否监听在正确接口。
常见误区： 部分 Exporter 默认监听
127.0.0.1 而非 0.0.0.0，导致跨节点抓取时端口不可达。启动参数中应显式指定 --web.listen-address=0.0.0.0:<port>。
4.3 指标格式错误
Exporter 返回的 HTTP 响应体不符合 Prometheus 文本格式规范，导致 Prometheus 解析失败并记录 parsing error。格式错误通常不会导致 up 变为 0，但会丢失该次抓取的全部指标。
| 错误类型 | 示例 | 修复方向 |
|---|---|---|
| 标签值未加引号 | metric{label=value} 1 |
标签值必须使用双引号：metric{label="value"} 1 |
| 指标名包含非法字符 | my-metric{label="v"} 1 |
指标名只允许 [a-zA-Z_:][a-zA-Z0-9_:]*，将 - 替换为 _ |
| 时间戳格式错误 | metric 1 1234567890.123 |
时间戳应为整数毫秒，不支持浮点数 |
| 重复的 HELP/TYPE 行 | 多次声明 # HELP metric ... |
每个指标名只允许一个 HELP 和一个 TYPE 行 |
快速验证： 使用
curl -s http://<exporter>:<port>/metrics | promtool check metrics 可离线检测格式合规性。
4.4 抓取超时
Prometheus 在 scrape_timeout 配置时间内未收到完整 HTTP 响应，导致该次抓取被中断。超时可能由 Exporter 响应缓慢、网络延迟高、指标数据量过大引起。
- 指标基数爆炸： 高基数标签（如
user_id、request_id）导致 Exporter 序列化耗时过长。 - 后端依赖阻塞： Exporter 在采集数据时调用了外部 API 或数据库，响应超时。
- 网络带宽瓶颈： 大量指标（>10万条）在低带宽链路传输时容易超时。
优化策略： 适当增大
scrape_timeout（默认 10s，建议不超过 30s）；对高基数场景启用 honor_labels: false 并配合 metric_relabel_configs 丢弃不必要的标签。
4.5 数据丢失
数据丢失指 Prometheus 成功抓取并解析了指标，但在存储、压缩或查询过程中部分数据永久消失。这是误差预算台账偏差的主要来源，且难以通过 up 指标直接发现。
| 丢失阶段 | 典型原因 | 检测方法 |
|---|---|---|
| 抓取阶段 | WAL 写入失败、样本时间戳乱序被丢弃 | 查看 prometheus_tsdb_wal_writes_failed_total |
| 压缩阶段 | TSDB 压缩时 block 损坏、内存不足 | 检查 prometheus_tsdb_compactions_failed_total |
| 查询阶段 | 数据过期删除（retention）、远程存储写入失败 | 对比 prometheus_tsdb_head_samples_appended_total 与查询结果 |
误差预算影响： 数据丢失会导致 SLI 计算出现“假阴性”或“假阳性”。例如，某次 5xx 错误指标因丢失而未计入，误差预算会错误地显示为健康状态。建议在 Prometheus 端启用
--storage.tsdb.retention.size 和 --storage.tsdb.retention.time 双重限制，并定期执行 promtool tsdb analyze 检查数据完整性。