Condizioni dei canali - filtraggio intelligente delle notifiche

Le condizioni dei canali sono espressioni potenti che stabiliscono quando inviare le notifiche. Impostando delle condizioni sul tuo canale puoi filtrare le notifiche in base al contenuto delle variabili o degli header HTTP, così chi è iscritto riceve solo gli avvisi che gli servono davvero. È un passaggio fondamentale per ridurre l'affaticamento da avvisi e mantenere alto il rapporto segnale/rumore del tuo sistema di notifiche.

Considera le condizioni come il guardiano delle tue notifiche: valutano i dati del trigger in arrivo e lasciano passare una notifica solo quando vengono soddisfatti criteri precisi.

Capire le condizioni

Le condizioni sono espressioni che restituiscono true oppure false. Quando un canale viene attivato:

• Se le condizioni non sono impostate (campo vuoto), le notifiche vengono inviate a tutti gli iscritti.
• Se le condizioni sono impostate, le notifiche vengono inviate solo quando l'espressione risulta true.

Scrivere le condizioni

Le condizioni si scrivono come espressioni, senza le parentesi {{}} che si usano nei modelli. Per esempio:

status == "active"

Questa condizione permette l'invio delle notifiche solo quando la variabile status vale "active".

Casi d'uso comuni

Ecco alcuni esempi pratici di come puoi usare le condizioni:

Controlli di base sulle variabili

amount > 100

Notifica solo quando la variabile "amount" è maggiore di 100.

message != ""

Notifica solo quando la variabile "message" non è vuota.

isUrgent == true

Notifica solo quando la variabile "isUrgent" è vera.

Controllare gli header HTTP

Puoi accedere agli header HTTP tramite la variabile speciale header:

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

Notifica solo quando un header di origine personalizzato corrisponde esattamente a "grafana".

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

Notifica solo quando il tipo di contenuto è JSON.

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

Notifica solo quando un header di priorità personalizzato vale "high".

Condizioni complesse

Puoi combinare più condizioni con gli operatori logici:

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

Notifica solo quando la temperatura supera 30 oppure la pressione supera 100, e lo stato è "monitoring".

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

Notifica solo per errori critici o di livello alto nell'ambiente di produzione.

Operatori supportati

Nelle espressioni condizionali sono supportati questi operatori:

Variabili delle condizioni

Quando un canale viene attivato tramite webhook, puoi accedere a:

1. Parametri di query dell'URL
2. Body JSON delle richieste POST
3. Header HTTP tramite l'oggetto header

Per i trigger via email puoi accedere a:

• from: l'indirizzo del mittente
• to: l'indirizzo del destinatario
• subject: l'oggetto dell'email
• text: il corpo del messaggio in testo semplice
• html: il corpo del messaggio in HTML

Variabili di sistema per data e ora (UTC)

Queste variabili di sola lettura sono sempre disponibili sia nelle condizioni sia nei modelli. Tutti i valori sono calcolati in UTC.

I valori seguenti vengono inseriti direttamente (in forma piatta) e si possono usare per nome:

• year: anno a 4 cifre (numero)
• month: numero del mese 1–12
• dayOfMonth: giorno del mese 1–31
• dayOfWeek: giorno della settimana 0–6 (domenica = 0)
• hour: ora del giorno 0–23
• minute: minuto 0–59
• second: secondo 0–59
• date: stringa YYYY-MM-DD
• time: stringa HH:mm:ss
• iso: ora corrente come stringa ISO‑8601 (es. 2025-05-06T12:34:56.789Z)

Altri valori sono disponibili solo nel namespace sys. (non vengono inseriti come nomi piatti):

• sys.timezone: la stringa costante "UTC"
• sys.now: ora corrente come stringa ISO‑8601 (lo stesso valore di iso)
• sys.epochMs: millisecondi dall'epoch Unix (numero)
• sys.epochSeconds: secondi dall'epoch Unix (numero)
• sys.monthName: nome del mese January–December
• sys.dayOfWeekName: nome del giorno Sunday–Saturday

