真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

monitoring Troubleshooting

Prometheus Target Down 排查流程

Prometheus Targets 页面显示 down、context deadline exceeded 或 connection refused 时，先看 Last Error，从 Prometheus 所在网络位置 curl 目标 /metrics，Kubernetes 场景检查 ServiceMonitor 的 selector 与 namespaceSelector 是否匹配 Service labels 和端口名。

先在 Prometheus Targets 页面看 Last Error，再从 Prometheus 所在网络位置 curl 目标 /metrics。多数问题是地址、端口、路径或网络策略不通。

适用环境Prometheus / Exporter / 监控链路
风险等级低
最后验证2026-06-30
建议权限普通用户

2026-06-30 更新·约 4 分钟阅读

Scenario

这篇文章解决什么问题

适用于 Prometheus Targets 页面显示 down 或 unknown，但业务服务本身看起来正常的场景。重点验证 Prometheus 所在网络位置是否能访问 metrics。

Symptoms

典型现象

  • Targets 页 Last Error 出现 context deadline exceeded、connection refused、server returned HTTP status。
  • 本机 curl 通，但 Prometheus 仍抓取失败。
  • ServiceMonitor 创建后没有生成目标或标签不对。

Before Debugging

排查前先确认

  • 先确认是监控系统自身不可用，还是 target/exporter 不可抓取。
  • 从 Prometheus 所在网络位置测试 metrics，而不是只在本机 curl。
  • 记录 Targets 页面的 Last Error、endpoint、labels 和 scrape pool。

Root Causes

常见根因分层

服务发现没有生成目标

ServiceMonitor、PodMonitor、relabel、namespaceSelector 和标签不匹配，会导致压根没有 target。

  • 检查 selector 和 labels
  • 确认端口名匹配
  • 查看 Prometheus 配置生成结果

目标存在但抓取失败

网络策略、DNS、端口、metrics path、scheme、TLS 或认证失败都会让 target down。

  • 从 Prometheus Pod curl /metrics
  • 看 Last Error
  • 检查 TLS 和 token

指标可抓但质量不可用

高基数 label、抓取超时、metrics 体积过大，会让监控变慢或数据缺失。

  • 看 scrape duration
  • 控制 label cardinality
  • 拆分 heavy exporter

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。Prometheus Target Down 排查流程 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
curl -v http://target:9100/metrics
promtool check config prometheus.yml

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
promtool check config prometheus.yml
kubectl port-forward svc/prometheus 9090:9090 -n monitoring
kubectl get servicemonitor,podmonitor -A

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 在 Targets 页面记录 endpoint、state 和 Last Error。
  • 从 Prometheus 容器或同网络环境 curl 目标 metrics 地址。
  • 确认 metrics path、scheme、端口名和 scrape interval 配置。
3. 读取服务端证据，而不是只看客户端提示
kubectl port-forward svc/prometheus 9090:9090 -n monitoring
kubectl get servicemonitor,podmonitor -A
kubectl describe servicemonitor <name> -n <namespace>

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 确认 metrics path、scheme、端口名和 scrape interval 配置。
  • Kubernetes 场景检查 ServiceMonitor selector 是否匹配 Service labels。
  • 如果需要认证或 TLS，检查 bearer token、证书和 insecure_skip_verify 等配置。
4. 做最小修复并立即回归验证
kubectl get servicemonitor,podmonitor -A
kubectl describe servicemonitor <name> -n <namespace>

Commands

排查命令与使用意图

命令 1

用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。

命令 1
curl -v http://target:9100/metrics

命令 2

用于补充“Prometheus Target Down 排查流程”的排查证据链。promtool 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 2
promtool check config prometheus.yml

命令 3

用于补充“Prometheus Target Down 排查流程”的排查证据链。kubectl 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
kubectl port-forward svc/prometheus 9090:9090 -n monitoring

命令 4

