Ідентифікатори запитів

Кожен запит, який обробляє 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);

Записи журналу доступу

Якщо журналювання доступу ввімкнено, кожен запис журналу містить поле 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",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:131.0) Gecko/20100101 Firefox/131.0",
    "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));

Промпти для вашого агента

Ці промпти розраховані на агента з підключеним MCP-сервером документації OxPHP — потрібні сторінки він прочитає сам.

prompt

Зістав журнали мого застосунку з ідентифікаторами запитів OxPHP. Прочитай сторінку `features/request-ids` через MCP-сервер документації OxPHP.
Додай ідентифікатор у логер, який уже використовує цей репозиторій, і в запити, які він надсилає до сервісів нижче за ланцюгом, із запасним варіантом на випадок, коли той самий код виконується поза OxPHP.

Див. також

Журналювання доступу — кожен запис журналу містить поле request_id
Функції PHP — повний довідник щодо oxphp_request_id() та інших вбудованих функцій