Análises

Configure uma análise em um tipo de evento para responder a perguntas de velocidade e de concentração: quantas tentativas este cartão fez na última hora, quantos cartões diferentes passaram por este usuário hoje.

Uma análise é um avaliador de risco configurado sobre um tipo de evento. A análise acumula o histórico recente dos eventos em janelas deslizantes e, a cada novo evento, devolve uma pontuação de 0 a 100. A pontuação indica o quanto aquele comportamento destoa do esperado.

A análise não decide sozinha: a decisão cabe à regra. A regra alimenta a análise com a ação registrar análise e consulta o resultado com a ação executar análise. As condições seguintes da regra usam esse resultado.

A análise é transacional: avalia um evento por vez e responde a tempo de a regra agir sobre ele. O termo se refere ao modo de operação, não ao tipo de dado. A análise vale para qualquer tipo de evento, não apenas para transações financeiras. Para acompanhar o comportamento agregado ao longo do tempo, use métricas e monitoramentos.

Como a análise decide

Uma análise é um conjunto de células. Cada célula é uma pergunta independente sobre uma fatia do histórico: um agrupamento, uma janela de tempo, uma medida e um alvo.

Todas as células são avaliadas. A mais específica entre as que acionaram decide o resultado: vale a menor Prioridade e, em caso de empate, a célula que observou a maior amostra.

A pontuação devolvida é a dessa célula, e não a maior da análise: uma célula específica que pontuou 91 decide na frente de uma célula abrangente que pontuou 99. A cascata escolhe pelo alcance do bloqueio, não pela magnitude do desvio, para manter a ação restrita ao menor grupo possível.

Quando nenhuma célula aciona, a pontuação é a maior que alguma célula alcançou, e a célula do score não é informada. Um campo do evento que persiste a célula do score fica preenchido apenas nos eventos em que alguma célula explicou a pontuação.

Quando o evento não traz o campo da dimensão, ou quando a janela está vazia, a célula não pode ser avaliada. A célula é ignorada, nunca lida como se estivesse normal.

Onde configurar

Em Configurações > Tipos de evento, abra o tipo de evento e vá até a aba Análises.

A análise tem um único campo próprio, o Nome, que é o identificador usado pelas regras. O nome não pode ser alterado depois da criação: as ações que citassem o nome antigo ficariam órfãs. Todo o resto é configurado nas células.

O editor da célula organiza a configuração em quatro grupos:

Identidade: o identificador da célula;
Janela: quais eventos entram, com que chave e por quanto tempo;
Medida: o número extraído da janela;
Gatilho: o limite aplicado a esse número.

O editor também oferece exemplos prontos, como um contador de tentativas ou um limite de velocidade. Cada exemplo preenche os quatro grupos de uma vez e pode ser ajustado em seguida.

Reordene a lista de células por arrasto. A nova ordem grava a Prioridade de cada célula e define a ordem da cascata: a primeira da lista decide primeiro.

Usar a análise em uma regra

A análise só produz efeito através de uma regra:

a ação registrar análise alimenta as janelas com o evento atual;
a ação executar análise avalia a análise e disponibiliza o resultado;
as condições seguintes decidem o que fazer com esse resultado.

O resultado fica disponível como variável temporária, com a pontuação, a célula que a originou e o conjunto de células acionadas.

Cada célula avaliada também publica o valor bruto que mediu na janela, em %<resultado>.cells.<célula>.value. Uma célula sem gatilho entrega o seu número por essa variável, para as condições seguintes ou para um campo do evento.

Condição 1:  $amount > 0     → Registrar análise: bot
Condição 2:  $amount > 0     → Executar análise: bot
Condição 3:  %bot.triggered  → Preencher campo: revisao = "true"
Condição 4:  "recusas_por_cartao" in %bot.triggered_cells  → Adicionar à lista: $card_fingerprint em @cartoes_bloqueados

Registrar e executar são independentes: uma condição pode alimentar o histórico sem consultá-lo, consultá-lo sem alimentar, ou fazer as duas coisas.

Campos da célula

Campo	Conteúdo
Nome	identificador da célula, único dentro da análise; aparece nos resultados da regra
Dimensão	campo, ou combinação de campos, que agrupa a janela
Janela	tamanho da janela deslizante, em minutos, horas ou dias, até 90 dias
Sinal	como a célula julga a janela: estatístico, limite fixo ou sem gatilho
Medida	o que a célula mede na janela
Direção	qual lado do alvo representa risco
Alvo	valor de referência; nas medidas de taxa, um número entre 0 e 1
Limite	pontuação de 0 a 100 a partir da qual a célula aciona; padrão 90
Prioridade	ordem na cascata; a menor decide primeiro
Numerador e Denominador	filtros que definem a taxa, nas medidas de porcentagem
Distinto por	campo contado, ou entidade da taxa, conforme a medida
Registrar quando	filtro que decide quais eventos alimentam a janela

Registrar quando é a única configuração que enxerga campos que a célula não agrupa nem conta. Esse filtro muda a pergunta: registrar somente eventos recusados transforma uma célula de “cartões diferentes deste usuário” em “cartões diferentes em que este usuário foi recusado”.

