PHP OpenTelemetry 指标实战:Laravel 应用接入监控完整教程

用 PHP OpenTelemetry Metrics SDK 为 Laravel 记录请求数和耗时,验证路由标签、PHP-FPM 请求收尾与 OTLP/HTTP 导出,再接入观测云 DataKit。

最佳实践
PHP OpenTelemetry 指标实战:Laravel 应用接入监控完整教程封面

PHP 应用可以用 OpenTelemetry Metrics SDK 在 Laravel 中间件记录请求数和耗时。普通 PHP-FPM 请求的用户态 SDK 状态不会因为工作进程复用而跨请求保留,因此这个示例在每次请求收尾时明确导出。常驻队列 worker 的导出时机需要单独安排。

核心要点速览

  • Composer 安装 SDK、OTLP 导出器和 HTTP、Protobuf 依赖,Laravel 用中间件统一埋点。
  • Counter 记请求数,Histogram 记耗时。按状态码、请求方法和已匹配的路由模板分组,避免把实际 URL 路径当标签。
  • 示例每次请求尝试发送一份增量指标。先用本地 Collector 验证,再按 DataKit 的协议、地址和实际聚合方式接入。

安装 SDK

以下示例以 Laravel 13 为例,需要 PHP 8.3 或以上。所用 SDK 和 exporter 本身要求 PHP 8.2 或以上。示例使用 Guzzle 和 Composer 安装的 Protobuf 实现,手工埋点不要求 PHP 自动埋点扩展。请在已有 Laravel 项目根目录安装依赖。OpenTelemetry PHP 手工埋点文档

composer require open-telemetry/sdk:1.16.1 \
  open-telemetry/exporter-otlp:1.5.0 \
  guzzlehttp/guzzle:7.16.1 google/protobuf:5.36.2

将下面配置存为 collector.yaml,运行 otelcol-contrib --config=collector.yaml。Collector 的 HTTP 接收端只绑定本机,由 debug exporter 输出收到的指标。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:14318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]

用中间件实现请求计数

将代码存为 app/Http/Middleware/OpenTelemetryMetrics.php。用单调时钟测量 Laravel 下游处理耗时,再在 terminate() 根据框架最终返回的状态码记录指标。这个耗时不含向客户端发送响应体的时间,也不含遥测导出。Laravel 可能重新解析中间件实例,所以耗时暂存在请求对象中。Laravel 可终止中间件

<?php

namespace App\Http\Middleware;

use Closure;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Illuminate\Http\Request;
use OpenTelemetry\Contrib\Otlp\MetricExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
use OpenTelemetry\SDK\Metrics\Data\Temporality;
use OpenTelemetry\SDK\Metrics\MeterProvider;
use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use Symfony\Component\HttpFoundation\Response;
use Throwable;

final class OpenTelemetryMetrics
{
    private const DURATION = '_otel_demo_duration_seconds';

    public function handle(Request $request, Closure $next): Response
    {
        $started = hrtime(true);
        try {
            return $next($request);
        } finally {
            $request->attributes->set(self::DURATION, (hrtime(true) - $started) / 1e9);
        }
    }

    public function terminate(Request $request, Response $response): void
    {
        $duration = $request->attributes->get(self::DURATION);
        if (!is_float($duration)) {
            return;
        }

        $method = $request->method();
        $knownMethods = ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE', 'PATCH'];
        $attributes = [
            'http.request.method' => in_array($method, $knownMethods, true) ? $method : '_OTHER',
            'http.response.status_code' => $response->getStatusCode(),
        ];
        if ($route = $request->route()) {
            $attributes['http.route'] = '/' . ltrim($route->uri(), '/');
        }

        try {
            $factory = new HttpFactory();
            $client = new Client(['timeout' => 0.25]);
            $transport = (new PsrTransportFactory($client, $factory, $factory))->create(
                getenv('OTEL_EXPORTER_OTLP_METRICS_ENDPOINT') ?: 'http://127.0.0.1:14318/v1/metrics',
                'application/x-protobuf',
                maxRetries: 0,
            );
            $reader = new ExportingReader(new MetricExporter($transport, Temporality::DELTA));
            $provider = MeterProvider::builder()
                ->setResource(ResourceInfo::create(Attributes::create(['service.name' => 'checkout-php'])))
                ->addReader($reader)
                ->build();

            try {
                $meter = $provider->getMeter('example.checkout');
                $requests = $meter->createCounter('app.http.server.requests', '{request}');
                $latency = $meter->createHistogram('app.http.server.duration', 's', advisory: [
                    'ExplicitBucketBoundaries' => [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5],
                ]);
                $requests->add(1, $attributes);
                $latency->record($duration, $attributes);
            } finally {
                if (!$provider->shutdown()) {
                    error_log('OpenTelemetry metrics export did not complete');
                }
            }
        } catch (Throwable $error) {
            error_log('OpenTelemetry metrics export failed: ' . $error::class);
        }
    }
}

