--- title: "Integrazione Grafana - avvisi di infrastruttura" sidebarTitle: Grafana description: Invia gli avvisi di Grafana a Echobell tramite webhook e ricevi subito notifiche push o chiamate. Configurazione passo passo con modelli di avviso. --- import { Step, Steps } from "fumadocs-ui/components/steps"; # Integrazione Grafana 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](/docs)) - 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 ### Crea un canale Echobell 1. Apri l'app Echobell 2. Crea un nuovo canale (ad esempio "Avvisi Grafana") 3. Scegli un colore distintivo per riconoscerlo a colpo d'occhio ### Configura i modelli di notifica Prepara i modelli che daranno forma ai tuoi avvisi Grafana: **Modello del titolo:** ``` {{alertName}} - {{status}} ``` **Modello del corpo:** ``` 🔔 Avviso: {{alertName}} 📊 Metrica: {{metric}} 📈 Valore: {{value}} ⏰ Ora: {{time}} ℹ️ Messaggio: {{message}} ``` Questi modelli funzionano con la struttura del payload degli avvisi di Grafana. ### Recupera l'URL del webhook 1. Nelle impostazioni del canale, individua la sezione **Triggers** 2. Copia l'URL del webhook mostrato 3. Conserva l'URL al sicuro: lo userai nella configurazione di Grafana ### Configura il contact point di Grafana 1. In Grafana vai su **Alerting** → **Contact points** 2. Fai clic su **New contact point** 3. Imposta questi valori: - Nome: "Echobell" - Tipo: "Webhook" - URL: l'URL del webhook di Echobell - Metodo HTTP: POST - Tipo di contenuto: application/json 4. Configura il modello del messaggio: ```json { "alertName": "{{ .alertName }}", "status": "{{ .status }}", "metric": "{{ .metric }}", "value": "{{ .value }}", "time": "{{ .time }}", "message": "{{ .message }}", "externalLink": "{{ .dashboardURL }}" } ``` ### Crea le regole di avviso 1. Vai su **Alerting** → **Alert rules** 2. Crea una nuova regola di avviso oppure modificane una esistente 3. Nella configurazione della regola: - Imposta le condizioni adatte alle tue metriche - Seleziona il contact point "Echobell" - Definisci i criteri di valutazione dell'avviso ## 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](/docs/notification) 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](/docs/conditions) 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](/blog/grafana-call-notification). ## 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** ```bash curl -X POST https://hook.echobell.one/t/ \ -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](/docs/support) - 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](/docs/webhook)** - Approfondimento sul funzionamento dei webhook - **[Sistema di modelli](/docs/template)** - Padroneggia la sintassi dei modelli di notifica - **[Condizioni](/docs/conditions)** - Filtra gli avvisi in base a criteri precisi - **[Tipi di notifica](/docs/notification)** - Come funzionano le priorità degli avvisi - **[Primi passi](/docs)** - Nozioni di base e configurazione di Echobell ### Risorse Grafana - **[Documentazione su Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/)** - Guida ufficiale agli avvisi di Grafana - **[Contact points](https://grafana.com/docs/grafana/latest/alerting/fundamentals/contact-points/)** - Configurazione dei contact point in Grafana - **[Notification policies](https://grafana.com/docs/grafana/latest/alerting/fundamentals/notification-policies/)** - Instradamento e raggruppamento degli avvisi - **[Alert rules](https://grafana.com/docs/grafana/latest/alerting/fundamentals/alert-rules/)** - Creazione e gestione delle regole di avviso ### Integrazioni correlate - **[Integrazione Prometheus](/docs/developer/prometheus)** - Avvisi direttamente da Prometheus - **[Uptime Kuma](/docs/developer/uptime-kuma)** - Monitoraggio uptime dei siti web - **[GitHub Actions](/docs/developer/github)** - Avvisi per le pipeline CI/CD - **[Home Assistant](/docs/developer/home-assistant)** - Notifiche per la casa intelligente ### Articoli del blog - **[Attiva le notifiche con chiamata per gli avvisi Grafana](/blog/grafana-call-notification)** - Strategie avanzate di integrazione con Grafana - **[Non perdere più un errore di GitHub Actions](/blog/github-actions-notifications)** - Best practice per gli avvisi CI/CD - **[Notifiche a finestra temporale con le condizioni UTC](/blog/time-window-notifications-using-utc-conditions)** - 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](/docs/features)) 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](/docs/features) per altri strumenti e piattaforme di monitoraggio molto diffusi.