PHP框架中拼接Prometheus指标需严格遵循文本格式规范：响应头设为text/plain；指标含HELP、TYPE注释及主体行；标签值双引号包裹并转义；指标名合法；末尾空行；浮点数用点分隔。
在PHP框架中拼接Prometheus指标，核心是让自定义指标符合Prometheus文本格式规范，且能被Prometheus Server通过HTTP端点正确抓取。指标名称、标签、值、类型注释缺一不可，任意字段错位或换行不当都会导致抓取失败甚至服务崩溃。
确认暴露端点与Content-Type
第一步：确保你的PHP路由返回指标时响应头为 Content-Type: text/plain; charset=utf-8。Prometheus只接受该MIME类型的响应，其他类型（如application/json）会被静默丢弃。
第二步：用echo或print输出指标前，必须调用header('Content-Type: text/plain; charset=utf-8');。不加这句，Nginx/Apache可能默认返回text/html，Prometheus直接标记target为DOWN。
第三步：整个指标响应体末尾必须有一个空行。这是Prometheus协议硬性要求——最后一行为空行，否则采集器解析失败并报错“invalid metric line”。
立即学习“PHP免费学习笔记（深入）”；
拼接标准指标行（以Counter为例）
方法一：手动拼接最简格式
写一行HELP注释：echo "# HELP php_http_requests_total Total number of HTTP requests handled";
写一行TYPE注释：echo "# TYPE php_http_requests_total counter";
写指标主体：echo "php_http_requests_total{method=\"GET\",route=\"/user\",status=\"200\"} 127";
注意：标签值必须用双引号包裹，且内部双引号需转义；标签键名不能含空格或特殊字符，仅允许ASCII字母、数字、下划线。
方法二：用sprintf动态注入标签和值
$method = 'POST'; $route = '/api/order'; $status = '500'; $value = 3;
echo sprintf('php_http_requests_total{method="%s",route="%s",status="%s"} %d', addslashes($method), addslashes($route), addslashes($status), $value);
【addslashes()不是万能的，它不转义等号和大括号，若$route含{或=，必须额外过滤】
避免常见格式陷阱
指标名不能以数字开头，不能含连字符（-），例如http-requests-total是非法名，必须改写为http_requests_total。
同一指标多次出现时，标签组合必须完全一致，否则Prometheus视为不同指标——比如php_http_requests_total{method="GET"} 12 和 php_http_requests_total{method="get"} 3 会被当成两个独立序列。
浮点数值必须用点号分隔，禁止用逗号：php_memory_usage_bytes 1048576.0 ✅，php_memory_usage_bytes 1,048,576.0 ❌。