Il namespace sys. replica anche tutti i valori piatti (es. sys.year, sys.hour).

Esempi:

// Giorni feriali tra le 09:00 e le 17:00 UTC
hour >= 9 && hour < 17 && dayOfWeek >= 1 && dayOfWeek <= 5

// Solo nel fine settimana
dayOfWeek == 0 || dayOfWeek == 6

// Primo giorno del mese, all'ora esatta
dayOfMonth == 1 && minute == 0

Best practice

Parti da qualcosa di semplice

Comincia con condizioni di base e aggiungi complessità solo quando serve:

Fase 1: parti da una condizione singola

temperature > 30

Fase 2: aggiungi gli operatori logici

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

Fase 3: aggiungi la logica annidata

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

Prova a fondo

Metti alla prova le condizioni con input diversi per assicurarti che si comportino come previsto:

1. Prova con valori normali - verifica che le condizioni funzionino negli scenari attesi
2. Prova i casi limite - cosa succede esattamente al valore di soglia?
3. Prova con variabili mancanti - come si comporta la condizione quando il dato non c'è?
4. Prova con tipi inattesi - e se un numero arriva come stringa?
5. Usa webhook di prova - invia trigger di test con combinazioni di dati diverse

Documenta le tue condizioni

Aggiungi dei commenti nel campo note del canale per spiegare le condizioni complesse:

Nota del canale:
Condizione: (cpu > 80 && memory > 90) || diskSpace < 10

Questa condizione invia avvisi quando:
- La CPU è sopra l'80% E la memoria è sopra il 90%
- OPPURE lo spazio su disco scende sotto i 10 GB

Così i tuoi colleghi capiscono la logica degli avvisi senza dover decifrare l'espressione.

Tieni conto dei casi limite

Considera le variabili mancanti o i valori inattesi:

• Variabili mancanti: le variabili non definite valgono vuoto/false, quindi assicurati che la tua logica lo gestisca
• Confronti numerici: <, >, <= e >= convertono entrambi gli operandi con Number(), quindi il confronto è numerico e non lessicale. "100" > "20" è true (100 > 20), non segue l'ordine alfabetico.
• Valori non numerici: se uno dei due lati di un confronto <, >, <= o >= non è un numero, Number() produce NaN e il confronto è sempre false.
• Uguaglianza e confronto: == e != usano l'uguaglianza debole (quindi count == "5" corrisponde al numero 5), mentre gli operatori di ordinamento confrontano sempre come numeri.
• Maiuscole e minuscole: status == "Active" è diverso da status == "active"

Evita le tempeste di avvisi

Usa le condizioni per non farti sommergere di notifiche per problemi passeggeri:

errorCount > 5    # Non semplicemente errorCount > 0
cpuUsage > 90     # Non cpuUsage > 50
failureRate > 0.1 # Non semplicemente hasFailures

Scegli soglie adeguate per ridurre il rumore senza perderti gli eventi critici.

Filtra per orario lavorativo

Combina la gravità con condizioni basate sull'ora:

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

In questo modo gli avvisi critici arrivano 24 ore su 24, mentre quelli ad alta priorità solo durante l'orario lavorativo.

Sfrutta i controlli sugli header

Verifica l'origine dei webhook per evitare spam o attivazioni non autorizzate:

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

Controllare la provenienza della richiesta aggiunge un livello di sicurezza.

Esempi dal mondo reale

Monitoraggio dei server - avvisi progressivi

# Avvisa solo quando la CPU resta alta a lungo, non per picchi passeggeri
cpu > 80 && duration >= 300

E-commerce - ordini di valore elevato

# Notifica solo per ordini sopra i 500 $ o segnalati come sospetta frode
orderAmount > 500 || isFraudSuspected == true

Sviluppo - build fallite critiche

# Avvisa solo per i fallimenti sul branch principale o per i deploy falliti
(branch == "main" || branch == "master") && status == "failed"

IoT - monitoraggio ambientale

