PHP の OpenTelemetry メトリクス:Laravel の HTTP リクエストを計測する
PHP OpenTelemetry Metrics SDK で Laravel のリクエスト数と処理時間を記録。ルートのテンプレート、PHP-FPM の終了処理、OTLP/HTTP 送信を確認します。
PHP-FPM のワーカープールに余裕があっても、Laravel の注文 API は 503 を返すことがある。まず、Laravel が返したステータスと応答を作るまでの処理時間を記録しよう。集計には実際の URL ではなく、/orders/{order} のようなルートのテンプレートを使う。注文 ID が増えても、同じルートのデータをまとめて見られる。
ローカルに OTLP の受信先を用意する
例では PHP 8.3 以上が必要な Laravel 13 を使う。バージョンを固定した 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 のレシーバーはループバックだけで待ち受ける。デバッグ出力で、バックエンドへつなぐ前にメトリクスを確認できる。
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() の呼び出し時に別のミドルウェアインスタンスを解決することがあるため、計測値はリクエストに保存する。ステータスには、HTTP 例外から生成された応答も含め、terminate() に渡された最終応答の値を使う。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 で起動し、二つの URL にアクセスする。
\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 の出力では、それぞれにカウンターの増分 1 とヒストグラムの観測値 1 件が届く。ステータスは異なるが、ルートのテンプレートは同じだ。5xx の割合は、同じ時間帯と集計範囲で 5xx の増分合計を全リクエストの増分合計で割る。例のバケット境界は 5 ms から 2.5 秒まで。実際に追うしきい値に合わせて設定する。P95 を推定するには、処理時間の分布とバケットごとの件数が必要になる。
Guance に接続したら、同じ二つのリクエストで保存された値を確かめる。このコードはプロセスの環境変数 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、エクスポーターの再試行回数を 0 にした。負荷が大きい場合は、受信先が正常なときと応答しないときの両方でワーカーの占有を測る。近くの Collector が後続の転送をまとめても、リクエストごとに初期化するこの PHP 側の送信回数は変わらない。配信は保証されない。
常駐のキューワーカーなら、複数のジョブで一つのプロバイダーを使える。リーダーを保持し、ワーカーのループやタイマーで $reader->collect() を呼ぶ。正常終了時は $provider->shutdown() を一度だけ実行する。キューの深さなどの Gauge は共有状態を読めるコンポーネントで測る。別々のリクエストで UpDownCounter を増減しても、FPM プール全体の同時実行数は求められない。
プル方式の /metrics が必要なら PHP と Prometheus のガイド(中国語・簡体字)。計測器と集計の違いは OpenTelemetry メトリクス(英語) を参照。
