Quarentena de eventos

A quarentena protege a operação quando um evento não pode seguir o fluxo esperado ou quando ele já foi recebido antes.

Ela separa o evento, registra os problemas encontrados e permite investigar a causa sem deixar um dado inválido afetar segmentos, computed traits ou jornadas.

Recebido não significa processado

A ingestão é assíncrona. Uma resposta de sucesso com status 202 confirma que o PrismaFlow recebeu o evento para processamento, mas não garante que ele passou por todas as validações.

Se um problema for encontrado depois dessa resposta, o evento aparecerá na quarentena. Por isso, a saúde da integração também deve ser acompanhada pelo dashboard.

Um relatório semanal de saúde da ingestão está em implantação. Ele reunirá essa informação com outras métricas e será enviado aos emails dos administradores da conta.

O que aparece na quarentena

O dashboard mostra os eventos separados e permite filtrar por:

nome do evento;
motivo;
status;
período de recebimento.

Nos detalhes, é possível conferir o nome e a versão do evento, quando ele foi recebido, o motivo da quarentena, os caminhos com erro e as tentativas de reprocessamento.

Quando existem vários problemas de validação no mesmo evento, a quarentena apresenta todos os que foram encontrados. Corrigi-los em conjunto evita uma nova tentativa ainda inválida.

O payload original fica protegido e não é exposto na listagem nem nas exportações. Use os caminhos e mensagens apresentados, o nome e a versão do evento, o horário de recebimento e os registros da aplicação de origem durante a investigação.

Motivos e caminhos de recuperação

Envelope inválido

O formato básico do evento possui um problema. Ele pode estar no nome, na versão, no timestamp, nos identificadores ou em outra parte obrigatória do envio.

Corrija a integração e envie um novo evento pela origem. O payload guardado na quarentena não pode ser editado.

Definição não encontrada

Não existe uma definição para a combinação exata de nome e versão enviada.

Se essa combinação está correta, crie a definição e reprocesse o evento. Se a integração deveria usar outro nome ou outra versão, corrija a origem e envie um novo evento.

Criar uma v2 não torna um evento enviado como v1 válido. Para reprocessar o evento original, a definição de sua própria versão precisa existir e estar ativa.

Definição desabilitada

A definição existe, mas não está ativa.

Reative a definição e reprocesse o evento quando aquele contrato ainda deve ser aceito. Se a integração deveria usar uma versão diferente, normalize a origem e envie um novo evento com a versão correta.

Falha na validação do schema

Uma ou mais propriedades não cumprem a definição. Pode faltar um campo obrigatório ou existir um valor que não pode ser normalizado para o tipo declarado.

Primeiro decida onde está o erro:

se o payload representa o dado correto, ajuste o contrato de forma compatível e reprocesse;
se o contrato está correto, corrija a origem e envie um novo evento.

Lembre que o reprocessamento usa o payload original. Ele não corrige um valor errado enviado pela integração.

Propriedade desconhecida

Um evento validado como strict trouxe uma propriedade que não faz parte da definição.

Se o campo possui uso real, inclua-o no contrato de forma compatível e reprocesse. Se ele é ruído ou foi enviado por engano, remova-o na origem e envie um novo evento.

Tipo de identidade não configurado

O evento trouxe um identificador cujo tipo ainda não está pronto para uso no aplicativo.

Conclua a configuração desse tipo de identidade e reprocesse o evento. Não mova o valor para properties para contornar a configuração, pois ele deixaria de receber o tratamento protegido de identifiers.

Conflito de identidade

Os identificadores do evento encontraram perfis diferentes, mas a configuração não permite que eles sejam unidos automaticamente.

Confirme se os valores representam a mesma pessoa antes de mudar a configuração. Não ative o merge apenas para liberar um evento: essa decisão também valerá para conflitos futuros e pode reunir históricos, segmentos e jornadas.

Veja Identidades e formação de perfis [blocked] para entender por que esse conflito acontece e quais cuidados tomar.

Evento duplicado

O PrismaFlow reconheceu que aquele evento já havia sido recebido e impediu um segundo processamento.

Esse é um mecanismo de segurança, não uma quebra de contrato. O registro pode ser usado para investigar por que a origem reenviou o evento, mas não deve ser reprocessado.

Duplicidades aparecem com mais frequência em integrações server-side. Uma interrupção durante o processamento, por exemplo, pode fazer a origem enviar novamente algo que já havia sido entregue. As SDKs de navegador e aplicativo cuidam de suas filas para evitar esse comportamento; duplicidades vindas delas são raras e podem indicar uma falha que precisa ser investigada.

Como investigar sem olhar evento por evento

Comece pelo conjunto, não por um registro isolado.

Abra a quarentena na área de eventos.
Observe a quantidade de eventos por motivo, nome e versão.
Use o período em que o volume começou a mudar para relacionar o problema a uma alteração de integração.
Abra um exemplo e leia todos os caminhos com erro.
Confirme na origem se o contrato ou o payload precisa ser corrigido.
Faça a correção antes de reprocessar ou reenviar.

Quebras de contrato tendem a ser raras em uma integração madura. Em uma operação que já recebeu cerca de 500 milhões de eventos, a duplicidade é o motivo observado com mais frequência. Isso reforça a importância de analisar o volume e a causa, sem assumir que toda entrada na quarentena representa um contrato quebrado.

O que acontece ao reprocessar

Somente eventos com status pendente podem ser reprocessados.

O PrismaFlow recupera o payload original e valida novamente a definição, o schema e as configurações necessárias:

se o evento estiver válido, ele volta para a ingestão, recebe um novo event_id e fica com status reprocessado;
se continuar inválido, permanece pendente, recebe o motivo e os erros mais recentes e consome uma tentativa;
ao completar três tentativas inválidas, fica com status esgotado.

Reprocessar várias vezes sem corrigir a causa não ajuda. Como o payload guardado não muda, o resultado também não mudará enquanto o contrato ou a configuração continuarem iguais.

Quando enviar um novo evento

Corrija a origem e faça um novo envio quando:

o envelope está inválido;
uma propriedade enviada está errada;
o evento deveria usar outro nome ou outra versão;
o registro já esgotou as tentativas de reprocessamento.

Não existe uma recuperação interna que libere um evento esgotado. Esse caso é pouco comum porque a quarentena apresenta os problemas encontrados antes de cada tentativa. Se o limite for atingido, a recuperação é corrigir a fonte e enviar um novo evento.

Não reenvie um evento marcado como duplicado apenas para removê-lo da quarentena. O evento original já foi protegido contra um segundo processamento, e o registro serve como evidência para investigar a origem.

Exportação e acompanhamento

A visão pode ser exportada em JSON ou CSV com os filtros aplicados. A exportação é útil para agrupar ocorrências, compartilhar uma investigação e acompanhar a evolução de uma correção.

Ela contém o resumo operacional dos erros, mas não revela o payload original.

Checklist de recuperação

O motivo e todos os caminhos com erro foram lidos.
O nome e a versão correspondem à definição esperada.
Foi decidido se a correção pertence ao contrato, à configuração ou à origem.
A causa foi corrigida antes de usar uma tentativa.
O evento original pode ficar válido sem editar o payload armazenado.
Eventos duplicados não serão reprocessados.
Um evento esgotado será corrigido e reenviado pela fonte.