ID de requête

Chaque requête traitée par OxPHP reçoit un identifiant unique pour le traçage et la corrélation des logs. L'ID apparaît dans les en-têtes de réponse et dans les logs d'accès, ce qui vous donne une seule valeur à suivre pour tracer une requête à travers chaque couche de votre stack.

Fonctionnement

OxPHP attribue un ID à chaque requête entrante avant que quoi que ce soit d'autre ne s'exécute. Si le client a déjà envoyé un en-tête X-Request-ID (par exemple depuis un load balancer ou une passerelle d'API), OxPHP valide cette valeur et la conserve. Pour passer la validation, l'en-tête doit faire de 1 à 64 caractères et ne contenir que des caractères alphanumériques, des tirets (-), des tirets bas (_) ou des points (.). Toute valeur qui échoue est remplacée par un ID nouvellement généré.

Lorsqu'aucun X-Request-ID valide n'arrive, OxPHP génère un ID hexadécimal en minuscules de 20 caractères, tel que 67890abc12341a2b0042. La valeur encode un horodatage, une valeur propre au processus et un compteur monotone, si bien que les collisions entre conteneurs et redémarrages sont extrêmement improbables.

À partir de là, l'ID voyage avec la requête :

Il ressort dans l'en-tête de réponse X-Request-ID sur chaque réponse.
Lorsque la journalisation des accès est activée, il apparaît dans le champ request_id de chaque entrée de log d'accès.
Les scripts PHP peuvent le lire via oxphp_request_id().

En-tête de réponse

Chaque réponse HTTP d'OxPHP inclut l'en-tête X-Request-ID :

http

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

Lorsqu'un load balancer ou une passerelle en amont fournit un X-Request-ID sur la requête entrante, OxPHP renvoie la même valeur dans la réponse, si bien que la traçabilité tient de bout en bout à travers votre infrastructure.

Lire l'ID de requête depuis PHP

Lisez l'ID de requête courant avec 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,
]);

Transmettez l'ID de requête aux services en aval pour conserver la traçabilité à travers les appels d'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);

Entrées du log d'accès

Lorsque la journalisation des accès est activée, chaque entrée de log inclut le champ 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"
  }
}

Filtrez votre agrégateur de logs par request_id pour tracer le cycle de vie complet d'une seule requête, y compris les erreurs PHP ou les entrées de log applicatives qui référencent le même ID.

Dépannage

L'en-tête `X-Request-ID` est absent des réponses

C'est inattendu. OxPHP ajoute l'en-tête à chaque réponse, donc s'il est absent, c'est probablement qu'un proxy intermédiaire le supprime.

À vérifier : Testez directement contre OxPHP, sans aucun proxy sur le chemin :

bash

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

Un ID en amont n'est pas préservé

La valeur X-Request-ID entrante échoue peut-être à la validation. OxPHP rejette les ID qui sont vides, plus longs que 64 caractères, ou qui contiennent des caractères autres que des caractères alphanumériques, des tirets, des tirets bas ou des points.

À vérifier : Inspectez la valeur envoyée par votre amont et vérifiez qu'elle respecte les exigences de caractères et de longueur. Les échecs les plus courants concernent des valeurs contenant des barres obliques, des espaces ou des accolades.

`oxphp_request_id()` renvoie une chaîne vide

Cette fonction n'est disponible qu'au sein d'OxPHP. Si vous exécutez le même code PHP sous PHP-FPM ou en CLI, la fonction n'est pas définie. Protégez les appels avec un contrôle de compatibilité :

php

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

Voir aussi

Journalisation des accès — chaque entrée de log inclut le champ request_id
Fonctions PHP — référence complète pour oxphp_request_id() et les autres fonctions intégrées