Python爬虫需用prometheus_client的start_http_server启动HTTP服务暴露/metrics端点，不可仅依赖框架路由；须在独立线程运行、避免阻塞主逻辑，指标命名用snake_case并加业务前缀，更新须覆盖所有状态分支。
如何在爬虫代码中暴露 Prometheus 指标端点
Python 爬虫要被 Prometheus 抓取，必须启动一个 HTTP 服务暴露 /metrics 接口。直接用 flask 或 fastapi 写个端点太重，推荐用官方推荐的 prometheus_client 自带的 start_http_server ——它内建了轻量 HTTP server，不依赖 Web 框架。
关键点：这个 server 必须在主线程外独立运行，否则会阻塞爬虫逻辑。常见错误是把它放在主循环里，导致爬虫卡死。
- 在爬虫启动前调用
start_http_server(8000)，端口可自选，但需与 Prometheus 配置一致 - 定义指标时优先用
Gauge（如当前请求数、待抓取 URL 数）和Counter（如成功/失败请求数），避免误用Summary或Histogram增加采集开销 - 所有指标名必须符合 Prometheus 命名规范：
snake_case，且以业务前缀开头，比如spider_requests_total，别用mySpiderRequests
示例初始化：
from prometheus_client import start_http_server, Counter, Gauge
<p>start_http_server(8000)</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/00968c3c2c15" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Python免费学习笔记（深入）</a>”；</p><p>spider_requests_total = Counter('spider_requests_total', 'Total requests made', ['status'])
spider_pending_urls = Gauge('spider_pending_urls', 'Number of URLs waiting to be crawled')如何正确标记爬虫状态并更新指标值
指标只有在爬虫运行中持续更新才有意义。很多人只定义了指标，却忘了在关键节点调用 .inc() 或 .set()，结果 Grafana 里全是 0 或断崖式数据。
核心原则：状态变更即打点。不是“每秒更新一次”，而是“每次发生有意义的状态变化就更新”。比如：
- 发起请求前，
spider_pending_urls.dec()；收到响应后，spider_requests_total.labels(status='success').inc() - 遇到重试，用
spider_requests_total.labels(status='retry').inc()单独计数，别混进failure - 使用
Gauge表示瞬时状态时，务必在每次状态变化后显式.set(new_value)，不能只靠.inc()/.dec()推算
特别注意异常捕获后的指标更新：未 catch 的异常会导致指标丢失。务必把 .inc() 放在 try/except 的 finally 或对应分支里。
Prometheus 配置爬虫 job 时容易漏掉的关键项
Prometheus 默认不自动发现本地爬虫指标，必须手动加 scrape_config。最常被忽略的是 honor_labels 和超时设置，导致指标覆盖或采集失败。
-
scrape_timeout建议设为10s（默认 10s 可不写），但若爬虫单次请求耗时长，需同步调大，否则 Prometheus 认为 target down - 务必加上
honor_labels: true，否则爬虫自己打的status标签会被 Prometheus 强制覆盖成job和instance -
static_configs中的targets写['localhost:8000']就够，不用加http://—— Prometheus 不认协议前缀
配置片段示例：
scrape_configs: - job_name: 'spider' honor_labels: true scrape_timeout: 10s static_configs: - targets: ['localhost:8000']
Grafana 中展示爬虫状态时的典型陷阱
指标有了，但 Grafana 面板做出来全是平直线或 NaN？大概率是 PromQL 写错或时间窗口没对齐。
- 查请求数趋势别直接用
spider_requests_total，那是累计值，要用rate(spider_requests_total[5m])算每秒速率 - 查当前待抓 URL 数，用
spider_pending_urls即可，但确保刷新间隔 ≤ 15s（Prometheus 默认采样间隔），否则面板看起来“不动” - 多个爬虫实例共用同一端口时，
instance标签无法区分——得在代码里主动加labels(instance='prod_spider_01')，并在 Grafana 查询中用{job="spider", instance=~"prod.*"}过滤
真实调试建议：先在 Prometheus 表达式浏览器里跑通查询，再粘到 Grafana。别跳过这步，90% 的面板空白问题出在这里。
Python 3.11 本身对监控无特殊支持，但它的高性能异步调度让指标更新更及时；不过也正因如此，多线程/协程环境下更新 Gauge 必须加锁，否则数值可能错乱——这点极易被忽略。
