Dokumentation

X-Correlation-ID in AEMaaCS-Fehlerantworten beibehalten (404/500)

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

In Adobe Experience Manager as a Cloud Service verwenden Sie den X-Correlation-Id-Header, um Anfragen über AEM-, Dispatcher- und CDN-Ebenen hinweg nachzuverfolgen. Diese Kopfzeile erscheint zwar in erfolgreichen (200 OK) Antworten, fehlt jedoch in Fehlerantworten wie "404 Nicht gefunden oder "500 Interner Server-Fehler, obwohl AEM-Protokolle bestätigen, dass sie festgelegt wurde. Standardmäßig ersetzt CDN AEM-Fehlerantworten durch synthetische Seiten, wodurch benutzerdefinierte Kopfzeilen entfernt werden. Dadurch werden die Überwachungs- und Debugging-Workflows unterbrochen, was die Korrelation von Client-seitigen Fehlern mit Backend-Protokollen erschwert.

Um dies zu beheben, fügen Sie den x-aem-error-pass: true-Header zu Fehlerantworten hinzu. Dadurch wird das CDN angewiesen, die ursprüngliche AEM-Antwort weiterzuleiten, anstatt eine synthetische Fehlerseite zu generieren, wodurch sichergestellt wird, dass die X-Correlation-Id-Kopfzeile in allen Antworttypen beibehalten wird.

Beschreibung description

Umgebung

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • CDN-Konfigurationen mithilfe von responseTransformations
  • Kontext: Bei der Implementierung von Korrelations-IDs oder Tracking-Mechanismen in AEM, Dispatcher und CDN

Problem/Symptome

  • X-Correlation-Id Kopfzeile ist in 200 OK Antworten vorhanden, fehlt jedoch in Antworten vom Typ 404 oder 500.
  • In AEM-Protokollen wird angezeigt, dass die Kopfzeile festgelegt ist, aber nicht den Browser oder API-Client erreicht. Wird beim Überprüfen des Anforderungs-Trackings oder Debugging-Verhaltens mithilfe von cURL-, Postman- oder Browser-developer tools festgestellt.
  • Überwachungssysteme können fehlgeschlagene Transaktionen aufgrund fehlender Korrelationskopfzeilen nicht verfolgen.
  • CDN-Konfigurationen scheinen Kopfzeilen in Fehlerantworten zu unterdrücken.

Auflösung resolution

So erreichen die ursprüngliche Fehlerantwort von AEM und ihre Kopfzeilen den Client:

  • Konfigurieren Sie Ihren AEM-Fehler-Handler, um die x-aem-error-pass: true in Fehlerantworten aufzunehmen.

  • Dadurch wird das CDN angewiesen, die Erstellung synthetischer Fehlerseiten zu umgehen und die ursprüngliche AEM- oder Dispatcher-Antwort (einschließlich ihrer Kopfzeilen) direkt an den Client weiterzuleiten.

  • Nach Anwendung dieser Änderung:

    • Die X-Correlation-Id-Kopfzeile wird sowohl in erfolgreichen als auch in fehlgeschlagenen Antworten angezeigt.
    • Client-seitige Überwachungs-Tools können den gesamten Lebenszyklus von Anfragen präzise verfolgen.

Weitere Überlegungen:

  • Sicherheit und Compliance: Stellen Sie sicher, dass Fehler-Payloads keine sensiblen internen Details offen legen, bevor Sie diesen Header in der Produktion aktivieren.
  • Umfang: Dieses Verhalten gilt nur für Antworten, die von AEM oder Dispatcher generiert wurden. Fehler auf CDN-Ebene dienen weiterhin synthetischen Seiten.
  • Häufiges Missverständnis: responseTransformations können Kopfzeilen in synthetischen Fehlerantworten nicht erneut einfügen.
  • Test-Tipp: Verwenden Sie curl -i -v oder Browser-Entwickler-Tools, um das Vorhandensein der Kopfzeile vor und nach der Anwendung der Fehlerbehebung zu überprüfen. Beispiel: -i -v https:///path-that-triggers-error

Empfehlungen zu Best Practices:

  • In Backend-Anfragen immer eine Korrelations-ID generieren und festlegen.
  • Dieselbe ID muss in den Protokollen und Kopfzeilen enthalten sein.
  • Verwenden Sie x-aem-error-pass: true für Fehlerantworten, die eine vollständige Rückverfolgbarkeit erfordern, insbesondere beim Debugging- oder Integrationstest.
  • Beschränken Sie die Nutzung in der Produktion auf kontrollierte Szenarien, um zu vermeiden, dass die standardmäßige Fehlerbehandlung in CDN überschrieben wird.

Verwandtes Lesen

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