Prometheus抓取失败target一直显示DOWN的排查方法(context deadline exceeded、connection refused定位与scrape_timeout配置)

监控自己先瞎了,是件比业务挂掉更麻烦的事。Grafana上某个面板全是空白,点进去看指标全没了,再打开Prometheus的Targets页面,那一行State是DOWN,LastError里写着 Get "http://10.0.1.42:9100/metrics": context deadline exceeded (Client.Timeout exceeded while awaiting headers)。业务端口明明是通的,浏览器访问正常,可Prometheus就是抓不到。

这种时候先明确一件事:target DOWN说的是抓取链路断了,不是业务挂了。顺着链路一段一段查,比上来就重启Prometheus有用得多。


先读LastError,那一句基本已经把方向定了

Targets页面上每个target后面都挂着最近一次失败的原因,这四类出现的频率最高,而排查路径完全不一样。

connection refused说明网络能到,但那个端口上没有进程在监听。最典型的成因是exporter只绑了回环地址:本机 curl 127.0.0.1:9100/metrics 一切正常,从别的机器一律拒绝。

no such host是域名解析失败。Prometheus跑在容器或者Pod里时特别常见,它所在的网络视角里根本解析不出这个名字,而运维在跳板机上nslookup是通的。

context deadline exceeded表示TCP连上了、请求也发出去了,只是在超时窗口内没等完整响应。要么目标响应慢(比如 /metrics里聚合了慢查询),要么超时配置不合理。

server returned HTTP status 404 Not Found说明服务活着,只是指标路径写错了。Spring Boot默认暴露在 /actuator/prometheus,不少应用的路径各不相同,照抄默认的 /metrics抓必然是404。

还有两种容易看漏的:unsupported Content-Type说明抓到的是HTML页面,大概率是地址填成了业务首页或者nginx的默认页;x509: certificate has expired or is not yet valid则指向证书,HTTPS抓取时尤其容易踩。

这个坑踩过不止一次:光看DOWN就认定是防火墙,查了半天安全组,最后发现是target端口填错了。


站在Prometheus的位置上验,不要站在跳板机上验

这一点经常被跳过。跳板机curl得通,不代表Prometheus那个容器里curl得通,DNS、网络命名空间、iptables规则都可能不一样。二进制部署就登到Prometheus那台机器上跑,容器部署就docker exec进去跑,Kubernetes里就kubectl exec进Pod。

curl -sS -m 5 http://10.0.1.42:9100/metrics | head -20
ss -lntp | grep 9100
kubectl exec -n monitoring prometheus-0 -- wget -qO- http://10.0.1.42:9100/metrics | head -20

ss那行要看的是Local Address那一列。写成127.0.0.1:9100的,本机访问没问题,外部一律connection refused;必须是0.0.0.0:9100或者 :::9100才对外可见。node_exporter用 --web.listen-address=:9100控制,改成0.0.0.0:9100再重启即可。

顺手测一下响应时间,超过scrape_timeout的目标要单独处理:

time curl -sS -o /dev/null -w '%{time_total}\n' http://10.0.1.42:9100/metrics


promtool先把配置文件过一遍

相当一部分所谓的"网络问题"其实是YAML写错了。promtool是Prometheus自带的那个命令行工具,二进制包里就有,不需要额外装。

