Integrazione Grafana - avvisi di infrastruttura

Grafana è una diffusa soluzione open source di analisi e monitoraggio, usata da migliaia di organizzazioni per visualizzare metriche, log e trace. Integrando Grafana con Echobell ricevi una notifica immediata ogni volta che le tue metriche fanno scattare un avviso: uso elevato della CPU, pressione sulla memoria, servizi non funzionanti o qualsiasi altra condizione monitorata.

Questa guida completa ti accompagna nella configurazione degli avvisi Grafana con Echobell, dalle impostazioni di base alle strategie avanzate di gestione degli avvisi.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Un account Echobell con almeno un canale creato (Inizia da qui)
• Accesso a un'istanza Grafana (consigliata la versione 8.0 o successiva, 9.0+ per la massima compatibilità)
• Permessi di amministrazione per configurare le notifiche di avviso in Grafana (di norma serve il ruolo Admin o Editor)
• Conoscenza di base delle dashboard e delle metriche di Grafana
• Familiarità con la tua infrastruttura di monitoraggio e con i requisiti degli avvisi

Panoramica della configurazione

Il processo di integrazione si articola in cinque passaggi principali e richiede in genere 10-15 minuti:

1. Crea un canale Echobell - Prepara un canale dedicato agli avvisi Grafana
2. Configura i modelli di notifica - Definisci come appariranno gli avvisi sul tuo dispositivo
3. Recupera l'URL del webhook - Ottieni l'endpoint webhook univoco del tuo canale
4. Imposta il contact point in Grafana - Configura Grafana per inviare gli avvisi a Echobell
5. Crea le regole di avviso in Grafana - Stabilisci quali condizioni attivano le notifiche

A configurazione completata, gli avvisi arrivano automaticamente da Grafana al tuo dispositivo in tempo reale.

Guida passo passo

{{alertName}} - {{status}}

🔔 Avviso: {{alertName}}
📊 Metrica: {{metric}}
📈 Valore: {{value}}
⏰ Ora: {{time}}
ℹ️ Messaggio: {{message}}

{
  "alertName": "{{ .alertName }}",
  "status": "{{ .status }}",
  "metric": "{{ .metric }}",
  "value": "{{ .value }}",
  "time": "{{ .time }}",
  "message": "{{ .message }}",
  "externalLink": "{{ .dashboardURL }}"
}

Test dell'integrazione

Per verificare la configurazione:

1. Crea una regola di avviso di prova con una condizione che scatti in fretta
2. Attendi che la condizione si verifichi
3. Controlla nell'app Echobell che sia arrivata la notifica dell'avviso
4. Verifica che tutte le variabili dell'avviso siano visualizzate correttamente
5. Tocca la notifica per aprire la dashboard Grafana collegata

Tipi di notifica per gli avvisi

Quando ti iscrivi al canale degli avvisi Grafana, configura questi tipi di notifica fondamentali:

• Usa Urgente per gli avvisi di sistema critici e le notifiche di emergenza
• Usa Chiamata per interruzioni gravi, superamenti critici di soglia o avvisi di emergenza
• Usa Normale per gli avvisi informativi standard e le notifiche di routine

Best practice per la gestione degli avvisi

Organizzazione dei modelli di avviso

Mantieni i modelli di avviso chiari e coerenti tra i canali:

Titolo: {{alertName}} - {{status}}
Corpo:
Server: {{instance}}
Metrica: {{metric}}
Attuale: {{value}}
Soglia: {{threshold}}

• Usa una formattazione strutturata - Organizza le informazioni con etichette chiare
• Includi le informazioni essenziali - Nome della metrica, valore, soglia, sistema coinvolto
• Usa le emoji con parsimonia - 🚨 per i casi critici, ⚠️ per gli avvertimenti, ✅ per i problemi risolti
• Mantieni i titoli concisi - Punta a 5-8 parole che comunichino subito il problema
• Prova i modelli - Invia avvisi di test per controllare la formattazione prima di andare in produzione

Configurazione degli avvisi critici

Imposta soglie adeguate per evitare l'affaticamento da notifiche:

• Evita gli avvisi eccessivi - Fissa le soglie su livelli su cui puoi agire, non su livelli semplicemente interessanti
• Usa l'isteresi - Configura soglie diverse per l'attivazione e per il rientro
• Raggruppa gli avvisi correlati - Unisci le condizioni collegate in un'unica regola
• Imposta intervalli di valutazione adeguati - Trova l'equilibrio tra reattività e rumore
• Considera le finestre temporali - Richiedi più verifiche della condizione prima di inviare l'avviso

