リクエストID

OxPHP が処理するすべてのリクエストには、トレーシングとログ相関のための一意の識別子が付与されます。このIDはレスポンスヘッダーとアクセスログに現れるため、スタックのあらゆる層を横断してリクエストを追跡するための値が1つで済みます。

仕組み

OxPHP は、他の何かが実行される前に、受信する各リクエストにIDを割り当てます。クライアントがすでに X-Request-ID ヘッダーを送信していた場合（たとえばロードバランサーやAPIゲートウェイから）、OxPHP はその値を検証して保持します。検証を通過するには、ヘッダーが1〜64文字の長さで、英数字、ハイフン（-）、アンダースコア（_）、ドット（.）のみを含んでいる必要があります。検証に失敗したものは、新たに生成されたIDに置き換えられます。

有効な X-Request-ID が届かない場合、OxPHP は 67890abc12341a2b0042 のような20文字の小文字16進数のIDを生成します。この値はタイムスタンプ、プロセス固有の値、単調増加するカウンターをエンコードしているため、コンテナや再起動をまたいだ衝突は極めて起こりにくくなっています。

そこからIDはリクエストとともに移動します。

すべてのレスポンスの X-Request-ID レスポンスヘッダーとして送出されます。
アクセスログが有効な場合、すべてのアクセスログエントリーの request_id フィールドに現れます。
PHP スクリプトは oxphp_request_id() を介してこれを読み取れます。

レスポンスヘッダー

OxPHP からのすべての HTTP レスポンスには X-Request-ID ヘッダーが含まれます。

http

HTTP/1.1 200 OK
X-Request-ID: 67890abc12341a2b0042
Content-Type: text/html; charset=utf-8

上流のロードバランサーやゲートウェイが受信リクエストに X-Request-ID を付与している場合、OxPHP は同じ値をレスポンスにそのまま返すため、インフラ全体でエンドツーエンドの追跡可能性が保たれます。

PHP からリクエストIDを読み取る

現在のリクエストIDは oxphp_request_id() で読み取ります。

php

<?php
$requestId = oxphp_request_id();

// Include in application logs for correlation
$logger->info('Processing order', [
    'request_id' => $requestId,
    'order_id'   => $orderId,
]);

API 呼び出しをまたいで追跡可能性を保つため、リクエストIDを下流のサービスへ転送します。

php

<?php
$requestId = oxphp_request_id();

$ch = curl_init('https://api.example.com/users');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-Request-ID: $requestId",
]);
$response = curl_exec($ch);
curl_close($ch);

アクセスログエントリー

アクセスログが有効な場合、すべてのログエントリーには request_id フィールドが含まれます。

json

{
  "timestamp": "2026-02-11T12:34:56.789Z",
  "level": "INFO",
  "fields": {
    "request_id": "67890abc12341a2b0042",
    "method": "GET",
    "path": "/api/users",
    "status": 200,
    "duration_us": 1234,
    "remote_ip": "10.0.0.1",
    "message": "request completed"
  }
}

ログアグリゲーターを request_id でフィルタリングすれば、同じIDを参照する PHP エラーやアプリケーションログエントリーも含めて、単一のリクエストのライフサイクル全体を追跡できます。

トラブルシューティング

レスポンスに `X-Request-ID` ヘッダーが見当たらない

これは想定外です。OxPHP はすべてのレスポンスにこのヘッダーを付与するため、見当たらない場合はおそらく中間のプロキシがそれを除去しています。

確認: 経路にプロキシを介さず、OxPHP に対して直接テストしてください。

bash

curl -v http://localhost:8080/ 2>&1 | grep -i x-request-id

上流のIDが保持されない

受信した X-Request-ID の値が検証に失敗している可能性があります。OxPHP は、空である、64文字を超える、または英数字・ハイフン・アンダースコア・ドット以外の文字を含むIDを拒否します。

確認: 上流が送信している値を調べ、文字と長さの要件を満たしているか確認してください。よくある失敗の原因には、スラッシュ・スペース・波括弧を含む値があります。

`oxphp_request_id()` が空文字列を返す

この関数は OxPHP 内でのみ利用可能です。同じ PHP コードを PHP-FPM や CLI 上で実行した場合、この関数は定義されていません。互換性チェックで呼び出しをガードしてください。

php

<?php
$requestId = function_exists('oxphp_request_id')
    ? oxphp_request_id()
    : ($_SERVER['HTTP_X_REQUEST_ID'] ?? uniqid('', true));

リクエストID

仕組み

レスポンスヘッダー

PHP からリクエストIDを読み取る

アクセスログエントリー

トラブルシューティング

関連項目