PHP OpenTelemetry 指标实战：Laravel 应用接入监控完整教程
为 PHP/Laravel 应用接入 OpenTelemetry 指标：Composer 安装 SDK、中间件实现请求计数、Counter/Gauge/Histogram 用法、OTLP 导出配置，最终接入观测云实现 PHP 应用的统一监控告警。含完整中间件代码。
PHP 应用的 OpenTelemetry 指标接入以 Composer 包 open-telemetry/opentelemetry 为基础，通过 Laravel 中间件在请求生命周期中埋点计数——PHP 的"请求-响应"短生命周期模型意味着指标在进程内聚合、按周期导出，与常驻内存的 Go/Java 略有差异，但整体套路一致。
核心要点速览
- Composer 安装 SDK 与 OTLP exporter，Laravel 用中间件统一埋点；
- Counter 记请求总量并按状态码/路径/方法打属性；
- 指标按周期批量导出到 OTLP 端点，PHP-FPM 模型下导出发生在响应收尾阶段；
- 端点指向观测云 DataKit，指标进观测云做看板与告警。
安装 SDK
composer require open-telemetry/opentelemetry \
open-telemetry/exporter-otlp \
open-telemetry/sdk
PHP 的 OTel 生态相对年轻，Composer 安装时注意 PHP 版本要求（8.0+）与扩展依赖（ext-json、ext-mbstring）。
用中间件实现请求计数
php artisan make:middleware OpenTelemetryMiddleware
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use OpenTelemetry\SDK\Metrics\MeterProviderInterface;
class OpenTelemetryMiddleware
{
private $requestCounter;
private $latencyHistogram;
public function __construct(MeterProviderInterface $meterProvider)
{
$meter = $meterProvider->getMeter('laravel-app');
$this->requestCounter = $meter->createCounter(
'http.requests.total', 'Total number of HTTP requests', 'requests'
);
$this->latencyHistogram = $meter->createHistogram(
'http.request.duration', 'HTTP request latency', 's'
);
}
public function handle(Request $request, Closure $next)
{
$start = microtime(true);
$response = $next($request);
$attributes = [
'status' => $response->getStatusCode(),
'path' => $request->path() === '/' ? 'root' : $request->path(),
'method' => $request->method(),
];
$this->requestCounter->add(1, $attributes);
$this->latencyHistogram->record(microtime(true) - $start, $attributes);
return $response;
}
}
注册为全局中间件后，每个请求自动计数并记录耗时分布。
PHP 模型的特殊考量
请求级生命周期：PHP-FPM 每个请求独立，指标 SDK 在请求结束时批量导出。高流量下建议缩短导出周期（5-10s）或使用共享内存聚合方案，避免每个请求都发起 HTTP 导出请求拖慢响应。
OPcache 注意：OTel 类加载建议预热进 OPcache，减少每请求的初始化开销。
Gauge 的语义：短生命周期下"瞬时值"意义有限——队列深度、连接数这类 Gauge 指标更适合由独立的常驻进程（或观测云 DataKit 的对应采集器）采集。
更多指标仪器
- UpDownCounter：当前正在处理的请求数（请求开始 +1、结束 -1），反映并发水位；
- Histogram：如上面的耗时分布，桶边界按接口 SLO 自定义；
- 业务 Counter：订单创建数、支付成功数——业务指标往往比技术指标更早暴露问题。
观测云落地：PHP 应用进统一监控
OTLP exporter 端点指向观测云 DataKit（HTTP 4318），指标进入观测云指标模块：用 DQL 按 path/status 聚合出 5xx 率与 P95 延迟，监控器配置"5xx 率 > 2% 持续 3 分钟"类告警，通知直达钉钉/企微。
PHP 的链路追踪另有专门方案（ext-opentelemetry 扩展 + 自动埋点），接入后可在观测云 APM 中把慢请求的指标尖峰下钻到具体 Trace，定位是数据库慢查询还是外部 API 拖后腿。
常见问题（FAQ）
Q：PHP 的 OTel 成熟度如何？ 指标与链路的 SDK 已稳定可用；自动埋点生态（框架级）不如 Java/Node.js 丰富，主流框架靠中间件手动埋点即可覆盖。
Q：Lumen/Symfony 能用吗？ 可以，思路相同：框架中间件或事件订阅器中埋点，SDK 与框架无关。
Q：导出失败会影响业务请求吗？ 合理配置下不会——导出超时设短（1-2s）、失败静默记录日志，切勿让监控阻塞业务。
Q：CLI 脚本（队列消费者）怎么埋点？ 常驻 CLI 进程与 Go/Java 模型相同，正常初始化 MeterProvider 即可；注意 worker 重启时调用 shutdown 刷出最后一批指标。