Esempio di strategia per le soglie:

# Male: avviso al 50% di CPU (troppo sensibile)
cpu_usage > 50

# Meglio: avviso all'80% per 5 minuti
avg_over_time(cpu_usage[5m]) > 80

# Ottimo: avvisi progressivi
# Avvertimento al 70% prolungato, critico al 90%

Usa nomi di avviso significativi

Dai agli avvisi nomi descrittivi, che comunichino subito:

• Che cosa viene monitorato (CPU, memoria, disco)
• Dove sta succedendo (produzione, staging, istanza specifica)
• Perché è importante (servizio rivolto agli utenti, database critico)

Buoni esempi:

• "Database di produzione - uso elevato del pool di connessioni"
• "API Gateway - degrado dei tempi di risposta"
• "Worker node 3 - spazio su disco critico"

Da evitare:

• "Avviso 1", "Avviso di test", "CPU alta"

Fornisci contesto sufficiente

Il messaggio dell'avviso dovrebbe rispondere a queste domande:

• Che cosa è successo? La condizione specifica che è scattata
• Dove? Quale sistema, servizio o istanza
• Quanto è grave? Valore attuale rispetto alla soglia
• Quando? L'ora dell'avviso
• E adesso? Link alla dashboard o al runbook pertinente

Configura i livelli di priorità

Usa i tipi di notifica di Echobell in modo strategico:

• Normale: avvisi informativi, notifiche di risoluzione, segnalazioni non urgenti
• Urgente: avvisi importanti da gestire nel giro di poche ore
• Chiamata: problemi critici in produzione che richiedono un intervento immediato

Associa i livelli di gravità di Grafana ai tipi di notifica:

Critico + produzione → Chiamata
Alto + produzione → Urgente
Medio → Urgente
Basso → Normale
Info/Risolto → Normale

Sicurezza degli avvisi

Proteggi la tua infrastruttura di monitoraggio:

• Tieni segreti gli URL dei webhook - Permettono di inviare notifiche senza autenticazione
• Usa variabili d'ambiente - Non scrivere gli URL direttamente nei file di provisioning di Grafana
• Ruota i webhook periodicamente - Soprattutto quando qualcuno lascia il team
• Monitora la consegna dei webhook - Tieni traccia delle consegne fallite e indaga sulle anomalie
• Controlla le configurazioni degli avvisi - Rivedi con regolarità chi può modificarli
• Convalida le fonti degli avvisi - Usa l'autenticazione integrata di Grafana per i contact point

Gestione del ciclo di vita degli avvisi

Mantieni gli avvisi in ordine:

1. Revisione periodica - Controlla gli avvisi ogni trimestre ed elimina le regole obsolete
2. Documenta gli avvisi - Aggiungi descrizioni che spieghino perché ogni avviso esiste
3. Tieni traccia dello storico - Osserva quali avvisi scattano più spesso
4. Affina le soglie - Regolale in base ai dati storici e al tasso di falsi positivi
5. Archivia gli avvisi vecchi - Disattiva le regole dei servizi in dismissione senza cancellarle
6. Usa il controllo di versione - Sfrutta il provisioning di Grafana per tracciare le modifiche agli avvisi

Considerazioni sulle prestazioni

• Evita le tempeste di avvisi - Configura raggruppamento e tempistiche adeguati
• Usa le notification policy - Instrada i diversi livelli di gravità verso i canali giusti
• Imposta gli intervalli di attesa e di ripetizione - Evita notifiche duplicate
• Raggruppa gli avvisi simili - Riduci il volume di notifiche aggregandoli
• Tieni conto dell'ora del giorno - Usa le condizioni per filtrare gli orari lavorativi

Esempi concreti

Avviso di CPU elevata

Titolo: {{instance}} CPU critica
Corpo: uso della CPU: {{cpu_percent}}%
Durata: {{duration}}
Ora: {{time}}
Dashboard: {{dashboard_url}}

Pressione sulla memoria

Titolo: avviso memoria - {{hostname}}
Corpo: disponibile: {{available_mb}}MB ({{percent_free}}%)
Soglia: {{threshold_mb}}MB
Azione: controlla i processi che consumano più memoria