Alterar a dimensão, a janela ou a medida reinicia o histórico acumulado, sem reprocessamento. A célula precisa de uma janela inteira de tráfego para voltar a significar alguma coisa. Alterar o alvo, o limite, a prioridade ou os filtros preserva o histórico.

Medida

Medida	O que mede
Quantidade	volume de eventos na janela, ou seja, velocidade
Valores distintos	quantos valores diferentes de um campo aparecem na janela
Porcentagem	a taxa de um resultado, como a de aprovação
Porcentagem por valores distintos	a mesma taxa, contando cada valor distinto uma única vez

Quantidade não exige configuração adicional. Valores distintos exige o campo Distinto por, cujos valores diferentes são contados.

Porcentagem exige um Numerador e aceita um Denominador, ambos filtros sobre o mesmo campo de resultado. O numerador diz quais valores contam a favor. Com o denominador vazio, a base são todos os valores da janela.

Porcentagem por valores distintos é a mesma taxa medida sobre entidades em vez de tentativas. Cada valor distinto entra com uma observação, a da sua última tentativa na janela. Um cliente que tentou dez vezes pesa, portanto, o mesmo que um que tentou uma.

As duas medidas de porcentagem são avaliadas sobre as 100 observações mais recentes da janela.

Sinal

O sinal define como a célula julga a janela, e é a escolha que muda o significado do Alvo.

Com o sinal Estatístico, que é o padrão, o alvo é o comportamento normal esperado, e a pontuação exprime o quanto a janela destoa dele. Use o sinal estatístico quando o objetivo é detectar desvios do normal e o número exato não importa.

Com o sinal Limite fixo, o alvo é o próprio ponto de disparo: a célula aciona quando a observação o alcança, e a pontuação é sempre 100 ou 0. Use o limite fixo quando o número faz parte de uma política acordada, por exemplo um teto de tentativas recusadas por período definido em contrato. Traduzir esse número em um alvo estatístico o deixaria acoplado à calibração da análise. Reajustar a calibração moveria silenciosamente um valor que um documento externo fixa.

Ao escolher o limite fixo:

Não há proteção contra amostras pequenas. É a diferença central em relação ao sinal estatístico, e um risco real nas medidas de porcentagem: um limite de 50% aciona com uma única tentativa recusada, porque uma recusa em uma tentativa é 100%. Combine-o com uma janela e um filtro de registro que tornem uma amostra pequena significativa.
O campo Limite não se aplica e some do formulário, já que a pontuação só assume 100 ou 0.
A direção é de um lado só: “Acima” aciona ao alcançar ou passar do alvo, “Abaixo” ao alcançar ou ficar sob ele. “Ambos” é recusado, porque um número único delimita apenas um lado.
Nas medidas de volume o alvo precisa ser inteiro: não se observa 2,5 eventos.

Sem gatilho

Uma célula com o sinal Sem gatilho mantém a janela e expõe o valor medido, sem acionar. Alvo, Direção e Limite não se aplicam, e a célula fica fora da cascata: não decide o resultado nem entra na contagem de células acionadas.

A célula sem gatilho é adequada para expor um número da janela sem transformá-lo em bloqueio: contar as tentativas de um pedido, gravar esse contador em um campo e deixar a decisão para uma condição da regra.

Os três sinais convivem na mesma análise, e os dois que acionam pontuam na mesma escala de 0 a 100.

O formulário mostra uma prévia da célula assim que medida, direção e alvo estiverem preenchidos. Em uma célula de limite fixo, a prévia mostra a escala saltando direto de 0 para 100 no alvo.

Regras que usam esta análise

A página da análise apresenta as regras que se ligam a ela, uma linha por versão de regra. A relação separa as regras que executam a análise das que a registram, com os campos que cada uma grava e o nome do resultado.

Como registrar e executar são independentes, a análise pode ficar em um de dois estados incompletos. A relação assinala os dois:

pontua sem que ninguém registre: uma regra consulta a análise, mas nenhuma alimenta as suas janelas. A pontuação é calculada sobre um histórico que não recebe tráfego;
registra sem que ninguém pontue: as janelas acumulam, mas nenhuma regra lê o resultado. A análise não produz efeito sobre decisão alguma.

Uma análise nomeada por uma versão de regra publicada ou em observação não pode ser arquivada. A tentativa informa quais regras a mantêm em uso, e o arquivamento passa a ser possível depois que essas regras deixam de nomeá-la.

Versões

Uma análise é versionada como uma regra. A versão publicada é imutável, uma alteração de célula ou da ordem da cascata é feita em um rascunho, e a publicação leva a cascata inteira ao ar de uma vez. Uma versão anterior volta ao ar quando publicada novamente. Uma versão pode ser publicada em observação, sobre o mesmo tráfego da versão ativa, sem decidir nada. Consulte Versionamento.

O score de qualquer versão, inclusive de um rascunho, pode ser calculado com valores informados manualmente, sem gravar nada. Consulte Simulação.