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 指標(英文)。
