Surveillance des applications PHP avec Prometheus : la bibliothèque promphp/prometheus_client_php

Métriques Prometheus en PHP : guide complet de la bibliothèque promphp/prometheus_client_php

\n\n

Prometheus est la norme de facto pour la collecte de métriques dans l'infrastructure DevOps moderne. Si votre application backend est écrite en PHP, vous avez besoin d'un outil capable d'exporter des métriques dans un format compréhensible par le serveur Prometheus. La bibliothèque promphp/prometheus_client_php est la solution la plus mature et la mieux maintenue pour cette tâche. Dans cet article, nous verrons comment installer la bibliothèque, créer des métriques de base (compteurs, histogrammes, Summary) et les exposer sur un endpoint /metrics.

\n\n

Qu'est-ce que promphp/prometheus_client_php ?

\n\n

Il s'agit du client PHP officiel pour Prometheus, développé par la communauté promphp. La bibliothèque prend en charge :

\n

\n
• Quatre types de métriques principaux : Counter (compteur), Gauge (jauge), Histogram (histogramme), Summary (quantiles).
\n
• Des adaptateurs de stockage : en mémoire (pour les tests), dans Redis, APCu ou le système de fichiers.
\n
• Le formatage de la sortie au format texte Prometheus (text/plain).
\n
• La prise en charge des étiquettes (labels) pour les données multidimensionnelles.
\n

\n\n

Installation

\n\n

L'installation se fait via Composer. Ouvrez un terminal à la racine de votre projet et exécutez :

\n

composer require promphp/prometheus_client_php

\n\n

Après l'installation, incluez l'autoloader de Composer dans votre script PHP :

\n

require __DIR__ . '/vendor/autoload.php';

\n\n

Création d'un registre de métriques et d'un adaptateur de stockage

\n\n

La première étape consiste à créer un objet Registry (registre) qui contiendra toutes les métriques, et à choisir un adaptateur de stockage. Pour simplifier, utilisons un adaptateur en mémoire (les données ne vivent que pendant une seule requête). Pour la production, on utilise souvent Redis ou APCu.

\n\n

use Prometheus\\CollectorRegistry;\nuse Prometheus\\Storage\\InMemory;\n\n$registry = new CollectorRegistry(new InMemory());

\n\n

Exemple 1 : Counter — compter le nombre de requêtes

\n\n

Un compteur (Counter) est une valeur qui augmente de manière monotone. Idéal pour compter les requêtes HTTP, les erreurs, les accès à la base de données.

\n\n

// Récupère ou crée un compteur\n$counter = $registry->getOrRegisterCounter(\n    'my_app',           // namespace\n    'http_requests_total', // nom de la métrique\n    'Total number of HTTP requests', // description help\n    ['method', 'endpoint'] // étiquettes (labels)\n);\n\n// Incrémente le compteur avec des étiquettes spécifiques\n$counter->incBy(1, ['GET', '/api/users']);

\n\n

Dans la sortie de /metrics, cela ressemblera à ceci :

\n

# HELP my_app_http_requests_total Total number of HTTP requests\n# TYPE my_app_http_requests_total counter\nmy_app_http_requests_total{method="GET",endpoint="/api/users"} 1

\n\n

Exemple 2 : Gauge — valeurs courantes (mémoire, connexions)

\n\n

Une Gauge peut aussi bien augmenter que diminuer. Elle est utilisée pour suivre l'état actuel : nombre de connexions actives, mémoire utilisée, file d'attente de tâches.

\n\n

use Prometheus\\Gauge;\n\n$gauge = $registry->getOrRegisterGauge(\n    'my_app',\n    'memory_usage_bytes',\n    'Current memory usage in bytes',\n    ['pool']\n);\n\n// Définit une valeur\n$gauge->set(memory_get_usage(true), ['main']);\n// Ou modifie par rapport à la valeur actuelle\n$gauge->inc(1024, ['main']);   // +1KB\n$gauge->dec(512, ['main']);    // -512B

\n\n

Exemple 3 : Histogram — distribution des valeurs (temps de réponse)

\n\n

Un histogramme regroupe les observations dans des compartiments (buckets) prédéfinis. Idéal pour mesurer le temps d'exécution des requêtes ou la taille des réponses.

\n\n

use Prometheus\\Histogram;\n\n$histogram = $registry->getOrRegisterHistogram(\n    'my_app',\n    'http_request_duration_seconds',\n    'Duration of HTTP requests in seconds',\n    ['method', 'endpoint'],\n    [0.1, 0.5, 1.0, 2.0, 5.0] // buckets