Análises

Uma análise é um avaliador de risco configurado sobre um tipo de evento. Ela acumula o histórico recente dos eventos em janelas deslizantes e, a cada novo evento, devolve uma pontuação de 0 a 100 indicando 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, consulta o resultado com a ação executar análise e usa esse resultado nas condições seguintes.

Destina-se 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.

A análise é transacional: ela 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.

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 e 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) e Gatilho (o limite aplicado a esse número). Ele também oferece exemplos prontos, como um contador de tentativas ou um limite de velocidade, que preenchem os quatro grupos de uma vez e podem ser ajustados em seguida.

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

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, e 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 que a ação fique 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. Ao persistir a célula do score em um campo do evento, ele fica preenchido apenas nos eventos em que alguma célula explicou a pontuação.

Uma célula que não pode ser avaliada, porque o evento não trouxe o campo da dimensão ou porque a janela está vazia, é ignorada, nunca lida como se estivesse normal.

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, e é o que permite mudar 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, e 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, de modo que um cliente que tentou dez vezes pesa 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

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 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 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, e 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, ela mostra a escala saltando direto de 0 para 100 no alvo.

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.

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, separando as que a executam 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, ambos assinalados nessa relação:

pontua sem que ninguém registre: uma regra consulta a análise, mas nenhuma alimenta as suas janelas, de modo que 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, de modo que 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 removida. A remoção informa quais regras a mantêm em uso, e 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, a edição de uma célula ou da ordem da cascata parte dela para um rascunho, e a publicação leva a cascata inteira ao ar de uma vez. Uma versão anterior pode ser restaurada, e uma versão pode ser publicada em observação, sobre o mesmo tráfego da versão ativa, sem decidir nada. Consulte Versionamento.