Identyfikatory żądań

Każde żądanie przetwarzane przez OxPHP otrzymuje unikalny identyfikator na potrzeby śledzenia i korelowania logów. ID pojawia się w nagłówkach odpowiedzi oraz w logach dostępu, dzięki czemu masz jedną wartość, którą możesz śledzić przez wszystkie warstwy swojego stosu.

Jak to działa

OxPHP przypisuje ID każdemu przychodzącemu żądaniu, zanim uruchomi się cokolwiek innego. Jeśli klient przesłał już nagłówek X-Request-ID (na przykład z load balancera lub bramy API), OxPHP weryfikuje tę wartość i ją zachowuje. Aby przejść weryfikację, nagłówek musi mieć długość od 1 do 64 znaków i zawierać wyłącznie znaki alfanumeryczne, myślniki (-), podkreślenia (_) lub kropki (.). Wszystko, co nie spełnia tych wymagań, zostaje zastąpione świeżo wygenerowanym ID.

Gdy nie nadejdzie żaden prawidłowy X-Request-ID, OxPHP generuje 20-znakowe ID w postaci małych liter szesnastkowych, takie jak 67890abc12341a2b0042. Wartość koduje znacznik czasu, wartość unikalną dla procesu oraz monotoniczny licznik, dzięki czemu kolizje pomiędzy kontenerami i po restartach są skrajnie mało prawdopodobne.

Od tego momentu ID podróżuje wraz z żądaniem:

Trafia do nagłówka odpowiedzi X-Request-ID w każdej odpowiedzi.
Gdy rejestrowanie dostępu jest włączone, pojawia się w polu request_id każdego wpisu w logu dostępu.
Skrypty PHP mogą je odczytać przez oxphp_request_id().

Nagłówek odpowiedzi

Każda odpowiedź HTTP z OxPHP zawiera nagłówek X-Request-ID:

http

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

Gdy nadrzędny load balancer lub brama dostarcza X-Request-ID w przychodzącym żądaniu, OxPHP odsyła tę samą wartość w odpowiedzi, dzięki czemu śledzenie zachowuje ciągłość od początku do końca w całej infrastrukturze.

Odczytywanie ID żądania z PHP

Aktualne ID żądania odczytasz za pomocą 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,
]);

Przekaż ID żądania do usług podrzędnych, aby zachować śledzenie w wywołaniach 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);

Wpisy w logu dostępu

Gdy rejestrowanie dostępu jest włączone, każdy wpis w logu zawiera pole 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"
  }
}

Filtruj swój agregator logów po request_id, aby prześledzić pełny cykl życia pojedynczego żądania, w tym wszelkie błędy PHP lub wpisy w logach aplikacji odwołujące się do tego samego ID.

Rozwiązywanie problemów

W odpowiedziach brakuje nagłówka `X-Request-ID`

To sytuacja nieoczekiwana. OxPHP dodaje ten nagłówek do każdej odpowiedzi, więc jeśli go brakuje, prawdopodobnie usuwa go jakieś pośrednie proxy.

Sprawdź: Przetestuj bezpośrednio na OxPHP, bez żadnego proxy na trasie:

bash

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

ID z góry nie jest zachowywane

Przychodząca wartość X-Request-ID mogła nie przejść weryfikacji. OxPHP odrzuca ID, które są puste, dłuższe niż 64 znaki lub zawierają znaki inne niż alfanumeryczne, myślniki, podkreślenia lub kropki.

Sprawdź: Zbadaj wartość wysyłaną przez usługę nadrzędną i upewnij się, że spełnia wymagania dotyczące znaków i długości. Częste przyczyny niepowodzeń to wartości zawierające ukośniki, spacje lub nawiasy klamrowe.

`oxphp_request_id()` zwraca pusty ciąg znaków

Ta funkcja jest dostępna wyłącznie w OxPHP. Jeśli uruchomisz ten sam kod PHP pod PHP-FPM lub w CLI, funkcja nie będzie zdefiniowana. Zabezpiecz wywołania sprawdzeniem zgodności:

php

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

Zobacz także

Rejestrowanie dostępu — każdy wpis w logu zawiera pole request_id
Funkcje PHP — pełne odniesienie do oxphp_request_id() i innych wbudowanych funkcji