prometheus targets端口错误或localhost网络隔离会导致无数据采集；python应用必须用prometheus_client暴露标准/metrics格式；grafana数据源需填容器内可解析的服务名如http://prometheus:9090；counter类指标须用rate()计算速率，不可直接绘图。
prometheus.yml 配置里 targets 写错端口会直接不采集
Prometheus 启动后没数据，第一反应不是 Grafana 没配好，而是 prometheus.yml 里 targets 的端口根本连不通。常见错误是把 Python 应用的指标端口（比如 8000）写成 80 或漏掉冒号，或者用了 localhost 却在容器里跑——宿主机和容器网络隔离，localhost 指的是 Prometheus 自己的容器内部。
- 检查
targets是否用容器名或服务名代替localhost（Docker Compose 场景下必须这样） - 确认 Python 应用已启动且
/metrics路径可 curl 访问：curl http://your-app:8000/metrics - 如果用
host.docker.internal，注意 Docker Desktop for Mac/Windows 才默认支持，Linux 需手动加--add-host=host.docker.internal:host-gateway - 端口映射要一致：Python 应用暴露
8000，prometheus.yml的targets就得写app:8000，不是app:80
Python 应用暴露 metrics 必须用 prometheus_client 的 start_http_server
很多人自己写 HTTP handler 返回文本格式 metrics，但 Prometheus 只认标准格式：行首是 # HELP/# TYPE，指标行末不能有多余空格，类型声明必须匹配实际值。手写极易出错，而且不支持多进程场景下的计数器合并。
- 必须用
prometheus_client库，不是自己拼字符串：pip install prometheus-client - 单进程直接调
start_http_server(8000)；多进程（如 Gunicorn）要用MultiProcessCollector+ 共享文件系统目录 - 不要在 Flask/FastAPI 路由里用
generate_latest()手动返回——它不处理并发锁，高并发下可能返回截断内容 - 暴露的路径默认是
/metrics，别改成/api/metrics之类，除非同步改 Prometheus 的metrics_path配置
Grafana 添加 Prometheus 数据源时 URL 填错会导致 400 或 CORS
前端报 HTTP Error Bad Request 或浏览器控制台显示 CORS error，大概率是 Grafana 容器里填的 Prometheus URL 不对。Grafana 是前端直连 Prometheus 的，不是通过后端代理——所以填 http://localhost:9090 在容器里永远失败。
- Docker Compose 下统一用服务名：
http://prometheus:9090（前提是prometheus是docker-compose.yml里定义的服务名） - 如果 Grafana 和 Prometheus 不在同个 compose 文件，确保它们在同一个自定义网络，且防火墙放行
9090 - 不要勾选
Forward OAuth Identity，Python 应用没做 OAuth，开了反而触发 401 - 测试连接前先进 Grafana 容器执行：
curl -v http://prometheus:9090/-/readyz，通了再试 Web 界面
Python counter 类型指标累加后不重置，导致 Grafana 图表「只涨不跌」
比如用 Counter 统计请求总数，画出来的图永远单调上升，但你想看「每秒请求数」——这不是图表设置问题，是指标类型和查询方式没配对。
立即学习“Python免费学习笔记（深入）”；
-
Counter必须用 PromQL 的rate()或irate()计算速率，不能直接画原始值：rate(http_requests_total[5m]) - 避免用
increase()在短时间窗口（如[1m]）里计算，浮点误差大，尤其在实例重启后 counter 重置时会跳变 - 如果真需要“当前值”，比如在线用户数，该用
Gauge，不是Counter - 本地开发时频繁重启 Python 进程，
Counter会归零，rate()在刚启动的几分钟内可能为 0 或 NaN，属正常现象
Grafana 里看到数据但曲线平直、数值异常低，先看 PromQL 表达式是否用了 sum() 却没加 by 分组，再查 Python 进程是否真的在打点——curl 一下 /metrics，别只信图表。