promtool check config /etc/prometheus/prometheus.yml
promtool check rules /etc/prometheus/rules/*.yml
promtool check metrics < metrics.txt
promtool test rules /etc/prometheus/rules/test.yml

check config会直接抓出缩进、冒号、未知字段这类低级错误,还会校验超时和间隔的关系。check metrics用来验导出内容是否合规,把curl下来的文本喂给它,有非UTF-8字节、标签名不合法、同名指标重复,都会点出具体行。

改完配置记得重载。启动参数带了 --web.enable-lifecycle的可以走HTTP,否则发SIGHUP:

curl -X POST http://localhost:9090/-/reload
kill -HUP $(pidof prometheus)

重载完看一眼日志里还有没有Scrape failed,连着两三个抓取周期都没有,才算真的修好。


scrape_timeout与scrape_interval的硬约束

全局默认值是scrape_interval 1m、scrape_timeout 10s。超时的硬规则只有一条:不能大于抓取间隔,否则promtool会直接拒绝,报错原文是 scrape timeout greater than scrape interval for scrape config with job name "xxx"。

实测下来,给慢目标的超时值取间隔的50% 到80% 比较稳,留出的余量能避免上一轮还没结束下一轮就开始。只慢一个目标就别动全局,在job里单独覆盖:

scrape_configs:
  - job_name: 'slow-exporter'
    scrape_interval: 60s
    scrape_timeout: 30s
    static_configs:
      - targets: ['10.0.1.42:9100']

反过来也有一种情况:所有job同时超时,那多半不是目标的问题,是Prometheus自己CPU或者内存被压住了。这时候调超时只会掩盖症状,该看的是Prometheus进程的资源占用和TSDB的head块大小。


relabel_configs把目标悄悄丢掉了

最隐蔽的一类。keep或者drop的正则写错,目标根本没进入抓取池,Targets页面上也不会显示DOWN,它是直接消失。之前有台机器上加了一条drop规则想过滤测试实例,正则漏了锚点,把生产实例一并干掉了,面板空了两天才被发现。

对比服务发现返回的数量和最终抓取的数量就能看出来:

curl -s 'http://localhost:9090/api/v1/targets?state=active' | python3 -c 'import json,sys;print("active:",len(json.load(sys.stdin)["data"]["activeTargets"]))'
curl -s 'http://localhost:9090/api/v1/targets?state=dropped' | python3 -m json.tool | head -60

state=dropped里能翻到被丢掉的目标,连同它身上的 __meta_* 原始标签一起,照着标签反推是哪条规则命中的即可。用promtool的 promtool check config 查不出这一类,它是逻辑问题不是语法问题。


认证与TLS这一段别跳过

401、403和握手失败基本都是配置问题,不是网络问题。Bearer token的话先拿同一串token在Prometheus机器上手动请求一遍:

curl -sS -H "Authorization: Bearer $(cat /etc/prometheus/api.token)" \
  --cacert /etc/ssl/certs/ca-certificates.crt https://10.0.1.42:9100/metrics | head

200说明凭据没问题,401就是token过期或者文件权限不对(Prometheus进程读不到),TLS报错则去看证书链和SAN有没有包含访问的那个IP。Kubernetes里抓取apiserver、kubelet这类HTTPS端点时这段几乎必配,ca_file、insecure_skip_verify的作用要分清楚,后者只是临时止血手段。


抓取正常但图上还是没数

有时候target明明是UP,图上依旧断断续续,问题就不在抓取而在写入或者查询那一段。

时钟不同步是最容易被忽略的一个。Prometheus和被抓端时间差太多,样本会被判定为太旧或者来自未来,日志里表现为out of order sample或者too old。之前碰到过一次,某台机器NTP服务没起来,慢了十几分钟,那台机器的曲线全断了而target一直是绿的。chrony或者systemd-timesyncd配好,再用 timedatectl 确认NTP synchronized是yes。

另一个是保留期。默认retention是15天,历史数据被清掉之后查什么都不奇怪,别误判成抓取故障。

告警侧也顺手验一下,Alertmanager收不到告警时先用amtool看:

amtool check-config /etc/alertmanager/alertmanager.yml
amtool alert --alertmanager.url=http://localhost:9093

给监控自己加一条 up{job=~".+"} == 0 的告警,持续5分钟才触发,省得抓取断了要等业务方来反馈才发现。


版本差异

promtool的子命令在不同版本里名字有出入。Ubuntu 22.04、24.04,的系统源里带的Prometheus版本普遍偏旧,而Prometheus 3.5.0、3.5.5,是官方LTS线,3.13.0、3.14.0、3.15.1,属于2026年,的较新分支;老版本上check rules的行为和新版本并不完全一致,升级前最好把规则文件先跑一遍test rules存下基线。

数据截至2026年11月。