Tipos de evento

Um tipo de evento é definido de acordo com um contexto de negócio da sua operação. Exemplos: transação financeira (transaction), autenticação de usuário (user_authentication) ou marcos logísticos de entrega (logistics_delivery_event).

O tipo de evento define o contrato de dados de um evento: como o evento deve ser estruturado, quais dados são relevantes para análise e como esses dados podem ser monitorados ao longo do tempo.

Diferença entre tipo de evento e evento

tipo de evento: é o modelo de dados e regras de validação.
evento: é a ocorrência real enviada para a API, seguindo o modelo do tipo de evento.

Todo evento sempre pertence a um tipo de evento previamente configurado.

Na API POST /events, o atributo type do evento informa o ID do tipo de evento cadastrado. Se o tipo informado não existir ou estiver inativo, a plataforma rejeita o envio.

Contrato por contexto de negócio

Com tipo de evento, a integração deixa de depender de um contrato rígido por domínio de negócio e passa a seguir um modelo mais flexível:

o tipo de evento é definido de acordo com o contexto de negócio;
os eventos padronizados são enviados para o endpoint POST /events;
o modelo evolui com menor acoplamento entre produto e integração.

Componentes principais

Um tipo de evento normalmente contempla:

campos: estrutura do evento (por exemplo: identificadores, valores, status e atributos de contexto);
métricas: agregações e indicadores derivados dos eventos recebidos;
monitoramentos: critérios e visões para acompanhamento operacional, risco e performance;
análises: avaliadores de risco que pontuam o comportamento recente de cada evento;
regras: lógica avaliada sobre cada evento recebido, no momento em que ele chega.

Essa combinação modela fluxos de negócio diferentes sem um endpoint específico para cada novo caso de uso.

Campos

Os campos definem o contrato de dados do tipo de evento. Consulte Campos para detalhes sobre configuração, tipos de dado e regras de validação.

Análises

As análises acumulam o histórico recente dos eventos em janelas deslizantes e devolvem uma pontuação de risco para cada novo evento, consultada pelas regras. Consulte Análises para a configuração das células, das medidas e dos sinais.

Último evento recebido

O tipo de evento registra o momento em que recebeu o último evento, exibido no painel. É a leitura mais direta para confirmar que uma integração está enviando dados e para identificar um tipo de evento que parou de receber.

Regra padrão

O tipo de evento pode indicar uma regra padrão, aplicada a todos os eventos daquele tipo quando a requisição não informa explicitamente qual regra executar. É a forma recomendada de operar quando existe uma única lógica para o tipo de evento: a integração envia apenas os dados, e a regra passa a ser configuração de painel.

Informar rule.name na requisição sobrepõe a regra padrão.

Relação com a API /events

Depois que um tipo de evento é definido, cada ocorrência é enviada para POST /events seguindo o contrato correspondente.

Esse padrão favorece:

padronização de ingestão de dados;
evolução contínua da modelagem;
reaproveitamento de métricas e monitoramentos entre cenários.

Tipo de evento de falhas

Cada conta tem um tipo de evento reservado, _failure, que registra o que deu errado na integração da conta. As falhas incluem as requisições recusadas pela API de eventos, as regras que falharam ao processar um evento e os monitoramentos não executados. A conta acompanha as falhas como acompanha os demais eventos, em vez de perceber as falhas apenas pela ausência de dados.

Consulte as falhas em Explorar ou pelo agente, como os eventos de qualquer tipo. Na lista de tipos de evento, _failure apresenta a marca Sistema. No menu de tipos de evento de Explorar, _failure está em Mais.

A plataforma gerencia o tipo de evento _failure:

os campos não podem ser editados;
nenhuma regra pode ser associada ao tipo de evento;
a API não aceita eventos enviados para _failure;
o tipo de evento não conta no limite de tipos de evento da conta;
os eventos são mantidos por 7 dias.

Os IDs de tipo de evento iniciados por _ são reservados para os tipos do sistema.

Tipo de evento de alertas

Cada conta tem um tipo de evento reservado, _alert, com um evento a cada abertura e a cada encerramento de um alerta dos monitoramentos. O histórico de alertas pode ser consultado em Explorar, medido por métricas e acompanhado por monitoramentos, como os demais eventos.

Os eventos de _alert são mantidos pelo mesmo período dos demais eventos, conforme Dados originais. Um alerta deixa de ser exibido com a retenção da métrica, mas os eventos de abertura e de encerramento permanecem. Os alertas anteriores à criação do tipo de evento não fazem parte do histórico.

Campo	Rótulo no painel	Conteúdo
`event`	Evento	Aberto, Normalizado, Expirado ou Desativado, conforme o ciclo de vida
`monitor`	Monitoramento	monitoramento que abriu o alerta
`metric`	Métrica	métrica do monitoramento
`aggregation`	Agregação	agregação monitorada
`event_type`	Tipo de evento	tipo de evento da métrica
`interval`	Intervalo	intervalo do monitoramento, de 1 minuto a 7 dias
`direction`	Direção	Alta ou Queda; ausente em alerta originado somente de condições
`segment`	Segmento	segmento do alerta; ausente em monitoramento sem segmentação
`segment_hash`	Hash do segmento	identificador do segmento, para agrupar os alertas de um mesmo segmento
`value`	Valor	valor observado; apenas na abertura
`threshold`	Limite ultrapassado	limite ultrapassado; apenas na abertura
`duration_seconds`	Duração (segundos)	duração do alerta; apenas no encerramento

A abertura e o encerramento de um mesmo alerta têm o mesmo ID de evento. Os campos de monitoramento, métrica, agregação e tipo de evento apresentam o nome atual do recurso, inclusive de um recurso removido. As avaliações dos alertas não fazem parte do tipo de evento.

A plataforma gerencia o tipo de evento _alert como o de falhas, com a marca Sistema e o menu Mais em Explorar:

os campos não podem ser editados;
nenhuma regra pode ser associada ao tipo de evento;
a API não aceita eventos enviados para _alert;
o tipo de evento não conta no limite de tipos de evento da conta;
um monitoramento sobre o próprio _alert não gera eventos de alerta.

Boas práticas

Use nomes claros e estáveis para os tipos de evento.
Evite tipos genéricos demais, sem semântica de negócio.
Trate mudanças de contrato com versionamento planejado.
Documente obrigatoriedade e formato de cada campo para o time de integração.

Índice

Exemplos de tipos de evento