Documentação

Preservar X-Correlation-Id nas respostas de erro do AEMaaCS (404/500)

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

No Adobe Experience Manager as a Cloud Service, você usa o cabeçalho X-Correlation-Id para rastrear solicitações nas camadas do AEM, Dispatcher e CDN. Embora este cabeçalho apareça em respostas bem-sucedidas (200 OK), ele está ausente em respostas de erro como 404 Não encontrado ou 500 Erro Interno do Servidor, mesmo que os logs do AEM confirmem que ele foi definido. Por padrão, o CDN substitui as respostas de erro do AEM por páginas sintéticas, que removem os cabeçalhos personalizados. Isso interrompe os fluxos de trabalho de monitoramento e depuração, dificultando a correlação das falhas do lado do cliente com os logs de back-end.

Para corrigir isso, adicione o cabeçalho x-aem-error-pass: true às respostas de erro. Isso instrui o CDN a encaminhar a resposta original do AEM em vez de gerar uma página de erro sintético, garantindo que o cabeçalho X-Correlation-Id seja preservado em todos os tipos de resposta.

Descrição description

Ambiente

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • Configurações de CDN usando responseTransformations
  • Contexto: ao implementar IDs de correlação ou mecanismos de rastreamento no AEM, Dispatcher e CDN

Problema/Sintomas

  • O cabeçalho X-Correlation-Id está presente nas respostas 200 OK, mas está ausente nas respostas 404 ou 500.
  • Os logs do AEM mostram que o cabeçalho está definido, mas não alcança o navegador ou o cliente da API. Observado ao validar o rastreamento de solicitação ou o comportamento de depuração usando cURL, Postman ou o navegador developer tools.
  • Os sistemas de monitoramento falham ao rastrear transações com falha devido à ausência de cabeçalhos de correlação.
  • As configurações de CDN parecem suprimir cabeçalhos nas respostas de erro.

Resolução resolution

Para permitir que a resposta de erro original da AEM e seus cabeçalhos cheguem ao cliente:

  • Configure seu manipulador de erros do AEM para incluir o cabeçalho x-aem-error-pass: true nas respostas de erro.

  • Isso instrui o CDN a ignorar a geração de página de erro sintético e encaminhar a resposta original do AEM ou do Dispatcher (incluindo seus cabeçalhos) diretamente para o cliente.

  • Após aplicar essa alteração:

    • O cabeçalho X-Correlation-Id aparece em respostas com e sem êxito.
    • As ferramentas de monitoramento do lado do cliente podem rastrear o ciclo de vida completo da solicitação com precisão.

Considerações adicionais:

  • Segurança e conformidade: verifique se as cargas de erro não expõem detalhes internos confidenciais antes de habilitar esse cabeçalho na produção.
  • Escopo: esse comportamento se aplica somente às respostas geradas pelo AEM ou Dispatcher. Os erros de nível CDN ainda servirão páginas sintéticas.
  • Equívoco comum: responseTransformations não pode reinjetar cabeçalhos em respostas de erro sintético.
  • Dica de teste: use o curl -i -v ou as ferramentas do desenvolvedor do navegador para verificar a presença do cabeçalho antes e depois de aplicar a correção. Por exemplo, -i -v https:///path-that-triggers-error

Prática recomendada:

  • Sempre gere e defina uma ID de correlação em solicitações de back-end.
  • Inclua a mesma ID em logs e cabeçalhos.
  • Use x-aem-error-pass: true para respostas de erro que exigem rastreabilidade completa, especialmente durante testes de depuração ou integração.
  • Limite o uso na produção para cenários controlados a fim de evitar a substituição da manipulação de erros padrão do CDN.

Leitura relacionada

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