Condições de canal - Filtragem inteligente de notificações

As condições de canal são expressões poderosas que determinam quando as notificações devem ser enviadas. Ao definir condições no seu canal, você pode filtrar notificações com base no conteúdo de variáveis ou de cabeçalhos HTTP, garantindo que os inscritos recebam apenas alertas relevantes. Isso é essencial para reduzir a fadiga de alertas e manter uma alta relação sinal-ruído no seu sistema de notificações.

Pense nas condições como o porteiro das suas notificações: elas avaliam os dados recebidos do gatilho e só deixam a notificação passar quando critérios específicos são atendidos.

Entendendo as condições

As condições são expressões que resultam em true ou false. Quando um canal é acionado:

• Se as condições não estiverem definidas (vazias), as notificações são enviadas a todos os inscritos.
• Se as condições estiverem definidas, as notificações só são enviadas quando a expressão resulta em true.

Como escrever condições

As condições são escritas como expressões, sem os delimitadores {{}} usados nos modelos. Por exemplo:

status == "active"

Essa condição só permite o envio de notificações quando a variável status for igual a "active".

Casos de uso comuns

Veja alguns exemplos práticos de como você pode usar condições:

Verificações básicas de variáveis

amount > 100

Notificar apenas quando a variável "amount" for maior que 100.

message != ""

Notificar apenas quando a variável "message" não estiver vazia.

isUrgent == true

Notificar apenas quando a variável "isUrgent" for verdadeira.

Verificação de cabeçalhos HTTP

Você pode acessar os cabeçalhos HTTP usando a variável especial header:

header["x-webhook-source"] == "grafana"

Notificar apenas quando um cabeçalho de origem personalizado for exatamente igual a "grafana".

header["content-type"] == "application/json"

Notificar apenas quando o tipo de conteúdo for JSON.

header["x-priority"] == "high"

Notificar apenas quando um cabeçalho de prioridade personalizado estiver definido como "high".

Condições complexas

Você pode combinar várias condições usando operadores lógicos:

(temperature > 30 || pressure > 100) && status == "monitoring"

Notificar apenas quando a temperatura ultrapassar 30 ou a pressão ultrapassar 100, e o status for "monitoring".

environment == "production" && (errorLevel == "critical" || errorLevel == "high")

Notificar apenas erros críticos ou de alto nível no ambiente de produção.

Operadores suportados

Os seguintes operadores são suportados nas expressões de condição:

Variáveis de condição

Quando um canal é acionado por webhook, você pode acessar:

1. Parâmetros de consulta da URL
2. Corpo JSON de requisições POST
3. Cabeçalhos HTTP por meio do objeto header

Nos gatilhos por e-mail, você pode acessar:

• from: O endereço do remetente do e-mail
• to: O endereço do destinatário
• subject: A linha de assunto do e-mail
• text: O conteúdo do corpo em texto simples
• html: O conteúdo do corpo em HTML

Variáveis de hora do sistema (UTC)

Essas variáveis somente leitura estão sempre disponíveis tanto nas condições quanto nos modelos. Todos os valores são calculados em UTC.

Os valores a seguir são injetados diretamente (de forma plana) e podem ser usados pelo nome:

• year: Ano com 4 dígitos (número)
• month: Número do mês 1–12
• dayOfMonth: Dia do mês 1–31
• dayOfWeek: Dia da semana 0–6 (domingo = 0)
• hour: Hora do dia 0–23
• minute: Minuto 0–59
• second: Segundo 0–59
• date: String YYYY-MM-DD
• time: String HH:mm:ss
• iso: Hora atual como string ISO‑8601 (ex.: 2025-05-06T12:34:56.789Z)

Outros valores estão disponíveis apenas no namespace sys. (eles não são injetados como nomes planos):

• sys.timezone: A string constante "UTC"
• sys.now: Hora atual como string ISO‑8601 (mesmo valor que iso)
• sys.epochMs: Milissegundos desde a época Unix (número)
• sys.epochSeconds: Segundos desde a época Unix (número)
• sys.monthName: Nome do mês January–December
• sys.dayOfWeekName: Nome do dia Sunday–Saturday