Servizio non raggiungibile

Titolo: 🚨 {{service_name}} non raggiungibile
Corpo: controllo di integrità fallito
Ultimo esito positivo: {{last_successful_check}}
Impatto: {{affected_users}} utenti coinvolti
Runbook: {{runbook_url}}

Casi d'uso comuni

Monitoraggio dell'infrastruttura

• Soglie di utilizzo di CPU, memoria e disco
• Throughput di rete e perdita di pacchetti
• Disponibilità dei servizi e controlli di integrità
• Stato di container e pod

Prestazioni delle applicazioni

• Degrado dei tempi di risposta
• Aumento del tasso di errore
• Esaurimento del pool di connessioni al database
• Profondità delle code e ritardi di elaborazione

Metriche di business

• Anomalie nel volume delle transazioni
• Cali dei ricavi al minuto
• Variazioni del numero di utenti attivi
• Rate limit delle API vicini alla soglia

Monitoraggio della sicurezza

• Tentativi di autenticazione falliti
• Pattern di accesso insoliti
• Avvisi di scadenza dei certificati
• Violazioni delle regole del firewall

Scopri altre strategie di integrazione nel nostro articolo sulle notifiche con chiamata per Grafana.

Risoluzione dei problemi

Se non ricevi gli avvisi, segui questi passaggi diagnostici:

Il webhook non attiva le notifiche

1. Verifica di aver copiato correttamente l'URL del webhook

   • Apri il tuo canale Echobell → Triggers → Webhook
   • Copia l'URL completo, compreso https://hook.echobell.one/t/
   • Assicurati che incollandolo in Grafana non siano finiti spazi o caratteri in più

2. Controlla che il canale sia attivo

   • Apri l'app Echobell
   • Vai al canale degli avvisi Grafana
   • Verifica che non sia stato eliminato o archiviato per errore

3. Assicurati che ci siano iscritti attivi

   • Serve almeno una persona iscritta per ricevere le notifiche
   • Controlla l'elenco delle iscrizioni al canale
   • Verifica che la tua iscrizione sia attiva

4. Controlla la configurazione del contact point in Grafana

   • Vai su Alerting → Contact points in Grafana
   • Apri il contact point Echobell
   • Conferma che l'URL corrisponda al webhook del tuo canale
   • Controlla che HTTP Method sia impostato su POST
   • Verifica che Content-Type sia application/json

5. Controlla la configurazione della regola di avviso in Grafana

   • Vai su Alerting → Alert rules
   • Apri la regola che dovrebbe scattare
   • Conferma che sia collegata al contact point Echobell
   • Controlla che la notification policy instradi verso il contact point corretto

6. Esamina lo storico degli avvisi di Grafana

   • Vai su Alerting → Alert rules
   • Fai clic sulla regola → Show history
   • Verifica che l'avviso stia davvero scattando (e non sia in stato pending)
   • Controlla se ci sono errori di valutazione

Gli avvisi scattano ma non arrivano

1. Prova il webhook direttamente

   curl -X POST https://hook.echobell.one/t/<channel-token> \
     -H "Content-Type: application/json" \
     -d '{"alertName": "Test", "status": "firing"}'

   Se in questo modo ricevi la notifica ma da Grafana no, il problema è nella configurazione di Grafana.

2. Controlla le notification policy di Grafana

   • Vai su Alerting → Notification policies
   • Verifica che le label della regola corrispondano alle regole di instradamento della policy
   • Cerca eventuali problemi di tempistica (attesa di raggruppamento, intervalli di ripetizione)

3. Esamina i log di Grafana

   • Cerca nei log di Grafana gli errori di consegna del webhook
   • Controlla i codici di stato HTTP (dovrebbe essere 200)
   • Indaga su eventuali errori di timeout o di connessione

Le notifiche non vengono visualizzate correttamente

1. Le variabili del modello non corrispondono al payload di Grafana

   • Grafana invia nomi di campo precisi come .alertName, .status e così via
   • Assicurati che le variabili del modello rispecchino la struttura del payload
   • Usa il pulsante "Test" di Grafana per vedere il payload reale

2. Informazioni mancanti nelle notifiche

   • A seconda della configurazione dell'avviso, alcune variabili di Grafana possono essere vuote
   • Aggiungi valori di riserva nei modelli: {{alertName || "Avviso sconosciuto"}}
   • Consulta la documentazione di Grafana per le variabili disponibili