# Temperature estreme fuori dall'intervallo accettabile
temperature < 15 || temperature > 28

Sicurezza - tentativi di accesso falliti

# Più accessi falliti dallo stesso IP in poco tempo
failedAttempts >= 3 && timeSinceFirst < 300

CI/CD - monitoraggio dei deploy

# Notifica solo per i deploy in produzione o i fallimenti in staging
(environment == "production") || (environment == "staging" && status == "failed")

Trading - avvisi sui prezzi

# Movimenti di prezzo significativi oltre la soglia
(priceChange > 5 || priceChange < -5) && volume > 1000000

Assistenza - violazioni degli SLA

# Ticket vicini allo SLA o che l'hanno già superato
ticketAge > slaThreshold || priority == "urgent"

Pattern ricorrenti

Avvisi basati su soglie

value > threshold
percentage >= 90
count < minimumRequired

Filtri basati sullo stato

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

Filtri per finestra temporale

# Solo orario lavorativo (9:00 - 17:00 UTC, dal lunedì al venerdì)
hour >= 9 && hour < 17 && dayOfWeek >= 1 && dayOfWeek <= 5

# Solo fuori orario
hour < 9 || hour >= 17 || dayOfWeek == 0 || dayOfWeek == 6

# Finestre di manutenzione nel fine settimana
(dayOfWeek == 0 || dayOfWeek == 6) && hour >= 2 && hour < 6

Condizioni multi-fattore

# Combina più criteri
severity == "high" && environment == "production" && region == "us-east-1"

# Gravità critica OPPURE gravità alta in produzione
severity == "critical" || (severity == "high" && environment == "production")

Confronto di stringhe

# Corrispondenza esatta (non esiste un operatore "contains")
status == "error"
errorType == "database"

# Confronto tra stringhe
environment == "production"
username != "test-user"

Combinare le condizioni con i modelli

Le condizioni e i modelli lavorano insieme per creare notifiche intelligenti e contestuali:

Condizione (filtra quali trigger inviano una notifica):

temperature > 30 || humidity > 80

Modello (formatta il contenuto della notifica):

Titolo: avviso ambientale in {{location}}
Corpo: temp.: {{temperature}}°C, umidità: {{humidity}}%

Questa separazione ti permette di:

1. Filtrare le notifiche indesiderate con le condizioni
2. Formattare le notifiche importanti con i modelli
3. Adattare il contenuto della notifica in base alla gravità

Scopri di più sulla sintassi e sulle funzionalità dei modelli.

Fare debug delle condizioni

Se le condizioni non si comportano come previsto:

1. Semplifica la condizione - prova un confronto alla volta
2. Controlla i nomi delle variabili - devono corrispondere esattamente (maiuscole e minuscole comprese)
3. Verifica i tipi di dato - usa webhook di prova per confermare il tipo delle variabili
4. Verifica la logica booleana - scomponi le condizioni complesse in parti più piccole
5. Rivedi la precedenza degli operatori - usa le parentesi per chiarire l'intento
6. Controlla i refusi - header["content-type"], non header["Content-Type"]

Documentazione correlata

• Guida ai modelli - formatta il contenuto delle notifiche con le variabili
• Integrazione webhook - passa le variabili tramite richieste HTTP
• Trigger via email - le variabili dei trigger via email
• Guida introduttiva - configura il tuo primo canale con condizioni

Prossimi passi

Ora che sai come funzionano le condizioni:

• Crea avvisi di monitoraggio intelligenti - filtra gli avvisi dell'infrastruttura
• Configura le notifiche CI/CD - avvisa solo per gli eventi di build importanti
• Imposta avvisi basati sull'ora - filtra per orario lavorativo
• Esplora tutte le funzionalità - scopri cos'altro può fare Echobell

---

Usando le condizioni in modo efficace puoi ridurre il rumore delle notifiche e fare in modo che gli iscritti ricevano solo avvisi rilevanti e su cui possono agire davvero. Parti da condizioni semplici e costruisci una logica di filtro più sofisticata man mano che le tue esigenze crescono.