O namespace sys. também espelha todos os valores planos (ex.: sys.year, sys.hour).

Exemplos:

// Dias úteis das 09:00 às 17:00 UTC
hour >= 9 && hour < 17 && dayOfWeek >= 1 && dayOfWeek <= 5

// Somente nos fins de semana
dayOfWeek == 0 || dayOfWeek == 6

// Primeiro dia do mês na hora cheia
dayOfMonth == 1 && minute == 0

Boas práticas

Comece simples

Comece com condições básicas e aumente a complexidade conforme necessário:

Fase 1: comece com condições únicas

temperature > 30

Fase 2: adicione operadores lógicos

temperature > 30 && location == "server-room"

Fase 3: adicione lógica aninhada

(temperature > 30 || humidity > 80) && location == "server-room" && status == "monitoring"

Teste minuciosamente

Teste suas condições com diferentes entradas para garantir que funcionem como esperado:

1. Teste com valores normais - Verifique se as condições funcionam nos cenários esperados
2. Teste os casos-limite - O que acontece exatamente no valor do limiar?
3. Teste com variáveis ausentes - Como a condição lida com dados que não chegaram?
4. Teste com tipos inesperados - E se um número for enviado como string?
5. Use webhooks de teste - Envie gatilhos de teste com diferentes combinações de dados

Documente suas condições

Adicione comentários no campo de notas do seu canal para explicar condições complexas:

Nota do canal:
Condição: (cpu > 80 && memory > 90) || diskSpace < 10

Esta condição dispara alertas quando:
- A CPU está acima de 80% E a memória está acima de 90%
- OU quando o espaço em disco cai abaixo de 10 GB

Isso ajuda os integrantes do time a entender a lógica do alerta sem precisar interpretar a expressão.

Considere os casos-limite

Leve em conta variáveis ausentes ou valores inesperados:

• Variáveis ausentes: variáveis indefinidas são avaliadas como vazias/falsas - garanta que sua lógica trate isso
• Comparações numéricas: <, >, <= e >= convertem os dois operandos com Number(), então a comparação é numérica, e não lexical. "100" > "20" é true (100 > 20), e não ordem lexical.
• Valores não numéricos: se um dos lados de uma comparação <, >, <= ou >= não for um número, Number() produz NaN e a comparação é sempre false.
• Igualdade vs. comparação: == e != usam igualdade frouxa (portanto count == "5" corresponde ao número 5), enquanto os operadores de ordenação sempre comparam como números.
• Diferenciação de maiúsculas e minúsculas: status == "Active" é diferente de status == "active"

Evite tempestades de alertas

Use condições para evitar uma enxurrada de notificações causada por problemas passageiros:

errorCount > 5    # Não apenas errorCount > 0
cpuUsage > 90     # Não cpuUsage > 50
failureRate > 0.1 # Não apenas hasFailures

Combine com limiares adequados para reduzir o ruído sem perder eventos críticos.

Use a filtragem por horário comercial

Combine a severidade com condições baseadas em tempo:

severity == "critical" || (severity == "high" && hour >= 9 && hour < 17)

Isso envia alertas críticos 24 horas por dia, 7 dias por semana, mas envia os alertas de alta prioridade apenas durante o horário comercial.

Aproveite as verificações de cabeçalho

Valide as origens dos webhooks para evitar spam ou acionamentos não autorizados:

header["x-webhook-source"] == "grafana" || header["x-webhook-source"] == "prometheus"

Isso acrescenta uma camada de segurança ao verificar a origem da requisição.

Exemplos do mundo real

Monitoramento de servidores - Alertas progressivos

# Alertar apenas quando a CPU estiver alta de forma consistente, não em picos passageiros
cpu > 80 && duration >= 300

E-commerce - Pedidos de alto valor

# Notificar apenas pedidos acima de US$ 500 ou marcados como suspeita de fraude
orderAmount > 500 || isFraudSuspected == true

Desenvolvimento - Falhas críticas de build

