# OpenTelemetry pour WordPress : tracer une requête de bout en bout

> Instrumenter PHP et WordPress avec OpenTelemetry, exporter les traces vers un collecteur, et relier ce qui se passe côté front, côté PHP et côté base en une seule vue.

- Auteur : Clément Hadrot
- Publié le : 2026-08-21
- Mis à jour le : 2026-08-21
- Catégorie : Outils & workflow
- URL : https://wpmoderne.dev.wordpress-developpement.fr/outils/opentelemetry-wordpress-tracer-requete/

## L’essentiel

- Une trace relie front, hooks WordPress et requêtes SQL en une chronologie
- L'extension PHP OpenTelemetry s'installe via PECL ou Composer
- Le collecteur reste l'étape souvent sous-estimée de la mise en place

Un site client signalait des lenteurs intermittentes, difficiles à isoler : certaines requêtes prenaient une seconde, d'autres cinq, sans schéma évident. Les outils classiques (journal d'erreurs PHP, `wp profile`) montraient bien un ralentissement, mais sans permettre de relier ce qui se passait côté navigateur, côté PHP et côté base de données dans une même chronologie. C'est exactement le problème qu'OpenTelemetry est conçu pour résoudre : donner à chaque requête un identifiant de trace unique, propagé d'un système à l'autre, pour reconstituer après coup son parcours complet.

OpenTelemetry n'est pas un outil de monitoring en soi, mais un standard ouvert et une collection d'instrumentations qui génèrent des données de traces, de métriques et de journaux dans un format commun, exploitables ensuite par n'importe quel outil compatible (Jaeger, Grafana Tempo, ou une plateforme commerciale d'observabilité).

## Les trois composants à mettre en place

1. L'instrumentation PHP, qui génère les données de trace au niveau du code exécuté par WordPress ;
2. Le collecteur OpenTelemetry, un processus intermédiaire qui reçoit les traces envoyées par PHP et les relaie vers un système de stockage ;
3. Le système de visualisation, qui affiche les traces sous forme de chronologie exploitable.

## Installer l'extension PHP

L'instrumentation automatique de PHP repose sur l'extension native `opentelemetry`, installable via PECL, complétée par les paquets Composer qui fournissent le SDK et les exportateurs :

```
pecl install opentelemetry
echo "extension=opentelemetry.so" >> /etc/php/8.3/fpm/php.ini

composer require open-telemetry/sdk open-telemetry/exporter-otlp
composer require open-telemetry/opentelemetry-auto-wordpress
```

Le paquet d'auto-instrumentation pour WordPress ajoute automatiquement des segments de trace (*spans*) autour des étapes clés du cycle de chargement — résolution de la requête principale, exécution des hooks majeurs — sans qu'il soit nécessaire de modifier le code du thème ou des extensions.

> L'essentiel à retenir : Une trace relie front, hooks WordPress et requêtes SQL en une chronologie ; L'extension PHP OpenTelemetry s'installe via PECL ou Composer ; Le collecteur reste l'étape souvent sous-estimée de la mise en place

## Ajouter des segments personnalisés autour d'un hook lent

Pour un diagnostic plus fin, on peut ajouter manuellement un segment de trace autour d'une portion de code suspectée, en s'appuyant sur l'API du SDK :

```
add_action( 'pre_get_posts', function ( $query ) {
    $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer( 'wp-moderne' );
    $span   = $tracer->spanBuilder( 'filtrer-requete-recommandations' )->startSpan();
    $portee = $span->activate();

    try {
        // logique métier existante du filtre
    } finally {
        $span->end();
        $portee->detach();
    }
} );
```

Ce segment apparaîtra dans la trace complète avec son propre temps d'exécution, imbriqué sous le segment plus large correspondant au hook `pre_get_posts`, ce qui permet de voir immédiatement s'il représente une part disproportionnée du temps total de la requête.

## Le collecteur : l'étape sous-estimée

Envoyer les traces directement depuis PHP vers une plateforme d'observabilité distante fonctionne, mais expose chaque requête WordPress à la latence et à la disponibilité de ce service distant. La pratique recommandée consiste à déployer un collecteur OpenTelemetry local, sur le même serveur ou à proximité, qui reçoit les traces en local puis les relaie de façon asynchrone et avec nouvelles tentatives en cas d'échec :

```
# variables d'environnement PHP, à définir dans la configuration du pool PHP-FPM
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=site-client-atelier
OTEL_TRACES_EXPORTER=otlp
```

Le collecteur lui-même se configure séparément (fichier `otel-collector-config.yaml`), avec un récepteur OTLP en entrée et un exportateur vers le système de stockage choisi en sortie.

## Relier le front, PHP et la base en une seule vue

La propriété la plus utile d'OpenTelemetry apparaît quand la propagation du contexte de trace traverse plusieurs systèmes : un en-tête HTTP `traceparent`, envoyé par le navigateur si le front est lui-même instrumenté, se propage jusqu'à PHP, qui à son tour propage ce même identifiant aux requêtes SQL exécutées via `$wpdb` si l'instrumentation de la base de données est activée. Le résultat : une seule chronologie visuelle qui montre, pour une requête donnée, le temps passé côté réseau, côté PHP et côté base, plutôt que trois journaux séparés à recouper manuellement.

> La première fois qu'on voit une trace complète relier un clic navigateur à une requête SQL précise, cinq couches plus bas, on comprend pourquoi les journaux d'erreurs classiques ne suffisaient plus sur les architectures les plus complexes de notre parc.

## Ce qu'il faut garder en tête avant de généraliser

- L'instrumentation ajoute un surcoût de performance mesurable, généralement faible mais non nul, qu'il vaut mieux quantifier avant de l'activer sur cent pour cent du trafic en production ;
- L'échantillonnage des traces (n'enregistrer qu'une fraction des requêtes) devient rapidement nécessaire sur un site à fort trafic, sous peine de générer un volume de données ingérable ;
- OpenTelemetry ne remplace pas un outil de monitoring d'uptime : il complète le diagnostic une fois qu'un problème de performance a déjà été détecté par ailleurs.

## Pour aller plus loin

La mise en place complète — extension PHP, collecteur, système de visualisation — demande un investissement initial réel, à réserver aux projets où les outils de diagnostic plus simples (journaux, `wp profile`) ont atteint leurs limites. Sur un site aux architectures multiples et interconnectées, ce standard finit néanmoins par devenir le seul moyen fiable de comprendre où le temps disparaît réellement.