PHP应用需通过HTTP端点暴露Prometheus指标，推荐使用promphp/promphp等库管理CollectorRegistry单例，避免手写缺陷；注意响应头、格式规范、label安全及抓取配置匹配。
PHP 应用如何暴露 Prometheus metrics 端点
PHP 本身没有内置的 Prometheus 指标暴露能力，必须通过 HTTP 接口返回符合 text/plain; version=0.0.4 格式的指标文本。最直接的方式是手写一个路由（如 /metrics），手动拼接指标行，但更稳妥的做法是使用 promphp/promphp 或 robjones/p8s-php-exporter 这类轻量库——它们不依赖扩展，纯用户态实现，兼容 PHP 7.4+ 和 8.x。
关键不是“能不能”，而是“要不要引入额外依赖”。如果只是导出几个计数器（比如请求总量、错误数），手写几行 echo 更快；如果要支持直方图、标签（labels）、注册中心式管理，就该用库。
- 手写示例：确保响应头为
Content-Type: text/plain; charset=utf-8，每行以# HELP或# TYPE开头，指标名后跟{label="value"}和数值，末尾换行 - 避免在
/metrics中做耗时操作（如查 DB、调远程 API），否则会拖慢 Prometheus 抓取，甚至触发超时（默认 10s） - 不要把敏感信息塞进 label 值（如
user_id="12345"），label 维度爆炸会导致 Prometheus 内存飙升
用 Prometheus\CollectorRegistry 管理指标生命周期
如果你选了 promphp/promphp，核心是 CollectorRegistry 实例——它负责收集、去重、序列化所有已注册的指标。不能每次请求都 new 一个 registry，否则 counter 会从 0 重新计数；应该单例复用（例如放在 DI 容器或全局静态变量里）。
常见误区是把 Gauge 当作瞬时值“快照”来反复 set，结果发现 Prometheus 图形毛刺严重。其实 Gauge 适合表示可增可减的状态（如内存占用），而真正需要“采样快照”的场景（如接口耗时），应该用 Counter 累加 + label 区分状态，再由 Prometheus 的 rate() 或 histogram_quantile() 计算派生指标。
立即学习“PHP免费学习笔记（深入）”；
-
Counter只能 +，适合累计事件（如http_requests_total{method="POST",status="200"}） -
Gauge可 set/inc/dec，适合当前值（如php_memory_usage_bytes） -
Histogram要预设 buckets，且每个 bucket 是独立Counter，别漏掉_sum和_count配套指标
为什么 cURL 抓不到 /metrics 返回？检查这三处
本地 curl http://localhost:8000/metrics 返回空或 404，大概率不是代码问题，而是 Web 服务器配置或 PHP 运行模式卡住了。
- PHP-FPM 模式下，确认 Nginx/Apache 把
/metrics路由正确转发给了 PHP，而不是被静态文件规则拦截（比如try_files $uri $uri/ /index.php?$query_string没覆盖到） - Swoole/Swoft 等常驻进程框架，需确认路由注册时机——不能在每次请求时才 new Collector，要在 Worker 启动时初始化 registry
- 某些安全模块（如 Suhosin、mod_security）会拦截含
{或=的响应体，导致 metrics 被截断；临时关掉测试，或改用更宽松的输出格式（如去掉 label，先验证基础通路）
对接 Prometheus Server 的抓取配置要点
PHP exporter 不是独立服务，它只是个普通 HTTP 接口，所以 Prometheus 的 scrape_configs 里只需填目标地址和路径，无需特殊 job_name（除非你要区分环境）。
重点在于 scrape_interval 和 scrape_timeout 的匹配：如果 PHP 应用偶尔慢（比如 GC 导致 3s 延迟），就把 scrape_timeout 设为 scrape_interval 的 70% 左右（如 interval=30s → timeout=20s），避免频繁 timeout 报错掩盖真实问题。
- 多个 PHP 实例（如集群）要用 service discovery 或 static_configs 列出全部地址，别只写一个
- 如果用了反向代理（如 Traefik/Nginx），确认 proxy_buffering 关闭，否则 metrics 响应可能被缓存或截断
- 上线前用
curl -v http://your-app/metrics 2>&1 | head -20看响应头和前几行，确认格式无误——Prometheus 对空行、乱码、缺失# TYPE极其敏感
最难调的往往不是 PHP 侧代码，而是指标语义设计：比如该用 http_request_duration_seconds_bucket 还是自定义 api_response_time_ms，取决于你后续想用 histogram_quantile() 还是直接画折线图。这个决策一旦定错，后期改成本远高于初期多花十分钟想清楚 label 维度。