# Alertar apenas para falhas na branch principal ou implantações que falharam
(branch == "main" || branch == "master") && status == "failed"

IoT - Monitoramento ambiental

# Temperaturas extremas fora da faixa aceitável
temperature < 15 || temperature > 28

Segurança - Tentativas de login malsucedidas

# Várias falhas de login do mesmo IP em pouco tempo
failedAttempts >= 3 && timeSinceFirst < 300

CI/CD - Acompanhamento de implantações

# Notificar apenas em deploys de produção ou falhas em staging
(environment == "production") || (environment == "staging" && status == "failed")

Trading - Alertas de preço

# Movimentos de preço significativos acima do limiar
(priceChange > 5 || priceChange < -5) && volume > 1000000

Suporte - Violações de SLA

# Chamados próximos do SLA ou que já o ultrapassaram
ticketAge > slaThreshold || priority == "urgent"

Padrões comuns de condição

Alertas baseados em limiar

value > threshold
percentage >= 90
count < minimumRequired

Filtragem baseada em status

status == "error" || status == "critical"
state != "healthy"
isActive == true

Filtragem por janela de tempo

# Apenas horário comercial (9h às 17h UTC, de segunda a sexta)
hour >= 9 && hour < 17 && dayOfWeek >= 1 && dayOfWeek <= 5

# Apenas fora do horário comercial
hour < 9 || hour >= 17 || dayOfWeek == 0 || dayOfWeek == 6

# Janelas de manutenção no fim de semana
(dayOfWeek == 0 || dayOfWeek == 6) && hour >= 2 && hour < 6

Condições com múltiplos fatores

# Combine vários critérios
severity == "high" && environment == "production" && region == "us-east-1"

# Crítico OU produção com severidade alta
severity == "critical" || (severity == "high" && environment == "production")

Correspondência de strings

# Correspondência exata (não existe operador "contains")
status == "error"
errorType == "database"

# Comparação de strings
environment == "production"
username != "test-user"

Combinando condições com modelos

As condições e os modelos funcionam juntos para criar notificações inteligentes e contextuais:

Condição (filtra quais gatilhos enviam notificações):

temperature > 30 || humidity > 80

Modelo (formata o conteúdo da notificação):

Título: Alerta ambiental em {{location}}
Corpo: Temp.: {{temperature}}°C, Umidade: {{humidity}}%

Essa separação permite que você:

1. Filtre notificações indesejadas com condições
2. Formate notificações importantes com modelos
3. Adapte o conteúdo da notificação conforme a severidade

Saiba mais sobre a sintaxe e os recursos dos modelos.

Depurando condições

Se as condições não estiverem funcionando como esperado:

1. Simplifique a condição - Teste apenas uma comparação por vez
2. Confira os nomes das variáveis - Verifique se correspondem exatamente (diferencia maiúsculas de minúsculas)
3. Verifique os tipos de dados - Use webhooks de teste para confirmar os tipos das variáveis
4. Teste a lógica booleana - Divida condições complexas em partes menores
5. Revise a precedência dos operadores - Use parênteses para deixar a intenção clara
6. Procure erros de digitação - header["content-type"], e não header["Content-Type"]

Documentação relacionada

• Guia de modelos - Formate o conteúdo das notificações com variáveis
• Integração com webhooks - Passe variáveis por meio de requisições HTTP
• Gatilhos por e-mail - Variáveis dos gatilhos por e-mail
• Primeiros passos - Configure seu primeiro canal com condições

Próximos passos

Agora que você entende as condições:

• Crie alertas inteligentes de monitoramento - Filtre alertas de infraestrutura
• Configure notificações de CI/CD - Alerte apenas em eventos de build importantes
• Configure alertas baseados em tempo - Filtragem por horário comercial
• Explore todos os recursos - Descubra o que mais o Echobell pode fazer

---

Ao usar condições de forma eficaz, você reduz o ruído das notificações e garante que os inscritos recebam apenas os alertas que são relevantes e acionáveis para eles. Comece com condições simples e vá construindo aos poucos uma lógica de filtragem mais sofisticada conforme suas necessidades evoluem.