Métriques Prometheus

OxPHP expose des métriques compatibles Prometheus au format d'exposition texte via GET /metrics sur le serveur interne. Elles couvrent le débit des requêtes, les temps de réponse, l'état des connexions, la santé du pool de workers, la mise en cache des fichiers statiques, l'efficacité de la compression et les performances du mode worker.

Activation des métriques

Définissez INTERNAL_ADDR pour démarrer le serveur interne :

Ensuite, effectuez le scraping depuis Prometheus ou tout collecteur compatible :

Métriques du serveur

Métriques de requêtes

Histogramme de durée de requête

Limites des buckets (microsecondes) : 100, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000, 250000, 500000, 1000000, +Inf.

Utilisez cet histogramme pour suivre la latence globale, identifier les endpoints lents et mesurer les percentiles de latence de queue.

Métriques de connexion

Lire la profondeur de file face aux places d'admission

Les deux jauges répondent à deux moitiés d'une même question : non pas quelle est la profondeur de la file, mais est-ce que quelque chose avance. oxphp_queue_depth indique ce qui attend ; oxphp_admission_slots_available indique si l'on peut encore laisser entrer quelque chose. Lisez les deux face à oxphp_busy_workers.

Les trois dernières lignes sont les formes que prend un pool bloqué. Dans chacune d'elles, le reste du tableau semble sain alors qu'aucune requête PHP ne se termine : aucun worker occupé, 200 de la sonde de vivacité tout du long et de la sonde de disponibilité pendant la première minute, fichiers statiques servis normalement. Les compteurs de refus bougent, mais ils bougent aussi sous une surcharge ordinaire. oxphp_pending_requests monte avec la file bloquée puis redescend à mesure que chaque arrivée reçoit sa réponse sur son propre budget ; pris isolément, il ne veut donc rien dire ici. Lu face à oxphp_queue_depth, si : des requêtes en attente proches de zéro alors que la profondeur reste à la capacité, c'est le blocage qui retient tout ce qu'on lui a jamais confié.

Le serveur remarque aussi un blocage. Chaque fois que deux analyses consécutives d'une seconde voient du travail en attente (des requêtes dans la file, ou des refus en hausse) avec au moins un worker inactif et un pool qui n'a rien terminé, il journalise :

Le message se répète environ une fois par minute tant que l'état dure, et INFO PHP pool is reaching workers again suit une fois que le travail reprend. Les champs se trouvent sous fields, donc une règle d'alerte doit viser .fields.queue_depth, et non .queue_depth. Trois garde-fous évitent les faux signalements : deux analyses plutôt qu'une ; une progression mesurée à ce que les workers ont terminé plutôt qu'à ce que les clients ont reçu, si bien qu'une avalanche d'abandons clients se lit comme le pool occupé qu'elle est ; et aucun signalement tant que le pool n'a pas terminé sa première requête, pour que l'amorçage au démarrage ne soit pas pris pour un blocage.

Ce dernier garde-fou ne couvre que le premier amorçage du processus. Un worker recyclé plus tard (sur le plafond mémoire ou via Worker::scheduleExit()) amorce à nouveau son application et apparaît inactif jusqu'à ce qu'il prenne sa première requête ; un amorçage lent sur un pool d'un seul worker (ou sur un pool plus grand dont tous les autres workers sont occupés) produit donc un avertissement intempestif suivi de son avis de rétablissement. Un oxphp_workers_spawned_total qui bouge au même moment permet de l'identifier.

L'avertissement n'est émis qu'en mode worker, puisque seul ce pool tient le compte de ce que les workers ont terminé ; l'état qu'il décrit ne peut pas se produire là où un worker se bloque lui-même sur la file. Les trois jauges sont exportées dans tous les modes.

Attentes gaspillées

oxphp_admission_wait_wasted_total compte le travail commencé plutôt que les entrées qui quittent la file, car un worker qui évacue des requêtes auxquelles leur échéance a déjà répondu fait bouger la file sans servir personne. Il est conditionné au fait que le budget soit à son plafond parce qu'une fois que le serveur a raccourci le budget, « le pool n'a rien commencé » en dit plus sur la fenêtre que sur le pool : un pool sain de quatre workers avec des gestionnaires d'un quart de seconde démarre une requête toutes les 62 ms, si bien qu'au plancher la plupart des attentes se terminent entre deux démarrages.

Ce que coûte cette condition dépend de si le budget bouge :

