Идентификаторы запросов

Каждый запрос, который обрабатывает OxPHP, получает уникальный идентификатор для трассировки и корреляции логов. Идентификатор появляется в заголовках ответа и в логах доступа, поэтому у вас есть одно значение, по которому можно отследить запрос на всех уровнях вашего стека.

Как это работает

OxPHP присваивает идентификатор каждому входящему запросу ещё до того, как выполнится что-либо ещё. Если клиент уже прислал заголовок X-Request-ID (например, от балансировщика нагрузки или API-шлюза), OxPHP проверяет это значение и сохраняет его. Чтобы пройти проверку, заголовок должен быть длиной от 1 до 64 символов и содержать только буквы и цифры, дефисы (-), подчёркивания (_) или точки (.). Всё, что не проходит проверку, заменяется на свежесгенерированный идентификатор.

Когда корректный X-Request-ID не приходит, OxPHP генерирует 20-символьный идентификатор в шестнадцатеричном виде в нижнем регистре, например 67890abc12341a2b0042. Значение кодирует метку времени, уникальное для процесса значение и монотонный счётчик, поэтому коллизии между контейнерами и перезапусками крайне маловероятны.

Дальше идентификатор путешествует вместе с запросом:

Он уходит в заголовке ответа X-Request-ID в каждом ответе.
Когда включено логирование доступа, он появляется в поле request_id каждой записи лога доступа.
PHP-скрипты могут прочитать его через oxphp_request_id().

Заголовок ответа

Каждый HTTP-ответ от OxPHP содержит заголовок 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

Прочитайте текущий идентификатор запроса с помощью 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:

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, чтобы проследить весь жизненный цикл одного запроса, включая любые ошибки PHP или записи прикладных логов, которые ссылаются на тот же идентификатор.

Устранение неполадок

Заголовок `X-Request-ID` отсутствует в ответах

Это неожиданно. OxPHP добавляет заголовок в каждый ответ, поэтому, если он отсутствует, скорее всего, его вырезает промежуточный прокси.

Проверьте: обратитесь напрямую к OxPHP без каких-либо прокси на пути:

bash

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

Идентификатор от вышестоящего сервиса не сохраняется

Входящее значение X-Request-ID, возможно, не проходит проверку. OxPHP отклоняет идентификаторы, которые пусты, длиннее 64 символов или содержат символы, отличные от букв, цифр, дефисов, подчёркиваний или точек.

Проверьте: изучите значение, которое отправляет вышестоящий сервис, и убедитесь, что оно соответствует требованиям по символам и длине. Частые причины сбоя — значения со слешами, пробелами или фигурными скобками.

`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));

Смотрите также

Логирование доступа — каждая запись лога содержит поле request_id
Функции PHP — полный справочник по oxphp_request_id() и другим встроенным функциям