3. Errori di parsing del JSON

   • Verifica che il modello del messaggio di Grafana sia JSON valido
   • Controlla se ci sono virgolette o caratteri speciali senza escape
   • Usa un validatore JSON online per verificare la struttura del payload

Problemi di tempistica degli avvisi

1. Ritardi nella ricezione degli avvisi

   • Controlla la tua connessione di rete
   • Verifica che Grafana riesca a raggiungere i server di Echobell
   • Rivedi l'intervallo di valutazione di Grafana (può introdurre ritardi)
   • Controlla le impostazioni di tempistica della notification policy

2. Notifiche duplicate

   • Rivedi gli intervalli di ripetizione nelle notification policy
   • Controlla se più regole scattano per la stessa condizione
   • Verifica che al canale sia associato un solo contact point

3. Notifiche durante le ore di silenzio

   • Le modalità Full Immersion di iOS possono influire sulla consegna delle notifiche
   • Le notifiche Urgente e Chiamata riescono a superare alcune modalità Full Immersion
   • Rivedi le impostazioni di notifica del tuo dispositivo

Il problema persiste?

Se hai provato tutto quanto sopra e le difficoltà continuano:

1. Attiva il logging di debug di Grafana

   • Aggiungi la sezione [log] a grafana.ini con level = debug
   • Cerca nei log i tentativi di consegna del webhook e le relative risposte

2. Usa la funzione di test integrata di Grafana

   • Nelle impostazioni del contact point usa "Test" per inviare un avviso di esempio
   • Ti aiuta a capire se il problema riguarda le regole o la consegna

3. Prova con un'altra regola di avviso

   • Crea una regola di prova semplice, con condizioni che scatteranno di sicuro
   • Se la prova funziona ma le regole di produzione no, il problema è nella configurazione delle regole

4. Contatta l'assistenza

   • Vai al Centro assistenza
   • Scrivi a echobell@weelone.com indicando:
     • La versione di Grafana
     • Un payload di avviso di esempio (senza dati sensibili)
     • L'URL del webhook (con il token oscurato)
     • I passaggi che hai già provato
     • Il comportamento atteso e quello effettivo

Documentazione e risorse correlate

Documentazione Echobell

• Guida all'integrazione webhook - Approfondimento sul funzionamento dei webhook
• Sistema di modelli - Padroneggia la sintassi dei modelli di notifica
• Condizioni - Filtra gli avvisi in base a criteri precisi
• Tipi di notifica - Come funzionano le priorità degli avvisi
• Primi passi - Nozioni di base e configurazione di Echobell

Risorse Grafana

• Documentazione su Grafana Alerting - Guida ufficiale agli avvisi di Grafana
• Contact points - Configurazione dei contact point in Grafana
• Notification policies - Instradamento e raggruppamento degli avvisi
• Alert rules - Creazione e gestione delle regole di avviso

Integrazioni correlate

• Integrazione Prometheus - Avvisi direttamente da Prometheus
• Uptime Kuma - Monitoraggio uptime dei siti web
• GitHub Actions - Avvisi per le pipeline CI/CD
• Home Assistant - Notifiche per la casa intelligente

Articoli del blog

• Attiva le notifiche con chiamata per gli avvisi Grafana - Strategie avanzate di integrazione con Grafana
• Non perdere più un errore di GitHub Actions - Best practice per gli avvisi CI/CD
• Notifiche a finestra temporale con le condizioni UTC - Filtrare gli orari lavorativi

Prossimi passi

Ora che Grafana è integrato con Echobell:

1. Affina i tuoi avvisi - Regola le soglie in base all'utilizzo reale
2. Crea altri canali - Usa canali separati per i diversi livelli di gravità
3. Esplora altre integrazioni - Collega altri strumenti a Echobell (vedi tutte le integrazioni)
4. Condividi con il team - Aggiungi i membri del team ai tuoi canali di avviso
5. Documenta la configurazione - Scrivi dei runbook per rispondere ai singoli avvisi
6. Misura l'efficacia degli avvisi - Tieni traccia dei falsi positivi e dei tempi di risposta

Vuoi monitorare altri sistemi? Consulta la nostra guida completa alle integrazioni per altri strumenti e piattaforme di monitoraggio molto diffusi.