Versionamento

Toda alteração em uma regra ou em uma análise publicada gera uma nova versão. O versionamento garante rastreabilidade, registrando quem alterou, quando e o que mudou, e permite reverter para versões anteriores quando necessário.

A mecânica é a mesma nos dois casos: uma versão publicada é imutável, a edição parte dela para um rascunho, e a publicação substitui o que está no ar. O que difere na análise está em Versões de análise.

Status

Cada versão pode estar em um dos seguintes status:

• Rascunho: pode ser modificada livremente. Só passa a valer depois de publicada.
• Em observação: publicada em paralelo com a versão ativa, sem decidir nada. Descrita em Observação.
• Ativa: versão publicada, em uso pela API. Não pode ser modificada: alterações geram uma nova versão.
• Inativa: já esteve ativa em algum momento. Mantida para rastreabilidade e pode ser reativada a qualquer momento.
• Removida: oculta no painel, mas preservada no histórico. Permanece visível ao inspecionar eventos antigos que a utilizaram.

Uma regra ou uma análise admite no máximo uma versão ativa e uma versão em observação ao mesmo tempo. Uma versão publicada apresenta o botão Nova versão a partir desta em lugar do botão de edição, e informa que não pode ser editada.

Comparação e publicação

A publicação de uma versão exige a revisão prévia das mudanças em relação à versão ativa. A tela de comparação abre posicionada entre a versão ativa e a versão a publicar, e o botão de publicar fica no próprio comparativo, após a revisão. Uma regra sem versão publicada é sinalizada como tal e só passa a valer após a primeira publicação.

A comparação abrange as condições e as ações. Cada linha corresponde a uma condição: as linhas coloridas indicam as que mudaram, e uma etiqueta identifica a alteração (adicionada, removida, reordenada ou alterada). Na coluna de ações, uma ação riscada deixa de valer e a que a substitui aparece após a seta; uma ação marcada com + é nova. O comparativo expõe o efeito exato da publicação antes de a versão entrar em vigor.

Na análise, cada linha corresponde a uma célula, com o valor anterior e o novo de cada configuração alterada.

Condições atendidas

Cada condição de uma versão de regra registra quantas vezes foi atendida a cada dia, apresentado na própria condição junto com o total de execuções do período. A leitura distingue três situações: o dia em que a regra não recebeu tráfego, o dia em que executou sem que a condição fosse atendida, e o dia em que ela foi atendida ao menos uma vez.

A contagem localiza a condição que nunca é atendida, seja porque a expressão não corresponde ao tráfego real, seja porque uma condição anterior já preencheu o campo que ela testa. Uma condição que não é atendida nenhuma vez desde a publicação é candidata a revisão antes da próxima versão.

A contagem começa na publicação da versão e considera apenas eventos reais: as simulações ficam de fora. Uma versão recém-publicada, portanto, começa sem leitura.

Observação

Uma versão pode ser publicada em observação (shadow) antes de entrar em vigor. Nesse estado ela é executada em paralelo com a versão ativa, sobre os mesmos eventos reais, e nada do que produz altera o resultado do evento: a decisão continua sendo a da versão ativa. O ciclo de vida passa a ser rascunho, observação e ativa.

Uma versão inativa também pode ser colocada em observação, o que permite avaliar uma versão já substituída sem devolvê-la ao comando das decisões. A versão ativa é a única que não pode ser observada, por já estar decidindo.

Uma versão em observação é imutável, como a ativa: editá-la cria um novo rascunho. A versão promovida é exatamente a que foi observada, sem reescrita das ações.

Saídas observadas

A observação é seletiva. Ao publicar, você marca quais saídas quer acompanhar. Cada saída marcada é gravada no mesmo evento, em um campo com o sufixo _shadow, ao lado do valor que a versão ativa gravou. As saídas não marcadas são descartadas junto com o restante da execução.

Como os dois valores ficam no mesmo evento, a comparação usa as telas existentes: filtros em Explorar, métricas e dashboards comparam o campo e o seu par observado sem configuração adicional.

As saídas observadas podem ser alteradas a qualquer momento, sem republicar a versão. Uma versão que não preenche nenhum campo não tem saídas para observar e não pode ser publicada em observação.

Todo evento processado registra também a versão em observação que o processou, além do nome e da versão da regra ativa. Sem esse registro não seria possível atribuir um valor observado à versão que o escreveu, já que cada revisão é uma versão nova.

O que a observação não executa

Uma versão em observação não altera o estado compartilhado que outras execuções leem:

• As ações que gravam em listas são suprimidas. As condições que consultam listas continuam lendo a lista real, de modo que uma regra cujo comportamento é alimentar uma lista e depois consultá-la é observada de forma aproximada, não exata.
• As análises registradas pela versão em observação ficam em janelas próprias, separadas das que a versão ativa alimenta e consulta.

As janelas da observação começam vazias e precisam de uma retenção inteira de tráfego para significar alguma coisa. Ao promover a versão para ativa, as janelas recomeçam do zero pelo mesmo motivo.

Em um tipo de evento com versão em observação, o evento fica visível nas consultas alguns instantes depois do recebimento, e não imediatamente, porque a gravação espera a execução observada para levar os dois valores no mesmo registro.

Versões de análise

Uma análise segue o mesmo ciclo da regra, com três particularidades.

Toda edição em uma análise publicada, seja uma célula, seja a ordem da cascata, cria um rascunho, e a publicação leva o conjunto inteiro ao ar de uma vez. Não há publicação de uma célula isolada: a cascata é publicada como um todo, de modo que as células nunca ficam em versões diferentes entre si.

Uma análise admite vários rascunhos ao mesmo tempo, cada um partindo da versão que o originou. A página da análise apresenta os rascunhos abertos e o caminho para cada um.

Alterar o que uma célula mede ou a janela em que ela acumula descarta o histórico já acumulado por essa célula, que recomeça vazia e precisa de uma retenção inteira de tráfego para voltar a significar alguma coisa. A comparação assinala essa consequência antes da publicação, e a confirmação é solicitada no momento da alteração. As demais células da análise mantêm as suas janelas.

Histórico

Cada regra e cada análise tem um histórico com as ações realizadas sobre as suas versões: criação, edição, publicação, publicação em observação, retirada de observação, substituição, despublicação e arquivamento. Cada entrada registra a versão, o autor e o momento.

O histórico exibe as ações mais recentes e mantém as demais recolhidas. A lista de versões é o registro completo.

Rastreabilidade nos eventos

Todo evento processado por uma regra registra o nome da regra e o número da versão que o processou, além da versão em observação, quando houver uma. Isso permite reconstruir depois qual lógica gerou cada valor, inclusive quando a versão já foi substituída ou removida.

A versão da análise que decidiu um evento é registrada pela ação executar análise, no destino Versão.