PHP OpenTelemetry 指標實作:量測 Laravel HTTP 請求

以 PHP OpenTelemetry Metrics SDK 記錄 Laravel 的請求數和處理時間,驗證路由樣板、PHP-FPM 請求結束流程與 OTLP/HTTP 匯出。

最佳實務
查看應用程式遙測資料的插圖

即使 PHP-FPM 的工作程序還有餘裕,Laravel 結帳 API 也可能回傳 503。先記下 Laravel 實際送出的狀態碼,以及產生回應所花的時間。標籤用 /orders/{order} 這種路由樣板,就能把不同訂單 ID 的請求放在同一個時間序列裡分析。

準備本機 OTLP 接收端

範例以 Laravel 13 為基礎,需 PHP 8.3 以上。固定版本的 OpenTelemetry SDK 與 OTLP 匯出器本身需要 PHP 8.2 以上。HTTP 連線用 Guzzle,Protobuf 由 Composer 套件提供。手動埋點不需要 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 啟動。OTLP/HTTP 接收器只在本機迴路監聽。接上後端前,可從 debug 匯出器查看收到的資料點。

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

記錄 Laravel 實際回傳的結果

把中介層存成 app/Http/Middleware/OpenTelemetryMetrics.php。用單調時鐘量測後續 Laravel 處理時間,這段時間不含傳送回應內容或匯出遙測資料。Laravel 呼叫 terminate() 時可能建立另一個中介層物件,因此把耗時存到請求物件。狀態碼從 terminate() 收到的最終回應讀取,包含由框架處理過的 HTTP 例外。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 指標語意慣例(英文)

比對正常請求和 503 的輸出

使用已初始化的隔離 Laravel 測試專案。若尚未設定本機應用程式金鑰,先執行 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 比率,把同一時間窗、同一範圍內的 5xx 增量加總,除以全部請求的增量總和。範例的桶邊界從 5 毫秒到 2.5 秒,實際使用時要配合關心的延遲門檻。P95 要依耗時分布和各桶計數估計,單看請求數推不出來。

若要接到觀測雲,先用同兩筆請求查看實際存下的資料。程式從處理程序環境變數 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 讀取完整 URL。DataKit 的預設 HTTP 埠為 9529,指標路徑為 /otel/v1/metrics,傳送格式用 Protobuf。依部署環境設定私有連線、TLS 和驗證。建立儀表板前,先確認接收端如何處理增量與直方圖桶。DataKit OpenTelemetry 收集器(簡體中文)

決定指標該在哪一層累積

PHP-FPM 會重複使用工作程序,普通請求建立的 SDK 物件卻會隨請求結束。此 ExportingReader 本身沒有計時器,範例透過 shutdown() 收集增量並同步嘗試傳送一次。每次輸出各自獨立,不能當成跨請求累計的計數。固定版本的 PHP ExportingReader

在 FastCGI 上,Laravel 可以在送出回應後做終止處理,匯出期間仍占用工作程序。範例將 HTTP 用戶端的逾時設為 250 ms,並停用匯出器重試。流量較大時,可以分別量測接收端正常和無回應時的工作程序占用。就近部署 Collector 有助於批次寫入下游,但這個範例的 PHP 端仍會每個請求送一次,也不保證送達。

常駐佇列 worker 可以讓多個工作共用同一個 provider。保留 reader 參照,依工作迴圈或計時器呼叫 $reader->collect(),正常結束時再呼叫一次 $provider->shutdown()。佇列深度這類 Gauge 應由能讀到共用狀態的元件觀測。在互相隔離的請求裡各自增減 UpDownCounter,無法得出整個 FPM 池的並行處理數。

需要讓 Prometheus 拉取 /metrics 時,可參考 PHP 與 Prometheus 指南(簡體中文)。指標類型與聚合另見 OpenTelemetry 指標(英文)。

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

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

立即開始

选择观测云版本

代码托管平台