Sentry front et WordPress : relier une erreur React à sa requête

« Sentry captures errors, but also gives you the context needed to identify the cause of the error » — la documentation officielle de Sentry pose bien l’ambition de l’outil. Mais sur un front React consommant WPGraphQL, ce contexte s’arrête par défaut à la frontière du navigateur : Sentry connaît le composant qui a levé l’exception, pas la requête GraphQL dont la réponse a provoqué ce composant à planter.

Ce guide part de ce constat pour construire, étape par étape, la propagation d’un identifiant de trace entre le front React et l’API WPGraphQL, afin qu’une seule recherche dans Sentry retrouve les deux moitiés d’un même incident. Il suppose Sentry déjà installé des deux côtés : son installation initiale n’est pas traitée ici.

Pourquoi une requête GraphQL complique la corrélation

Contrairement à une route REST, une requête WPGraphQL passe presque toujours par un unique point d’entrée HTTP (/graphql), quel que soit le contenu réellement demandé. Sans effort supplémentaire, tous les événements Sentry côté serveur se ressemblent : même URL, même méthode HTTP, seule la charge utile de la requête change. Il devient impossible de distinguer, dans le tableau de bord Sentry, l’erreur provoquée par une requête de menu de celle provoquée par une requête d’article.

Le correctif consiste à extraire, pour chaque requête, le nom de l’opération GraphQL envoyée par le front — une information que le client Apollo ou urql transmet déjà, mais que Sentry n’exploite pas automatiquement.

Les étapes

1. Générer un identifiant de trace unique côté React à chaque requête GraphQL, via crypto.randomUUID().
2. Ajouter cet identifiant en en-tête HTTP personnalisé sur chaque appel vers /graphql.
3. Extraire, côté WordPress, le nom de l’opération GraphQL et l’identifiant de trace reçu, via le hook graphql_request_data.
4. Configurer un scope Sentry côté serveur avec ces deux informations avant l’exécution de la requête.
5. Configurer le même identifiant de trace côté React, dans le contexte Sentry attaché à toute erreur de rendu.

Côté React : attacher l’identifiant à chaque appel

import * as Sentry from '@sentry/react';

function withTraceHeader(operationName) {
  const traceId = crypto.randomUUID();
  Sentry.setContext('graphql_operation', {
    name: operationName,
    trace_id: traceId,
  });
  return { 'X-Trace-Id': traceId, 'X-Operation-Name': operationName };
}

const link = new HttpLink({
  uri: process.env.WPGRAPHQL_ENDPOINT,
  fetch: (uri, options) => {
    const operationName = JSON.parse(options.body).operationName;
    return fetch(uri, {
      ...options,
      headers: {
        ...options.headers,
        ...withTraceHeader(operationName),
      },
    });
  },
});

Côté WordPress : lire et exploiter la trace

WPGraphQL expose un hook dédié, graphql_request_data, exécuté avant le traitement de chaque requête, qui donne accès à la requête HTTP entrante :

add_filter('graphql_request_data', function ($request_data) {
    $trace_id       = $_SERVER['HTTP_X_TRACE_ID'] ?? null;
    $operation_name = $_SERVER['HTTP_X_OPERATION_NAME'] ?? $request_data['operationName'] ?? 'anonyme';

    if ($trace_id && function_exists('Sentry\configureScope')) {
        \Sentry\configureScope(function ($scope) use ($trace_id, $operation_name) {
            $scope->setTag('trace_id', $trace_id);
            $scope->setTag('graphql_operation', $operation_name);
        });
    }

    return $request_data;
});

Toute exception levée pendant la résolution de la requête GraphQL — un resolver personnalisé qui échoue, une erreur de base de données — hérite désormais de ces deux tags, ce qui permet de filtrer par graphql_operation:GetArticleBySlug pour isoler un type de requête précis, ou par trace_id pour retrouver un incident spécifique signalé par un utilisateur.

Retrouver la paire d’événements

Une fois la requête React échouée capturée par Sentry côté client, la recherche trace_id:<valeur> dans le projet Sentry côté serveur fait remonter l’événement correspondant, avec la trace PHP complète de l’erreur — souvent bien plus parlante qu’un simple message d’échec de requête vu depuis le navigateur.

• L’identifiant de trace ne remplace pas un système de tracing distribué complet (type OpenTelemetry), mais couvre le besoin pour la plupart des projets de taille moyenne.
• Le nom d’opération GraphQL, seul, suffit déjà à grouper les erreurs par type de requête dans le tableau de bord Sentry.
• Cette mise en place ne dépend d’aucun plugin Sentry spécifique à GraphQL : elle repose uniquement sur des hooks WPGraphQL standards.

Le nom d’une opération GraphQL, transmis par le client dès sa création, est une information gratuite trop souvent perdue en route. L’exploiter côté serveur ne coûte qu’un hook.

En résumé

Un identifiant de trace et le nom de l’opération GraphQL suffisent à transformer un tableau de bord Sentry uniforme, où toutes les requêtes se ressemblent, en un outil de diagnostic réellement exploitable côté WPGraphQL. Cette mise en place se fait en quelques dizaines de lignes, sans dépendance supplémentaire ni modification de la configuration initiale de Sentry.