使用 prometheus-client 暴露 /metrics 是最轻量可控方式；start_http_server 必须在 daemon=true 的独立线程中运行；指标类型需严格匹配用途（counter 累计、gauge 瞬时）；命名须全小写+下划线且以字母开头；更新须覆盖所有执行路径并置于 finally 块；counter 重置需用 rate() 计算速率。
直接用 prometheus-client 暴露 /metrics 端点是最轻量、最可控的方式，不依赖 Web 框架路由，也不需要额外反向代理配置。
start_http_server 必须在独立线程运行
很多人把 start_http_server(8000) 放在主逻辑里，结果整个爬虫或 Web 服务卡死——因为这个函数是阻塞式的 HTTP server 启动，会一直占住主线程。
- 必须用
threading.Thread启动，且设daemon=True，避免程序退出时线程残留 - 端口要和 Prometheus 的
scrape_config中的static_configs.targets一致，比如localhost:8000 - 若项目已用
uvicorn或gunicorn，别尝试把 metrics 挂到同一进程的 ASGI/WSGI 路由下——容易冲突或被中间件拦截
指标类型选错会导致数据不可用
用 Counter 记录“当前待处理请求数”，用 Histogram 统计“单次数据库查询耗时”，结果 Grafana 里全是 0 或断崖式跳变——这是典型类型误用。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
-
Counter只增不减，适合累计值：如http_requests_total、spider_errors_total -
Gauge可增可减可设值，适合瞬时状态：如spider_pending_urls、queue_length -
Histogram和Summary开销大，仅在真需分布统计（如 P95 延迟）时启用；普通耗时打点优先用Summary+@decorator
指标命名不规范会让 Prometheus 抓不到数据
Prometheus 抓取后显示 no metrics found，但 curl http://localhost:8000/metrics 确实返回内容——大概率是命名违规。
- 必须全小写 + 下划线：
spider_requests_total✅，SpiderRequestsTotal❌ - 必须以字母开头，不能含空格、点、破折号
- 建议加业务前缀（如
myapp_或api_），避免和系统指标（如process_cpu_seconds_total）混淆 - 标签名也需 snake_case：
.labels(status='error')✅，.labels(Status='error')❌
更新指标必须覆盖所有执行路径
异常未被捕获、重试逻辑漏掉 .inc()、异步任务没 await 就返回——这些都会导致指标值停滞或归零，告警失效。
- 所有
.inc()、.set()必须放在try/except的finally块，或明确写在每个分支里 - 异步函数中更新
Gauge时，确保await完成后再调.set()，否则可能并发写入脏数据 - 批量任务场景下，别只在循环外
.inc(100)，应每次处理完一个就.inc()，才能反映实时进度
最容易被忽略的是指标生命周期管理：如果 Web 进程重启，Counter 会重置为 0，但 Prometheus 默认不认为这是异常——你需要配合 rate() 函数计算速率，而不是直接看原始值。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
