Documentation

Conserver X-Correlation-Id dans les réponses d’erreur AEMaaCS (404/500)

Last update: Thu Nov 13 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Dans Adobe Experience Manager as a Cloud Service, vous utilisez l’en-tête X-Correlation-Id pour suivre les requêtes sur les couches AEM, Dispatcher et CDN. Bien que cet en-tête apparaisse dans les réponses réussies (200 OK), il est manquant dans les réponses d’erreur telles que 404 Introuvable ou 500 Erreur de serveur interne, même si les journaux AEM confirment qu’il a été défini. Par défaut, le réseau CDN remplace les réponses d’erreur AEM par des pages synthétiques, ce qui supprime les en-têtes personnalisés. Cela interrompt les workflows de surveillance et de débogage, ce qui rend difficile la corrélation des échecs côté client avec les journaux du serveur principal.

Pour corriger ce problème, ajoutez l’en-tête x-aem-error-pass: true aux réponses d’erreur. Cela indique au réseau CDN de transférer la réponse AEM d’origine au lieu de générer une page d’erreur synthétique, en s’assurant que l’en-tête X-Correlation-Id est conservé dans tous les types de réponse.

Description description

Environnement

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • Configurations du réseau CDN à l’aide de responseTransformations
  • Contexte : lors de l’implémentation d’identifiants de corrélation ou de mécanismes de suivi sur AEM, Dispatcher et le réseau CDN

Problème/Symptômes

  • X-Correlation-Id en-tête est présent dans les réponses 200 OK, mais il est manquant dans les réponses 404 ou 500.
  • Les journaux AEM affichent que l’en-tête est défini, mais il n’atteint pas le navigateur ou le client d’API. Remarqué lors de la validation du suivi des requêtes ou du comportement de débogage à l’aide de cURL, Postman ou des developer tools de navigateur.
  • Les systèmes de surveillance ne parviennent pas à suivre les transactions ayant échoué en raison d’en-têtes de corrélation manquants.
  • Les configurations CDN semblent supprimer les en-têtes dans les réponses d’erreur.

Résolution resolution

Pour permettre à la réponse d’erreur d’origine d’AEM et à ses en-têtes d’atteindre le client :

  • Configurez votre gestionnaire d’erreurs AEM pour inclure le x-aem-error-pass: true d’en-tête dans les réponses d’erreur.

  • Cette instruction indique au réseau CDN de contourner la génération de page d’erreur synthétique et de transférer la réponse AEM ou Dispatcher d’origine (y compris ses en-têtes) directement au client.

  • Après avoir appliqué cette modification :

    • L’en-tête X-Correlation-Id s’affiche dans les réponses réussies et en échec.
    • Les outils de surveillance côté client peuvent suivre avec précision le cycle de vie complet des requêtes.

Remarques complémentaires :

  • Sécurité et conformité : assurez-vous que les payloads d’erreur ne présentent pas de détails internes sensibles avant d’activer cet en-tête en production.
  • Portée : ce comportement s’applique uniquement aux réponses générées par AEM ou Dispatcher. Les erreurs au niveau du réseau CDN diffusent toujours des pages synthétiques.
  • Malentendu courant : responseTransformations ne pouvez pas réinjecter des en-têtes dans les réponses d’erreur de synthèse.
  • Conseil de test : utilisez curl -i -v ou les outils de développement du navigateur pour vérifier la présence de l’en-tête avant et après l’application du correctif. Par exemple : -i -v https:///path-that-triggers-error

Recommandations relatives aux bonnes pratiques :

  • Générez et définissez toujours un identifiant de corrélation dans les requêtes du serveur principal.
  • Incluez le même ID dans les journaux et les en-têtes.
  • Utilisez des x-aem-error-pass: true pour les réponses d’erreur qui nécessitent une traçabilité complète, en particulier lors du débogage ou des tests d’intégration.
  • Limitez l’utilisation en production aux scénarios contrôlés afin d’éviter de remplacer le traitement d’erreur standard du réseau CDN.

Lecture connexe

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f