Ir para o conteúdo

Lidar com mensagens com falha usando uma Fila de Letra Morta no Jitterbit Studio

Introdução

O conector Jitterbit MQ permite processar mensagens de uma fila usando uma atividade Get. Quando o processamento falha, uma abordagem comum é usar a atividade NACK com Requeue Messages After NACK para devolver a mensagem à fila para uma tentativa posterior. Com filas Quorum, porém, essa abordagem tem um limite rígido: após 20 confirmações com falha, a mensagem é removida permanentemente da fila sem um erro. Para integrações que exigem comportamento de repetição controlado e entrega garantida, use o padrão Dead Letter Queue (DLQ) em vez disso.

Este guia apresenta a construção de um padrão DLQ usando várias filas e um conjunto de operações do Studio. As mensagens com falha são rejeitadas da fila principal e roteadas para uma série de filas de repetição com atrasos crescentes. Após um número configurável de tentativas, as mensagens são enviadas para uma DLQ final para inspeção manual.

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart TD A([Message in orders.main]) --> B[Main processor] B -->|Success| C([ACK: message removed]) B -->|Failure| D{retryCount} D -->|1| E([orders.retry.1m]) D -->|2| F([orders.retry.5m]) D -->|3 or 4| G([orders.retry.30m]) D -->|greater than 4| H([orders.dlq]) E -->|Forwarder runs every 1 min| A F -->|Forwarder runs every 5 min| A G -->|Forwarder runs every 30 min| A

Para necessidades de repetição mais simples que não exigem roteamento de atraso em várias camadas, consulte Repetir uma operação com falha. Para obter informações sobre como configurar o comportamento ao sucesso e à falha, consulte Configurar tratamento de erros em operações.

Este guia assume o seguinte:

  • Você tem uma conexão Jitterbit MQ funcionando no Studio. Para instruções de configuração, consulte a documentação do conector Jitterbit MQ.
  • Você está familiarizado com a criação e execução de operações do Studio.
  • Você está usando filas Quorum, que são necessárias para durabilidade, mas impõem o limite de entrega de 20 tentativas que este padrão aborda.

Parte 1: Criar as filas

Etapa 1: Criar as filas no Console de Gerenciamento

  1. Abra a página Filas de Mensagens do Console de Gerenciamento.

  2. Crie as cinco filas a seguir. Defina o Tipo como Quorum para cada uma.

    Nome da fila Finalidade TTL da mensagem
    orders.main Fila de processamento primário —
    orders.retry.1m Primeira repetição (atraso de 1 minuto) 3.600.000 ms
    orders.retry.5m Segunda repetição (atraso de 5 minutos) 3.600.000 ms
    orders.retry.30m Terceira repetição (atraso de 30 minutos) 3.600.000 ms
    orders.dlq Fila final para inspeção manual 864.000.000 ms

    Adapte os nomes das filas e o número de camadas de repetição para sua integração.

Nota

Os valores de TTL nas filas de repetição são uma salvaguarda que impede o acúmulo indefinido de mensagens se uma operação encaminhadora falhar. O atraso entre as repetições é controlado pela frequência com que as operações encaminhadoras são executadas, não pelo TTL.

Parte 2: Configurar a operação do processador principal

Etapa 2: Adicionar um campo retryCount ao seu payload de mensagem

O padrão DLQ usa um campo retryCount no payload da mensagem para rastrear quantas vezes o processamento foi tentado. Adicione este campo ao seu payload de mensagem com um valor inicial de 0 antes da operação ser acionada pela primeira vez.

Payload de exemplo

{
  "orderId": "ORD-12345",
  "retryCount": 0
}

Use um nome de campo consistente no nível superior em todas as operações do padrão. O campo retryCount é o único mecanismo para rastrear o histórico de tentativas entre execuções.

Etapa 3: Construir a operação de roteamento ao falhar

Quando o processador principal falha, a operação ao falhar deve ler o retryCount atual, rotear a mensagem para a fila de repetição apropriada e rejeitar a mensagem original da fila principal.

  1. Leia retryCount do campo messageBody no esquema de resposta da atividade Get.

  2. Incremente o valor em 1 usando um script ou transformação.

  3. Encaminhe para a fila apropriada com base na contagem atualizada:

    Valor de retryCount Fila de destino
    1 orders.retry.1m
    2 orders.retry.5m
    3 ou 4 orders.retry.30m
    Maior que 4 orders.dlq

  4. Escreva o retryCount atualizado de volta no campo messageBody do schema de requisição da atividade Send ao encaminhar para a fila de destino.

  5. Após a atividade Send ser concluída, use a atividade NACK com a opção Reject Messages After NACK para remover a mensagem de orders.main.