用于读取 Kubernetes 当前资源状态和 Events。重点看 STATUS、RESTARTS 和 Events 中的调度、探针、镜像错误。

命令 4
kubectl get servicemonitor,podmonitor -A

命令 5

用于读取 Kubernetes Events、状态变化和资源引用关系。排查 Pod、Service、Ingress 时，它通常能直接暴露调度、拉镜像、探针或后端错误。

命令 5
kubectl describe servicemonitor <name> -n <namespace>

Risk Notes

容易踩坑的地方

  • 不要只改 Prometheus 配置而不验证生成后的 target，这可能导致监控盲区。
  • 不要在业务高峰临时打开大量高基数指标，这可能导致 Prometheus OOM 或抓取超时。
  • 不要依赖单一 Prometheus 实例做高可用，应考虑 Thanos 或 VictoriaMetrics 等方案。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 Prometheus Target Down 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • 为 Prometheus 自身、target down 和 scrape error 建立告警，确保监控系统自身健康。
  • ServiceMonitor 标签和端口名形成固定约定，减少服务发现配置错误。
  • 上线 exporter 前检查 metrics 体积和高基数标签，避免抓取性能问题。
  • 定期审查 Prometheus 配置和告警规则，确保覆盖新增服务的监控需求。

常见问题

本机 curl 通，Prometheus 仍 down 怎么办？

要从 Prometheus 所在 Pod/主机网络位置测试。本机能通不代表 Prometheus 能访问。

ServiceMonitor 创建了为什么没有 target？

常见原因是 selector 标签不匹配、namespaceSelector 不包含目标 namespace，或 Service 端口名与配置不一致。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • Prometheus target down
  • prometheus scrape failed
  • context deadline exceeded prometheus
  • prometheus connection refused target
  • prometheus relabel target missing
  • node exporter down
  • Prometheus targets unhealthy
  • server returned HTTP status 404 prometheus

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

命令

Prometheus 配置检查和 Target 排查命令

Prometheus 配置校验和 target 排查的常用命令，promtool check config 排除 prometheus.yml 语法错误，从 Prometheus 所在网络位置 curl target /metrics 复现抓取，Kubernetes 场景 kubectl describe servicemonitor 检查 selector 和端口名匹配。

monitoring命令

Base64 编码原理与使用场景

用 base64、base64 -d 和 Buffer.from().toString('base64') 编解码字符串，理解 Base64 用 64 个可打印字符表示二进制、编码后体积膨胀约 4/3，以及 URL Safe 变体把 + / 替换为 - _ 的用法，Base64 是编码不是加密。

frontend工具

Base64 编码解码工具

支持 UTF-8 编码的 Base64 在线编码与解码工具，能正确处理中文、Emoji 与特殊字符，浏览器本地完成不上传数据，适合接口调试、JWT 拆解、图片 Data URL 和邮件附件转换等场景。

frontend命令

chmod 文件权限命令

使用 chmod 修改 Linux 文件权限的常用命令，数字模式 755 等于 rwxr-xr-x，字母模式 u+x/g-w 按用户/组/其他加减权限，chmod -R 递归修改目录，chmod --reference 复制参考文件权限，目录必须有 x 权限才能进入。

linux速查

CI/CD 常用命令速查表

GitHub Actions、GitLab CI 和 Jenkins 三大 CI/CD 流水线一页速查：gh run/rerun/cancel 调试、gitlab-runner list/verify 与 CI Lint、jenkins-cli 构建日志、Runner 在线状态与缓存磁盘排查，覆盖 job 卡顿和构建失败主路径。

cicd命令

CI/CD 常用排障命令

CI/CD 排障常用命令合集，Jenkins 用 jenkins-cli 与 queue/computer API 查队列和 executor，GitLab 用 gitlab-runner verify/list 检查 Runner，GitHub Actions 用 gh run list、gh run view --log-failed、gh cache 定位失败步骤和缓存。

cicd