Criar regras de alerta com labels e notificações

Este guia mostra como criar uma regra de alerta no Elven Observability e preparar seus labels para que ela possa seguir uma política de notificação. O exemplo é genérico: adapte consulta, limites e labels às métricas e aos serviços do seu ambiente.

Uma regra define o que monitorar e quando o alerta deve disparar. Os labels descrevem o alerta e permitem que uma política escolha o contact point adequado, como Jira, Telegram ou e-mail.

Pré-requisitos

• A métrica ou série temporal que representa a condição está sendo coletada e pode ser consultada no EO.
• Você conhece o limite que caracteriza uma condição de alerta e o tempo pelo qual ela deve permanecer ativa antes de disparar.
• Você sabe quais labels a política de notificação espera, por exemplo team=plataforma e severity=critical.
• Se a regra deve usar uma política, essa política e seu contact point já estão configurados. Consulte Políticas de notificação.

Exemplo

Neste exemplo, uma regra representa uma condição crítica de um serviço da equipe de plataforma. Os valores são ilustrativos e devem ser substituídos pelos nomes e padrões usados no seu ambiente.

Criando a regra

1. No menu do EO, acesse Alerts & IRM → Alert rules e escolha + New alert rule. Se a navegação do seu ambiente tiver nomes diferentes, procure a área de regras de alerta do Grafana.
2. Informe um nome que identifique o serviço e a condição, como API - serviço indisponível. O nome também identifica as instâncias de alerta derivadas da regra.
3. Selecione a fonte de dados e escreva a consulta que representa a condição monitorada. Use Builder para montar a consulta visualmente ou Code para inseri-la diretamente, quando disponíveis.
4. Configure a condição que faz a regra disparar, como um valor acima ou abaixo de um limite. Use Preview para conferir o resultado da consulta e validar se a condição se comporta como esperado.
5. Se a regra permitir vários passos de consulta ou expressões, defina qual consulta ou expressão será a condição de alerta. Use a visualização prévia antes de avançar.

Organizando a regra com labels

1. Escolha a pasta onde a regra ficará organizada.
2. Na seção Labels, adicione os pares de chave e valor que descrevem o alerta. Para o exemplo, use team=plataforma, service=api, severity=critical e environment=production.
3. Compare os nomes e valores com as condições da política de notificação. A chave e o valor precisam coincidir com a rota que você deseja atingir.
4. Evite criar labels com nomes diferentes para o mesmo conceito entre regras, como alternar entre team e squad sem que as políticas contemplem ambos.

Labels podem existir na série retornada pela consulta e também ser definidos na configuração da regra. Confira a prévia de roteamento para entender os labels que serão usados no seu ambiente.

Configurando avaliação e estados

1. Selecione um grupo de avaliação existente ou crie um novo. O intervalo do grupo determina com que frequência as regras são avaliadas.
2. Defina o Pending period conforme a tolerância do serviço a oscilações. A condição precisa permanecer ativa durante esse período para que a regra passe de Pending para Firing.
3. Se necessário, configure Keep firing for para evitar que a regra deixe de disparar imediatamente quando a condição melhorar.
4. Em Configure no data and error handling, escolha como a regra deve se comportar quando uma avaliação retornar ausência de dados ou erro. Decida esses estados conforme o significado operacional de cada situação para o serviço.

Uma avaliação pausada impede a criação de novas instâncias enquanto a regra não está sendo avaliada. Isso difere de uma janela de silêncio, que pode suprimir notificações sem interromper a avaliação da regra.

Adicionando informações para quem recebe o alerta

Na seção de mensagem ou anotações da regra, preencha informações que ajudem a identificar e investigar a condição:

• Summary: frase curta com o sintoma, por exemplo A API está indisponível.
• Description: explique o que a condição monitora e o que foi observado.
• Runbook URL: inclua o link para o procedimento de resposta, quando houver.
• Dashboard ou painel: vincule a visualização que ajuda a confirmar e investigar o alerta, se essa opção estiver disponível.

As anotações aparecem na notificação e devem ajudar a equipe a entender o alerta sem depender do nome da regra sozinho.

Usando a política de notificação

1. Na configuração de notificações da regra, selecione o modo avançado ou a opção que usa Notification policies.
2. Confira se a regra não está configurada para enviar diretamente a um contact point quando a intenção é usar a árvore de políticas. O envio direto para um contact point não passa pelo roteamento dessa árvore.
3. Use Preview routing, quando disponível, para conferir qual política corresponde aos labels da regra.
4. Confira se a rota aponta para o contact point esperado e salve a regra.

Se a versão do EO não mostrar o modo avançado ou a prévia de roteamento, confirme com a equipe administradora do ambiente como a configuração de alerting está habilitada antes de publicar ou alterar a regra.

Validando a regra e a notificação

Faça a validação inicial em uma regra de teste ou escopo controlado.

1. Use Preview na consulta para verificar se ela retorna os dados e unidades esperados.
2. Confira os labels da regra e compare-os com as condições da política.
3. Use Preview routing para verificar a política que receberia a notificação. Essa prévia valida o roteamento, mas não comprova a entrega ao contact point.
4. Salve a regra e verifique se ela aparece na lista de Alert rules com a pasta, estado e labels esperados.
5. Gere uma condição de teste controlada ou aguarde uma ocorrência aprovada e confira o estado da regra e o histórico de notificações.
6. Confirme o recebimento no destino. Para Jira, combine previamente um projeto apropriado para testes: uma notificação de teste pode criar uma issue real.

Resolução de problemas

• A consulta não retorna dados: confirme a fonte de dados, o intervalo de tempo e os labels ou filtros incluídos na consulta.
• A regra nunca passa para Firing: confira o limite, o resultado da consulta, o intervalo de avaliação e o Pending period.
• A regra dispara, mas usa o contact point padrão: confirme que a regra está usando políticas de notificação e que seus labels correspondem à rota.
• A prévia não mostra a política esperada: confira o Alertmanager, os labels efetivos da regra e as condições da política.
• A regra retorna No data ou Error: verifique a disponibilidade da fonte de dados e a configuração de tratamento desses estados.
• O roteamento está correto, mas não há entrega: consulte o histórico de notificações e o estado do contact point.

Glossário

Alert instance: ocorrência de uma regra para uma série ou conjunto de labels específico.

Evaluation group: grupo que determina quando e com que intervalo as regras associadas são avaliadas.

Label: par de chave e valor associado à regra ou ao alerta, usado para classificar e rotear notificações.

Pending period: tempo que a condição precisa permanecer ativa antes da instância mudar para Firing.

Annotation: informação descritiva apresentada na notificação, como resumo, descrição ou link para runbook.

Referências

• Alertas na Elven Observability
• Políticas de notificação
• Documentação do Grafana: criar regras de alerta gerenciadas pelo Grafana
• Documentação do Grafana: consultas e condições de alertas