• Un pool qui ne démarre rien n'atteint jamais le nombre de requêtes démarrées sur lequel le contrôleur fonde sa décision ; il garde donc son plafond et ce compteur reste armé.
• Un pool qui s'appelle lui-même démarre une requête chaque fois qu'une requête externe renonce à son appel interne. Dès que ses propres appelants sont moins patients que ses gestionnaires, le budget baisse (mesuré : deux divisions par deux en quelques secondes), et ce compteur se tait après les arrivées antérieures à la baisse. Rien sur cette page ne prend le relais à ce stade : cherchez le motif dans les appels sortants de l'application elle-même. Là où les appelants sont patients (un cron interne, un sidecar avec un délai généreux), rien n'est abandonné, le plafond tient, et c'est ce compteur qui le révèle.

La cause classique est une application qui rappelle ce même serveur en HTTP, mais le compteur n'est pas un détecteur d'auto-appel : un pool dont tous les gestionnaires durent plus longtemps que le budget ne libère rien pendant une attente non plus. En mode worker, oxphp_worker_request_duration_us (temps du gestionnaire, attente en file exclue) les distingue : des gestionnaires en dessous du budget pendant que ce compteur augmente signifient que les attentes ne sont pas simplement en file derrière du travail lent. N'utilisez pas oxphp_request_duration_us pour cela : elle inclut ces refus, chacun contribuant presque un budget entier. Hors mode worker, utilisez les mesures de temps propres à l'application.

QUEUE_WAIT_TIMEOUT_MS=0 n'est pas la version la plus courte d'un budget raccourci : il supprime l'attente d'une place dans la file et laisse l'attente dans la file sans limite, si bien que sur un pool qui ne prend rien en charge, une requête qui trouve une place libre ne reçoit jamais de réponse. Associez 0 à un QUEUE_CAPACITY assez petit pour que la file soit pleine au moment où cela compte.

Ce que dit le journal pendant le délestage des requêtes

Le superviseur surveille les quatre raisons de surcharge de oxphp_admission_refused_total lors de la même analyse d'une seconde et signale l'épisode plutôt que les requêtes individuelles, car une ligne par refus serait elle-même la panne. La première analyse qui voit l'une d'elles bouger journalise :

