Observabilité Next.js / Drupal : tracing, logs et budgets d'erreur

Un incident en production sur une architecture découplée Next.js / Drupal suit presque toujours le même scénario : l'équipe front signale une page blanche ou une latence anormale, l'équipe CMS répond que l'API Drupal est verte, et chacun regarde ses propres tableaux de bord. Sans couche d'observabilité partagée, le diagnostic tourne au jeu de ping-pong. L'incident dure plus longtemps qu'il ne le devrait — et les régressions se répètent faute de priorisation claire.

Pourquoi l'observabilité partagée change tout dans une stack découplée

Dans un monolithe, une requête traverse une seule application, un seul système de logs, un seul point d'observation. Dans une architecture headless — Next.js en front, Drupal en CMS headless, API JSON:API ou GraphQL entre les deux — la même requête traversera au minimum deux runtimes, deux couches réseau, parfois un CDN, un service de revalidation ISR, et plusieurs webhooks.

Chaque couche produit ses propres logs, dans ses propres formats, sans référence commune. Quand quelque chose casse, retrouver la requête incriminée demande de croiser manuellement des timestamps approximatifs dans des outils différents. L'observabilité partagée consiste à instrumenter les deux systèmes de façon à ce qu'une requête soit traçable de bout en bout — de la navigation utilisateur dans Next.js jusqu'à la réponse de Drupal — avec les mêmes identifiants et une vue unifiée.

Étape 1 — Corréler requêtes et réponses avec un trace ID commun

Chaque requête émise par Next.js vers l'API Drupal doit transporter un identifiant de traçage unique (un trace-id) dans ses en-têtes HTTP. Drupal doit lire cet identifiant, le journaliser dans ses propres logs, et le renvoyer dans la réponse.

En pratique, cela s'implémente avec OpenTelemetry, le standard ouvert de l'industrie pour le traçage distribué. Next.js supporte OpenTelemetry nativement depuis la version 13.4 via son instrumentation hook (instrumentation.ts). Drupal, côté PHP, dispose du SDK OpenTelemetry pour PHP, intégrable dans un service custom.

Le résultat : un trace-id commun apparaît dans les logs Next.js et dans les logs Drupal. Une requête qui aboutit à une erreur HTTP 500 peut être retrouvée en quelques minutes dans les deux systèmes, avec la chaîne d'appels complète.

Étape 2 — Tracer les appels critiques : API JSON, webhooks et ISR

Les appels API JSON:API / GraphQL sont le flux principal. Chaque span OpenTelemetry doit capturer le type de requête, l'entité Drupal ciblée, le temps de réponse, et le statut HTTP. Un seuil d'alerte sur la latence médiane permet de détecter une dégradation Drupal avant qu'elle devienne visible côté utilisateur.

Les webhooks constituent le flux inverse : Drupal notifie Next.js lors de la publication d'un contenu, déclenchant une revalidation. Un webhook échoué silencieusement entraîne des pages périmées sans erreur visible. Instrumenter les webhooks côté Drupal (émission) et côté Next.js (réception + résultat de revalidation) ferme cette zone aveugle.

L'ISR (Incremental Static Regeneration) introduit une complexité supplémentaire : tracer les revalidations ISR — tentative, succès, durée — permet de comprendre si une page affiche du contenu ancien parce que l'ISR fonctionne normalement ou parce que la revalidation échoue en boucle.

Étape 3 — Définir des SLO pertinents pour une stack découplée

Dans une architecture Next.js / Drupal, les SLO doivent couvrir au moins trois périmètres distincts :

• Le SLO de disponibilité de l'API Drupal : proportion de requêtes auxquelles Drupal répond avec succès dans un intervalle donné.
• Le SLO de latence des pages Next.js : temps de réponse des pages SSR ou ISR, distinct du SLO API car il inclut le temps de rendu Next.js et la logique applicative du front.
• Le SLO de fraîcheur du contenu : délai entre la publication dans Drupal et la disponibilité effective du contenu mis à jour dans Next.js. Un délai systématiquement hors cible indique un problème dans la chaîne webhook → revalidation ISR.

Fixer ces objectifs est un acte éditorial autant que technique : ils doivent refléter ce que les utilisateurs et le métier considèrent comme acceptable.

Étape 4 — Instaurer des budgets d'erreur pour prioriser sans débat

Un budget d'erreur est le complément du SLO : si un SLO fixe la disponibilité cible à 99,5 %, le budget d'erreur est le volume de défaillances autorisé avant de dépasser ce seuil sur une période donnée.

L'intérêt opérationnel est direct : le budget d'erreur transforme une discussion subjective (« faut-il prioriser ce bug ou cette feature ? ») en décision objective. Si le budget est intact, l'équipe peut engager des déploiements risqués ou des expérimentations. Si le budget est consommé, toute l'énergie va à la stabilisation.

Dans une architecture bicéphale Next.js / Drupal, chaque couche dispose de son propre budget, mais les deux sont visibles dans le même tableau de bord. Quand les deux budgets baissent simultanément, c'est le signal d'un problème systémique — pas un incident isolé dans l'une des deux couches.

L'outillage courant : Prometheus pour collecter les métriques, Grafana pour visualiser les SLO et les budgets, et les recording rules Prometheus pour calculer les fenêtres glissantes.

Ce que l'observabilité partagée change réellement

Une fois les quatre étapes en place, le changement le plus visible n'est pas technique. C'est organisationnel. Les équipes front et CMS cessent de se renvoyer les incidents parce qu'elles regardent les mêmes données. La priorisation devient factuelle : le budget d'erreur dit si l'urgence est réelle ou gérée. Les régressions diminuent non pas parce que le code devient parfait, mais parce que les signaux faibles — latences qui dérivent, webhooks qui échouent silencieusement, revalidations ISR qui stagnent — sont détectés avant de devenir des incidents.

Ce que DrupaLabs met en place

Chez DrupaLabs, l'observabilité n'est pas une option ajoutée après la livraison. Nous l'intégrons dans l'architecture dès la phase de cadrage : instrumentation OpenTelemetry, définition des SLO avec les équipes métier, mise en place des budgets d'erreur et des alertes associées.

Tout commence par un diagnostic : nous analysons votre stack, identifions les zones aveugles, et proposons un plan d'instrumentation adapté à votre niveau de maturité et à vos contraintes d'infrastructure.