Importante

A atividade Send para a fila de retry deve ser concluída antes da atividade NACK ser executada. Essa ordem garante que a mensagem não seja perdida se a atividade Send falhar. Não use Requeue Messages After NACK, que ignora a lógica de roteamento da DLQ e conta para o limite de 20 tentativas de entrega.

Etapa 4: Configurar a operação do processador principal

  1. No Studio, abra ou crie a operação que processa mensagens de orders.main.

  2. Adicione uma atividade Get configurada para ler de orders.main.

  3. Adicione as etapas que processam cada mensagem (por exemplo, consultando um sistema ERP para o status de pedido esperado).

  4. Abra as configurações de ações da operação e configure o seguinte:

    • On Success: Execute uma operação que usa a atividade Acknowledge para confirmar a mensagem de orders.main.
    • On Fail: Execute a operação de roteamento de falha criada na Etapa 3.

Parte 3: Configurar as operações do encaminhador de retry

Crie uma operação de encaminhador para cada fila de retry. Cada encaminhador lê mensagens de sua fila de retry, as envia de volta para orders.main para reprocessamento e é executado em um cronograma que corresponde ao atraso pretendido para esse nível.

Etapa 5: Criar cada operação de encaminhador

Para cada nível de retry, crie uma operação com as seguintes etapas:

  1. Adicione uma atividade Get para recuperar uma mensagem da fila de retry.

  2. Adicione uma atividade Send para enviar a mensagem para orders.main, preservando o valor de retryCount no payload.

  3. Adicione uma atividade Acknowledge para confirmar a mensagem da fila de retry.

Importante

A atividade Send para orders.main deve ser concluída antes da atividade Acknowledge ser executada. Se a atividade Send falhar, a mensagem permanece na fila de retry e será recuperada na próxima execução do encaminhador. Confirmar antes de a atividade Send ser concluída removeria silenciosamente a mensagem da fila de retry sem garantia de que ela chegou a orders.main.

Etapa 6: Agendar cada operação de encaminhador

Anexe um cronograma de operação a cada operação de encaminhador com um intervalo correspondente ao seu nível de retry:

Operação Fila de origem Intervalo de cronograma
Encaminhador de retry 1m orders.retry.1m A cada 1 minuto
Encaminhador de retry 5m orders.retry.5m A cada 5 minutos
Encaminhador de retry 30m orders.retry.30m A cada 30 minutos

Para obter instruções sobre como configurar um agendamento, consulte Agendar uma operação para ser executada automaticamente.

Operação do inspetor DLQ (opcional)

Crie uma operação que leia de orders.dlq para alertar ou registrar mensagens que esgotaram todas as tentativas de repetição. Esta operação pode enviar uma notificação por email, escrever em um log ou disparar um fluxo de trabalho de revisão manual. Para obter instruções sobre como enviar email de uma operação do Studio, consulte Enviar uma notificação por email de uma operação do Studio.

Nota

Mensagens em orders.dlq exigem intervenção manual. Elas permanecem na fila até serem explicitamente reconhecidas ou seu TTL expirar.

Verificar a integração

  1. Implante o projeto.

  2. Envie uma mensagem de teste para orders.main com retryCount: 0 na carga.

  3. Dispare uma falha de processamento na operação do processador principal (por exemplo, retornando um erro do script de processamento).

  4. Abra os logs de operação no Studio e confirme que a operação on-fail foi executada e que a mensagem foi enviada para orders.retry.1m.

  5. Aguarde o encaminhador de 1 minuto ser executado. Confirme nos logs de operação que o encaminhador recuperou a mensagem de orders.retry.1m e a enviou de volta para orders.main.

  6. Continue disparando falhas para avançar a mensagem pelos níveis de repetição restantes. A fila orders.retry.5m trata uma passagem (retryCount 2) e orders.retry.30m trata duas passagens (retryCount 3 e 4). Após a quinta tentativa com falha, a mensagem é roteada para orders.dlq.

  7. Abra a página Filas de Mensagens do Console de Gerenciamento e confirme que uma mensagem chegou em orders.dlq.