refused correspond à ce que cette analyse-là a refoulé, sauf lors de la première analyse qui a une file à examiner, qui signale tout ce qui a été délesté avant elle (un pool encore en train de charger son application pendant que les arrivées s'accumulent constitue un véritable épisode). Une profondeur à la capacité sans aucune place libre, c'est un pool en retard sur son travail, et un wait_budget_us bien inférieur à wait_budget_ceiling_us indique que le serveur a déjà raccourci l'attente ; les deux nombres sont présents parce qu'un budget poussé à son plancher et un budget configuré aussi bas se ressemblent pris isolément. Les chiffres de la file sont un instantané pris lors de l'analyse, tandis que refused couvre la seconde qui vient de s'écouler ; un refused élevé à côté d'une file vide est donc une rafale brève, pas une contradiction.

Les deux comptes sont ventilés par raison, selon les quatre labels de surcharge de oxphp_admission_refused_total, avec des noms de champs construits à partir du compte qu'ils décomposent : refused_queue_full, refused_wait_timeout, refused_waiting_full et refused_waiting_bytes ont pour somme refused, et la répétition comme la ligne de clôture ci-dessous portent episode_refused_queue_full et ses trois pendants, dont la somme est episode_refused. C'est la raison qui détermine le réglage à ajuster (la ligne du compteur ci-dessus indique ce que chacune désigne), et ce compteur n'est servi que sur INTERNAL_ADDR. Sur une instance sans écouteur interne, ces champs et l'attribut de span oxphp.shed_reason, là où le traçage est actif, sont les endroits où la raison reste lisible. Les quatre sont écrits même à zéro : un 0 explicite est ce qui permet d'écarter une raison.

Tant que l'épisode dure, l'avertissement se répète sous la forme PHP admission is still shedding requests under overload, pas plus d'une fois par minute et uniquement lors d'une analyse qui refuse elle-même des requêtes (l'intervalle peut donc atteindre presque deux minutes), avec episode_refused (le total cumulé) à côté du refused par analyse. Ce que la répétition ventile par raison, c'est le total de l'épisode, pas celui de l'analyse. C'est important parce que la ligne de clôture est écrite au niveau INFO, en dessous du warn auquel journalisent les configurations de production : là, la répétition est la seule ligne qui dit de quoi l'épisode a été fait jusqu'ici, jusqu'à l'analyse lors de laquelle elle a été écrite. Un épisode qui se termine dans sa première minute n'a aucune répétition, et ce qui est refusé après la dernière répétition n'apparaît que dans la ligne de clôture. Une minute sans aucun refus met fin à l'épisode, au niveau INFO :

duration_ms va jusqu'au dernier refus, pas jusqu'à la ligne, si bien que la minute calme de clôture n'est pas comptée. Cette minute calme signifie aussi que les interruptions de moins d'une minute sont regroupées en un seul épisode, ce qui limite la sortie à deux lignes par minute au pire ; l'entrée dans l'épisode n'a pas ce délai, puisqu'un refus est un fait et non un échantillon.

Le signalement est émis dans tous les modes de routage et ne réagit qu'aux quatre raisons de surcharge, si bien qu'un redémarrage (shutting_down) ou un pool disparu (pool_unavailable) ne s'annonce pas comme de la charge. Il n'existe aucune jauge pour cet état, et aucune sonde n'en est informée : le délestage ne change jamais ce que répond /health/readiness, car une instance qui déleste des 529 répond rapidement sur un pool qui fonctionne, et retirer tour à tour de la rotation chaque réplique surchargée laisserait le Service sans aucun endpoint. Répondez à la surcharge en ajoutant de la capacité. Un pool bloqué déleste lui aussi, et en mode worker cet état-là répond bien 503 une fois qu'il a duré une minute. La file distingue les deux : un pool simplement en retard la vide, un pool bloqué non.

Métriques du pool de workers

Métriques du superviseur de workers

Observabilité par worker émise par le superviseur de workers. Chaque série porte un label worker_id (index de slot). Ces métriques apparaissent une fois que le superviseur suit l'état de chaque worker.

Histogramme d'attente en file

Limites des buckets (microsecondes) : 50, 100, 250, 500, 1000, 2500, 5000, 10000, 50000, 100000, 250000, 500000, 1000000, +Inf.

Ceci mesure le temps passé à attendre, pour l'admission puis dans la file, jusqu'au moment où un worker retire la requête de la file, si bien qu'il répond à « combien de temps avant qu'un worker ne prenne cette requête » plutôt qu'à « combien de temps la requête a-t-elle pris ». Rien de ce qui suit ce moment n'y figure : la préparation de la requête par le worker, le script (jusqu'à l'en-tête de la réponse, pour une réponse en flux) et la remise de la réponse aux threads d'E/S du serveur comptent tous dans oxphp_request_duration_us. Cette remise n'est pas gratuite : la réponse attend qu'un thread d'E/S soit réveillé ou vienne à bout du travail en file devant elle, si bien que, sur un script peu coûteux, le temps écoulé après cette attente peut représenter plusieurs fois celui du script lui-même.

Seule une requête qu'un worker a retirée de la file dans les limites de son budget est enregistrée ici. Un 529 refusé pour surcharge, ou un 503/500 lorsque le serveur s'arrête ou que le pool a disparu, est compté dans oxphp_admission_refused_total ; un 499 pour un client parti avant qu'un worker ne l'atteigne est compté dans oxphp_request_cancelled_total{reason="client_abort"} et dans aucune série de refus.

Une attente en file élevée signifie que les requêtes ont mis longtemps à atteindre un worker, ce qui n'est pas en soi un manque de workers : chaque mesure inclut le temps qu'il faut à un thread worker pour arriver à une requête qui lui a été remise, et ce temps existe aussi sur un serveur sans charge. Avant d'augmenter PHP_WORKERS, vérifiez que les requêtes trouvent tous les workers occupés et que la machine a des cœurs disponibles : les threads d'E/S du serveur lui-même, d'autres processus et un quota CPU de conteneur sont en concurrence avec les workers. oxphp_busy_workers face à oxphp_workers_current ne répond qu'en partie à la première question : cette valeur est lue au moment du scraping, donc une rafale qui remplit le pool entre deux scrapings apparaît ici et pas là, et en mode worker un thread compte comme occupé tant qu'il porte une requête, même pendant que le gestionnaire de cette requête est suspendu et que le thread en prend d'autres. La plage atteint une seconde, en accord avec le QUEUE_WAIT_TIMEOUT_MS par défaut, si bien qu'une requête qui a dépensé l'essentiel de son budget d'attente avant de s'exécuter est quantifiée plutôt que reléguée dans +Inf. Rien de ce qui est servi n'attend plus longtemps que le budget (au-delà, la requête est refusée), donc relever QUEUE_WAIT_TIMEOUT_MS est le seul réglage qui renvoie des attentes dans +Inf.

Métriques de limitation de débit

Métriques du cache de fichiers statiques

Métriques de compression

Métriques du mode worker

Ces métriques ne sont émises que lorsque le mode worker est actif (WORKER_MODE_ENABLED=true).

Compteurs globaux

Jauges par worker

Histogramme de durée de requête des workers

Limites des buckets (microsecondes) : 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, +Inf.

Cet histogramme mesure le temps passé à l'intérieur du callback du gestionnaire PHP, hors temps d'attente en file. Utilisez-le pour identifier les gestionnaires lents et suivre la latence de queue en mode worker.

Métriques du pool asynchrone

Ces métriques nécessitent que ASYNC_WORKERS soit défini à une valeur non nulle, et chacune possède sa propre condition d'émission : les compteurs n'apparaissent qu'après qu'au moins une tâche a été distribuée ou rejetée, les jauges _in_flight / _in_flight_limit apparaissent une fois que le pool a câblé son compteur de tâches en cours, et oxphp_async_output_discarded_bytes_total n'apparaît qu'après que de la sortie a été rejetée.

Métriques d'export OpenTelemetry

Ces métriques nécessitent OTEL_ENABLED=true. Elles comptent les lots de spans qu'OxPHP envoie au collecteur OTLP : les spans de requête, plus les spans APM lorsque le plugin APM est actif.

Un export est retenté une fois lorsque sa première tentative échoue sans réponse du collecteur dans la moitié de OTEL_EXPORTER_OTLP_TIMEOUT ou dans une seconde, selon la durée la plus courte : la connexion a été réinitialisée ou fermée, ou n'a pas pu être établie. La cause habituelle est un répartiteur de charge ou un NAT qui a coupé la connexion pendant qu'elle était inactive entre deux exports. Un statut d'erreur renvoyé par le collecteur, comme une clé d'API rejetée ou une limitation de débit, n'est pas retenté : la spécification OTLP interdit de retenter la plupart d'entre eux, et l'exportateur ne transmet pas le délai que demande un collecteur qui limite le débit. Une nouvelle tentative qui livre le lot n'est comptée que dans oxphp_otel_export_retries_total. Une tentative qui atteint le délai d'expiration de l'export n'est pas retentée ; un collecteur lent ne reçoit donc jamais deux fois le même lot.

La nouvelle tentative peut toutefois dupliquer. Lorsque le collecteur a bien reçu la première tentative avant que la connexion ne se rompe, la nouvelle tentative livre ces spans une seconde fois, et pour la même raison un export compté comme en échec peut tout de même avoir atteint le collecteur.

Les spans que le traceur abandonne avant l'export parce que sa file est pleine (OTEL_BSP_MAX_QUEUE_SIZE, 2048 spans par défaut) ne sont pas comptés ici.

Conseils pour tableau de bord Grafana

Les requêtes PromQL suivantes sont utiles pour construire des tableaux de bord :

Taux de requêtes (requêtes par seconde) :

Temps de réponse moyen (millisecondes) :

Durée de requête p99 (millisecondes) :

Taux d'erreur (réponses 5xx en pourcentage) :

Utilisation du pool de workers :

C'est une vraie fraction entre 0 et 1. Des valeurs soutenues à 1 signifient que chaque worker est occupé et que les arrivées supplémentaires font la queue. Associez-la à rate(oxphp_admission_refused_total{reason=~"queue_full|wait_timeout|waiting_full|waiting_bytes"}[5m]) pour voir si cet arriéré se transforme en refus, et à oxphp_pending_requests pour en mesurer la profondeur.

Saturation de la file (taux d'abandon par seconde) :

Attente en file p99 (microsecondes) :

Taux de succès du cache de fichiers statiques :

Octets économisés par la compression par seconde :

Latence p99 en mode worker (microsecondes) :

Budget d'attente poussé sous son plafond (fraction) :

1 est normal ; toute valeur inférieure signifie que le serveur raccourcit les attentes sous surcharge. Alertez sur le ratio plutôt que sur un nombre recopié de QUEUE_WAIT_TIMEOUT_MS.

Blocages de la boucle d'acceptation (alerter si non nul) :

Taux de recyclage des workers (par minute) :

Utilisation mémoire moyenne des workers :

Configuration de scraping Prometheus

Ajoutez un job de scraping à votre prometheus.yml :

Pour la découverte de services Kubernetes :

Prompts pour votre agent

Ces prompts supposent un agent connecté au serveur MCP de la documentation OxPHP — il lira lui-même les pages dont il a besoin.

Voir aussi

• Contrôles de santé — les endpoints /health et /config sur le serveur interne
• Référence de configuration — toutes les variables d'environnement, y compris INTERNAL_ADDR
• Arrêt gracieux — comment le drainage des connexions affecte oxphp_active_connections
• Mode worker — les workers persistants et les métriques qu'ils émettent