Documentazione

Mantenere X-Correlation-Id nelle risposte di errore AEMaaCS (404/500)

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

In Adobe Experience Manager as a Cloud Service, utilizzi l'intestazione X-Correlation-Id per tracciare le richieste tra i livelli AEM, Dispatcher e CDN. Anche se l'intestazione viene visualizzata in risposte riuscite (200 OK), risulta mancante in risposte di errore come 404 Non trovato o 500 Errore interno del server, anche se i registri di AEM confermano che è stata impostata. Per impostazione predefinita, la rete CDN sostituisce le risposte di errore di AEM con pagine sintetiche, eliminando le intestazioni personalizzate. Questo interrompe il monitoraggio e il debug dei flussi di lavoro, rendendo difficile correlare gli errori lato client con i registri back-end.

Per risolvere il problema, aggiungere l'intestazione x-aem-error-pass: true alle risposte di errore. In questo modo si comunica alla rete CDN di inoltrare la risposta AEM originale invece di generare una pagina di errore sintetico, garantendo che l'intestazione X-Correlation-Id sia mantenuta in tutti i tipi di risposta.

Descrizione description

Ambiente

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • Configurazioni CDN tramite responseTransformations
  • Contesto: quando si implementano ID di correlazione o meccanismi di traccia in AEM, Dispatcher e CDN

Problema/Sintomi

  • L'intestazione X-Correlation-Id è presente nelle risposte 200 OK ma non nelle risposte 404 o 500.
  • I registri di AEM mostrano che l’intestazione è impostata, ma non raggiunge il browser o il client API. Avviso durante la convalida del comportamento di rilevamento richieste o debug tramite cURL, Postman o browser developer tools.
  • I sistemi di monitoraggio non riescono a tracciare le transazioni non riuscite a causa di intestazioni di correlazione mancanti.
  • Le configurazioni CDN sembrano eliminare le intestazioni nelle risposte di errore.

Risoluzione resolution

Per consentire alla risposta di errore originale di AEM e alle relative intestazioni di raggiungere il client:

  • Configurare il gestore degli errori di AEM in modo da includere l'intestazione x-aem-error-pass: true nelle risposte agli errori.

  • Questo indica alla CDN di ignorare la generazione di pagine con errore sintetico e di inoltrare la risposta originale di AEM o Dispatcher (comprese le relative intestazioni) direttamente al client.

  • Dopo aver applicato questa modifica:

    • L'intestazione X-Correlation-Id viene visualizzata nelle risposte riuscite e non riuscite.
    • Gli strumenti di monitoraggio lato client possono tracciare con precisione l’intero ciclo di vita delle richieste.

Ulteriori considerazioni:

  • Sicurezza e conformità: assicurati che i payload di errore non espongano dettagli interni sensibili prima di abilitare questa intestazione in produzione.
  • Ambito: questo comportamento si applica solo alle risposte generate da AEM o Dispatcher. Gli errori a livello di CDN distribuiranno comunque le pagine sintetiche.
  • Errore comune: responseTransformations non può reinserire le intestazioni nelle risposte di errore sintetico.
  • Suggerimento per il test: utilizza gli strumenti di sviluppo curl -i -v o del browser per verificare la presenza dell’intestazione prima e dopo l’applicazione della correzione. Ad esempio, -i -v https:///path-that-triggers-error

Consigli sulle best practice:

  • Genera e imposta sempre un ID di correlazione nelle richieste back-end.
  • Includi lo stesso ID in registri e intestazioni.
  • Utilizzare x-aem-error-pass: true per le risposte di errore che richiedono la tracciabilità completa, in particolare durante il debug o il test di integrazione.
  • Limita l’utilizzo in produzione a scenari controllati per evitare di ignorare la gestione degli errori standard della rete CDN.

Lettura correlata

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