python金丝雀发布需手动埋点并暴露/metrics端点，因canary是部署策略而非代码组件；须用prometheus_client识别x-canary请求头、打标记录指标，并确保/metrics为get接口且返回text/plain格式。
Python 金丝雀发布没有内置监控指标——得靠你手动埋点、暴露、采集，否则 Prometheus 什么也抓不到。
为什么 canary 本身不带指标？
Python 生态里没有叫 “金丝雀发布” 的标准库或框架；canary 是部署策略，不是代码组件。你用的是 Flask、FastAPI 或 uvicorn，它们默认不统计“当前流量里多少进了 v2 版本”。指标得你自己定义、打点、暴露 HTTP 接口供 Prometheus 抓取。
- 常见错误现象：
Prometheus target is down或指标里压根没canary_request_total这类名称 - 根本原因：没加
/metrics端点，也没在请求路径/响应头里标记 canary 流量来源 - 别指望
pip install canary-monitor——目前不存在这个包
怎么让 canary 流量可被观测？
核心就两件事：识别 canary 请求 + 记录带标签的指标。推荐用 prometheus_client 配合中间件或路由装饰器。
- 使用场景：你在 Nginx 或 Istio 做了 header 路由（比如
X-Canary: true），后端要读它 - 实操建议：在每个请求入口检查
request.headers.get("X-Canary")，然后调用canary_requests_total.inc(labels={"version": "v2"}) - 参数差异：
labels必须一致（比如都含version和endpoint），否则 Prometheus 会当多个指标处理 - 简短示例：
from prometheus_client import Counter<br>canary_requests_total = Counter("canary_request_total", "Total canary requests", ["version", "endpoint"])<br><br># 在 FastAPI 路由里<br>@app.get("/api/data")<br>def get_data(request: Request):<br> version = "v1"<br> if request.headers.get("X-Canary") == "true":<br> version = "v2"<br> canary_requests_total.labels(version=version, endpoint="/api/data").inc()<br> return {"data": "ok"}
暴露 /metrics 时容易踩哪些坑？
很多人写了指标但 Prometheus 抓不到，问题几乎全出在暴露环节。
立即学习“Python免费学习笔记（深入）”；
- 常见错误现象：
HTTP 404或HTTP 405返回，或者返回空内容 - 实操建议：确保
/metrics是 GET 接口，且返回text/plain; version=0.0.4（不是application/json） - 兼容性影响：用
prometheus_client.make_wsgi_app()时，别把它挂到/metrics/（尾部斜杠会导致 301 重定向，Prometheus 不跟） - 性能注意：不要在
/metrics里做 DB 查询或远程调用——它会被高频轮询，一卡整个采集链路
最常被忽略的一点：canary 指标必须和业务指标对齐时间窗口。比如你用 rate(canary_request_total[5m])，但上游网关只保留 2 分钟的 header 标记，那 rate 就会失真。指标本身没毛病，错在上下文没对齐。