将下面回调合并到 bootstrap/app.php 的现有 withMiddleware 配置中。

->withMiddleware(function (\Illuminate\Foundation\Configuration\Middleware $middleware): void {
    $middleware->prepend(\App\Http\Middleware\OpenTelemetryMetrics::class);
})

示例的两条指标使用自定义名称,避免与自动 HTTP 埋点的指标混用。http.route 取已匹配的模板,例如 /otel-probe/{order},没有匹配时省略该属性。不要用实际路径、查询字符串或用户 ID 补这个字段。HTTP 指标语义约定

PHP 模型的特殊考量

请求级生命周期:上面的 ExportingReader 不会自己开定时器。这里用 shutdown() 收集并同步尝试发送一次。每份 Counter 是增量,不能把它当作一个跨请求持续增长的计数器。固定版本 ExportingReader

PHP-FPM worker 占用:Laravel 的 terminate() 在支持的 FastCGI 环境下可在响应发出后运行,但同步导出期间 worker 仍被占用。示例给 HTTP 客户端设置 250 ms 超时,并将 exporter 重试上限设为 0。生产中应从短超时、局部故障和实际吞吐评估开销,并优先考虑近端 Collector。在 Collector 批处理不等于 PHP 端少发请求。

Gauge 的语义:队列深度、连接数等瞬时值更适合由能读到真实状态的常驻进程或外部采集器观测。单个 PHP 请求里的对象无法感知整个 FPM 池的并发。

更多指标仪器

  • UpDownCounter:可以在共享同一份指标状态的常驻进程内记录活动请求数,开始加一、结束减一。短请求各自独立聚合时,不能据此推导整个 FPM 池的并发。
  • Histogram:记录耗时分布。示例的桶边界以秒为单位,从 0.005 到 2.5。按 SLO 设计桶,并确认下游保留桶与计数后再查询 P95。
  • 业务 Counter:只在订单创建或支付真正完成后加一,避免把 HTTP 成功数当作业务成功数。

在已经初始化的独立测试项目中,若还没有本地应用密钥,先执行 php artisan key:generate。然后在 routes/web.php 添加下面的合成探测路由。在终端运行 SESSION_DRIVER=array php artisan serve --host=127.0.0.1 --port=8000,再发起两次请求。

\Illuminate\Support\Facades\Route::get('/otel-probe/{order}', function (string $order) {
    abort_if($order === 'fail', 503);
    return response()->noContent();
});
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/otel-probe/alpha
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/otel-probe/fail

预期状态分别为 204 和 503。Collector 应收到各一份请求计数和耗时观测,二者的路由模板相同。用 5xx 增量之和除以同一窗口、同一范围内的全部请求增量得到错误率,只有计数无法计算 P95。

如果改为发送到观测云,示例读取进程环境变量 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,需要填完整的指标 URL。DataKit 默认 HTTP 端口为 9529,指标路径为 /otel/v1/metrics,使用 OTLP/HTTP Protobuf。部署时按实际接收端的私网连通、TLS 和鉴权要求配置。用同一对已知请求核对指标标签、增量语义及直方图桶,再建立看板和告警。DataKit 接入文档

常见问题(FAQ)

Q:PHP 的 OTel 成熟度如何? 手工指标 API 和 SDK 可用于上述场景。自动埋点需按框架、依赖和信号核实覆盖,已有同类 HTTP 指标时避免重复记录。

Q:Lumen/Symfony 能用吗? SDK 与框架无关,需改用相应中间件或事件订阅器,并确认能拿到最终响应和实际的进程生命周期。

Q:导出失败会影响业务请求吗? 取决于导出时机和超时。示例隔离异常并记录失败,不保证指标送达。即使在响应发出后,导出仍会占用 worker。

Q:CLI 脚本(队列消费者)怎么埋点? 常驻进程可以在启动时建一个 MeterProvider,保留 ExportingReader 引用,按工作循环或定时器调用 $reader->collect(),正常停机时调用一次 $provider->shutdown()。不要每处理一个任务就关闭长期使用的 provider。

系列阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台