Sviluppo di plug-in di controllo basati su agenti

A partire dalla versione 2.0.0 di Checkmk, è stata sviluppata una nuova Check API per la programmazione dei plug-in di controllo. Nella versione 2.4.0 di Checkmk, la Check API V2 è la versione attuale. In questo articolo ti mostreremo come utilizzare la Check API versione 2 per la programmazione dei plug-in. Puoi trovare informazioni sulla migrazione alla Check API versione 2 alla fine di questo articolo nel capitolo Migrazione.

Puoi accedere alla documentazione della Check API in qualsiasi momento tramite l'interfaccia utente di Checkmk: Help > Developer resources > Plug-in API references. Nella nuova finestra del browser, seleziona "Agent based ("Check API") > Version 2" nella barra di navigazione a sinistra:

Qui troverai non solo la documentazione per l'API Check in tutte le versioni supportate, ma anche la documentazione di tutte le altre API rilevanti per la creazione di plug-in di controllo. In questo articolo, non utilizziamo solo l'API Check, ma anche l'API Rulesets V1 quando creiamo un set di regole e l'API Graphing V1 quando creiamo definizioni metriche.

Se sei interessato alla programmazione di plug-in di controllo, avrai bisogno di quanto segue:

Il primo passo prima di scrivere qualsiasi programma plug-in è la ricerca! Questo significa che devi capire come ottenere le informazioni necessarie per il monitoraggio.

Per l'esempio scelto, sfruttiamo il fatto che il server Checkmk è anche l'host. Ciò significa che inizialmente è sufficiente recuperare i dati di stato tramite Livestatus, ovvero i dati organizzati in tabelle che Checkmk conserva nella memoria volatile riguardo agli host e ai servizi monitorati.

Accedi come utente del sito e richiedi le informazioni sui gruppi di host con il seguente comando:

La prima riga dell'output contiene i nomi delle colonne della tabella hostgroups interrogata. Il punto e virgola funge da separatore. Le righe successive contengono quindi il contenuto di tutte le colonne, anch'esse separate da punti e virgola.

L'output è già relativamente confuso in questo piccolo esempio e contiene informazioni che non sono rilevanti per il nostro caso. In generale, dovresti lasciare l'interpretazione dei dati a Checkmk. Tuttavia, un pre-filtraggio sull'host può ridurre il volume dei dati da trasferire se non tutti sono effettivamente necessari. Quindi, in questo caso, limita la query alle colonne rilevanti (Columns), ai nomi dei gruppi di host (name) e agli host in quei gruppi (members):

L'interfaccia Livestatus si aspetta di ricevere tutti i comandi e le intestazioni su righe separate. Le interruzioni di riga necessarie sono indicate da \n.

In questo esempio, ci sono attualmente tre gruppi di host: due gruppi per le località e uno per il gruppo check_mk. Questo contiene un host chiamato localhost.

Il gruppo di host check_mk è una funzionalità speciale all'interno dei gruppi di host. Non l'hai creato tu. E non puoi aggiungere attivamente un host a questo gruppo. Allora da dove viene questo gruppo di host? Poiché per definizione ogni host in Checkmk deve appartenere a un gruppo, Checkmk assegna ogni host che non assegni specificatamente a un gruppo al gruppo "speciale" check_mk come impostazione predefinita. Non appena avrai assegnato un host a uno dei tuoi gruppi di host, verrà rimosso da Checkmk dal gruppo check_mk. Non c'è nemmeno modo di riassegnare un host al gruppo di host check_mk.

Sono proprio queste proprietà del gruppo check_mk a essere utilizzate nel nostro esempio: Poiché ogni host deve essere assegnato a una posizione, il gruppo di host check_mk deve essere vuoto. Se non è vuoto, è necessario intervenire, ovvero gli host in esso contenuti devono essere assegnati ai gruppi di host e quindi alle posizioni appropriate.

Finora, come utente del sito, hai utilizzato il comando lq per visualizzare le informazioni. Questo è utile per comprendere i dati.

Tuttavia, per recuperare questi dati dal server Checkmk, il nuovo comando deve diventare parte dell'agente Checkmk sull'host monitorato. In teoria, potresti ora modificare direttamente l'agente Checkmk nel file /usr/bin/check_mk_agent e includere questa parte. Questo metodo avrebbe però lo svantaggio che il tuo nuovo comando scomparirebbe di nuovo quando il software dell'agente viene aggiornato, poiché questo file verrà sovrascritto durante l'aggiornamento.

È quindi meglio creare un plug-in dell'agente. Tutto ciò che ti serve è un file eseguibile che contenga il comando e che si trovi nella directory /usr/lib/check_mk_agent/plugins/.

E c'è un'altra cosa importante: I dati non possono essere semplicemente visualizzati. Avrai comunque bisogno di un'intestazione di sezione. Si tratta di una riga formattata in modo speciale che contiene il nome del nuovo plug-in dell'agente. Questa intestazione di sezione permette a Checkmk di riconoscere in seguito dove iniziano i dati del nuovo plug-in dell'agente e dove finiscono quelli del plug-in precedente. È più semplice se il plug-in dell'agente, l'intestazione di sezione e il plug-in di controllo hanno lo stesso nome, anche se questo non è obbligatorio.

Quindi, prima di tutto, ti servirà un nome significativo per il tuo nuovo plug-in di controllo. Questo nome può contenere solo lettere minuscole (solo a-z, senza dieresi né accenti), trattini bassi e cifre e deve essere unico. Evita conflitti di nomi con i plug-in di controllo esistenti. Se sei curioso di sapere quali nomi esistono già, in un sito Checkmk dalla riga di comando puoi elencarli con cmk -L:

L'output qui mostra solo le prime righe di un elenco molto lungo. Utilizzando i prefissi, l'assegnazione di molti plug-in di controllo può già essere facilmente riconosciuta qui. L'uso dei prefissi è quindi consigliato anche per i tuoi plug-in di controllo. Per inciso, la seconda colonna mostra come il rispettivo plug-in di controllo ottiene i propri dati.

Un nome adatto per il nuovo plug-in di controllo del nostro esempio è myhostgroups.

Ora hai tutte le informazioni necessarie per creare lo script per il plug-in dell'agente. Crea un nuovo file myhostgroups come utente root nella directory /usr/lib/check_mk_agent/plugins/:

Cosa significa questo in dettaglio?

La prima riga contiene lo "shebang" (abbreviazione di sharp e bang, dove quest'ultimo è l'abbreviazione del punto esclamativo), grazie al quale Linux riconosce che deve eseguire lo script con la shell specificata.

Per mantenere lo script adattabile, vengono introdotte due variabili:

Usa il comando echo per visualizzare l'intestazione della sezione. Poiché le colonne della tabella sono separate da un punto e virgola, usa l'aggiunta sep(59) per specificare che il punto e virgola venga utilizzato come separatore per i dati nell'output dell'agente. Il 59 sta per il codice carattere ASCII 59, il punto e virgola. Senza questa aggiunta, il carattere spazio (carattere ASCII 32) verrebbe utilizzato come separatore per impostazione predefinita.

Per poter utilizzare il comando lq, a tua disposizione come utente del sito, in uno script eseguito dall'utente root, anteponigli su.

Un altro punto importante una volta creato il file: rendi il file eseguibile:

Puoi provare il plug-in dell'agente direttamente a mano inserendo il percorso completo come comando:

I gruppi di host che non contengono alcun host non vengono elencati qui.

Il test e la risoluzione dei problemi sono le attività più importanti quando si crea un plug-in agente funzionante. È meglio procedere in tre passaggi:

Testare l'agent localmente è molto semplice. Come utenroot, esegui il comando check_mk_agent:

La nuova sezione dovrebbe apparire da qualche parte nell'output molto lungo. I plug-in dell'agente vengono generati dall'agente al termine dell'elaborazione.

Puoi scorrere l'output aggiungendo less (premi Spacebar per scorrere, / per cercare e Q per uscire):

Oppure puoi cercare le righe che ti interessano nell'output. Ad esempio, grep con -A offre la possibilità di visualizzare qualche riga in più dopo ogni risultato. Questo ti permette di cercare e visualizzare comodamente la sezione:

Il terzo e ultimo test viene quindi eseguito direttamente dal sito Checkmk. Includi l'host nel monitoraggio (ad esempio come localhost), accedi come utente del sito e poi recupera i dati dell'agente con cmk -d:

Questo dovrebbe produrre lo stesso output del comando precedente.

Se funziona, il tuo agente è pronto. E cosa hai fatto per questo? Hai creato un breve script nel percorso /usr/lib/check_mk_agent/plugins/myhostgroups e l'hai reso eseguibile.

Tutto ciò che segue ora avviene solo sul server Checkmk: Lì scrivi il plug-in di controllo.

Per i tuoi plug-in di controllo troverai la directory di base già pronta nella gerarchia local della directory del sito. Si tratta di ~/local/lib/python3/cmk_addons/plugins/. La directory appartiene all’utente del sito ed è quindi scrivibile per te.

In questa directory, i plug-in sono organizzati in famiglie di plug-in, i cui nomi di directory possono essere definiti liberamente. Ad esempio, tutti i plug-in relativi ai dispositivi Cisco sono memorizzati nella cartella cisco, allo stesso modo tutti i plug-in relativi ai tuoi gruppi di host sono memorizzati nella cartella myhostgroups. Questa convenzione permette a tutti i plug-in appartenenti alla stessa famiglia di condividere il codice — ed è utilizzata esattamente allo stesso modo dai plug-in forniti con Checkmk.

In questa sottodirectory <plug-in_family> vengono poi create ulteriori sottodirectory con nomi predefiniti, a seconda delle diverse API, ad esempio agent_based per l’API Check dei plug-in di controllo basati su agent. A sua volta, introdurremo in seguito ulteriori sottodirectory per l’API Rulesets e l’API Graphing.

Crea le due sottodirectory per il nuovo plug-in di controllo basato su agente e poi passa a esse per lavorare:

Puoi modificare il tuo plug-in di controllo con qualsiasi editor di testo installato sul sistema Linux.

Crea qui il file myhostgroups.py per il plug-in di controllo. La convenzione prevede che il nome del file rifletta il nome della sezione dell'agente. È obbligatorio che il file finisca con .py, perché a partire dalla versione 2.0.0 di Checkmk i plug-in di controllo sono sempre veri e propri moduli Python.

Un framework di base eseguibile (scaricabile da GitHub), che amplierai passo dopo passo di seguito, ha questo aspetto:

Per prima cosa, devi importare le funzioni e le classi necessarie per i plug-in di controllo dai moduli Python. Per il nostro esempio, importeremo solo ciò che sarà necessario o potrebbe essere utile nel resto di questo articolo. Qui, si usa `cmk.agent_based.v2` per specificare che vengono importati i moduli dall'API Check V2:

La funzione di analisi ha il compito di "analizzare" i dati "grezzi" dell'agente, ovvero analizzarli e suddividerli, e inserirli in una forma strutturata logicamente che sia facile da elaborare per tutti i passaggi successivi.

Come mostrato nella sezione dedicata al test dell'agente, la sezione fornita dal plug-in dell'agente ha la seguente struttura:

Checkmk suddivide già le righe della sezione fornita dal plug-in dell'agente in un elenco di righe in base al separatore nell'intestazione della sezione (nell'esempio ;); queste righe sono a loro volta elenchi di parole. In Checkmk è quindi disponibile la seguente struttura di dati al posto dei dati grezzi provenienti dal plug-in dell'agente:

Nell'elenco interno, il primo elemento contiene il nome del gruppo di host e il secondo i nomi degli host appartenenti al gruppo.

Puoi accedere a tutte queste informazioni, ma solo tramite la loro posizione nel set di dati. Dovresti quindi specificare sempre il numero di parentesi quadre e il numero "sequenziale" dei contenuti desiderati all'interno di ciascuna parentesi. Con volumi di dati più grandi, questo diventa sempre più complesso ed è sempre più difficile mantenere una visione d'insieme.

A questo punto, una funzione di analisi sintattica offre chiari vantaggi grazie alla struttura che crea. Rende il codice più leggibile, gli accessi sono più performanti ed è molto più facile mantenere una visione d'insieme. Trasforma la struttura dei dati fornita da Checkmk in modo tale da poter accedere a ciascuno dei singoli valori per nome (o chiave) a piacimento, senza dover cercare ripetutamente nell'array per trovare ciò che stai cercando:

La convenzione prevede che la funzione di analisi prenda il nome dalla sezione dell'agente e inizi con parse_. Riceve string_table come unico argomento. Nota che qui non sei libero di scegliere l'argomento: deve essere chiamato esattamente così.

Con def si specifica in Python che una funzione deve essere definita di seguito. parsed = {} crea il dizionario con la struttura dati migliorata. Nel nostro esempio, esamineremo ogni riga, elemento per elemento. Il gruppo di host seguito dai membri del gruppo di host viene prelevato da ogni riga e assemblato in una voce per il dizionario.

Il dizionario viene quindi restituito con return parsed.

Affinché l'intera procedura abbia effetto, devi creare la nuova sezione agente con la nuova funzione di analisi. Questo è l'unico modo in cui verrà riconosciuta e presa in considerazione da Checkmk. Per farlo, crea la sezione agente come istanza della classe AgentSection:

Qui è importante che il nome della sezione corrisponda esattamente all'intestazione della sezione nell'output dell'agente. Da questo momento in poi, ogni plug-in di controllo che utilizza la sezione myhostgroups riceve il valore di ritorno dalla funzione parse. Di norma, si tratterà del plug-in di controllo con lo stesso nome. Ma anche altri plug-in di controllo possono iscriversi a questa sezione, come mostreremo nell'estensione del plug-in di controllo.

A proposito: se vuoi saperne di più, puoi dare un'occhiata alla documentazione dell'API Check a questo punto. Lì troverai una descrizione dettagliata di questa classe, nonché delle classi, delle funzioni e degli oggetti che verranno utilizzati più avanti in questo articolo.

Affinché Checkmk riconosca la presenza di un nuovo plug-in di controllo, è necessario crearlo. Ciò avviene creando un'istanza della classe CheckPlugin.

Devi sempre specificare almeno quattro cose:

Il nome dell'istanza deve iniziare con check_plugin_. Il risultato sarà quindi simile a questo:

È meglio non provarlo ancora, poiché devi prima scrivere le funzioni discover_myhostgroups e check_myhostgroups. Queste devono apparire nel codice sorgente prima della creazione della sezione agente e del plug-in di controllo, come descritto sopra.

Una caratteristica speciale di Checkmk è il rilevamento automatico dei servizi da monitorare. Affinché ciò funzioni, ogni plug-in di controllo deve definire una funzione che utilizzi l'output dell'agente per riconoscere se un servizio di questo tipo o quali servizi di questo tipo debbano essere creati per l'host in questione.

La funzione di rilevamento viene sempre chiamata quando viene eseguito un rilevamento dei servizi per un host. Essa decide quindi se e quali servizi devono essere creati. Nel caso standard, riceve esattamente un argomento con il nome section. Questo contiene i dati della sezione dell'agente in un formato preparato dalla funzione parse.

Pertanto, implementa la seguente semplice logica: se esiste la sezione dell'agente myhostgroups, crea anche un servizio adeguato. Questo apparirà automaticamente su tutti gli host su cui è distribuito il plug-in dell'agente.

Per i plug-in di controllo che creano un solo servizio per host, non sono necessarie ulteriori informazioni:

La funzione di rilevamento deve restituire un oggetto di tipo service per ogni servizio da creare utilizzando yield (non con return). In Python, yield ha la stessa funzione di return: entrambe restituiscono un valore alla funzione chiamante. La differenza fondamentale è che yield ricorda a che punto è arrivata la funzione nell'elaborazione dei dati. La chiamata successiva prosegue dopo l'ultima istruzione yield e non ricomincia dall'inizio. Questo significa che non viene letto solo il primo risultato (come accadrebbe con return), ma tutti i risultati in sequenza (questo vantaggio diventerà rilevante più avanti nel nostro esempio con il service discovery).

Ora puoi passare alla funzione di controllo vera e propria, che utilizza l'output corrente dell'agente per decidere quale stato deve assumere il servizio e può fornire ulteriori informazioni.

Lo scopo della funzione di controllo è impostare un controllo che possa essere utilizzato per verificare se a un host è stato assegnato un gruppo di host. Per farlo, controlla se il gruppo di host check_mk contiene host. Se è così, il servizio dovrebbe ricevere lo stato CRIT. In caso contrario, tutto è OK e lo stesso vale per lo stato del servizio.

Ecco l'implementazione:

E ora la spiegazione: La funzione check_myhostgroups() recupera prima il valore associato alla chiave check_mk e lo assegna alla variabile attr. Poi la variabile hosts viene collegata al valore members, se esiste. Se non ci sono members, hosts rimane vuota.

Segue poi una query if per la valutazione effettiva:

Una volta creata la funzione di controllo, il plug-in di controllo è pronto.

Il plug-in di controllo e il plug-in dell'agente sono stati resi disponibili su GitHub.

Per prima cosa, assicurati che il tuo plug-in sia sintatticamente corretto:

Ulteriori test e l'attivazione del plug-in vengono eseguiti dalla riga di comando utilizzando il comando `cmk`. Per prima cosa, prova il rilevamento dei servizi con l'opzione `-I`. Aggiungendo l'opzione `v` (per la modalità verbosa) otterrai un output dettagliato. L'opzione `--detect-plugins` limita l'esecuzione del comando a questo plug-in di controllo e `localhost` a questo specifico host:

Come previsto, il servizio di rilevamento riconosce un nuovo servizio nel plug-in di controllo myhostgroups.

Ora puoi provare il controllo contenuto nel plug-in di controllo:

Eseguendo il controllo, verrà determinato lo stato del servizio trovato in precedenza.

Se tutto è andato come previsto, puoi attivare le modifiche. In caso contrario, troverai informazioni utili nel capitolo dedicato alla risoluzione dei problemi.

Infine, genera una configurazione aggiornata del core di monitoraggio e riavvialo:

Nel monitoraggio Checkmk troverai ora il nuovo servizio Host group check_mk sull'host localhost:

Congratulazioni per aver creato con successo il tuo primo plug-in di controllo!

Il primo plug-in di controllo, completato di recente, verrà ora ampliato passo dopo passo. Finora, il plug-in dell'agente ha fornito solo informazioni sui nomi e sui membri all'interno dei gruppi di host. Per poter valutare lo stato degli host e dei servizi in esecuzione su di essi, ad esempio, sono necessari ulteriori dati.

Nel capitolo precedente hai creato un controllo molto semplice che crea un servizio su un host. Tuttavia, è anche molto comune che ci siano diversi servizi da un singolo controllo su un host.

L'esempio più comune è un servizio per un file system su un host. Il plug-in di controllo denominato df crea un servizio per ogni file system presente sull'host. Per distinguere questi servizi, il punto di montaggio del file system (ad esempio /var) o la lettera dell'unità (ad esempio C:) viene incorporato nel nome del servizio. Ciò porta a nomi di servizio come Filesystem /var o Filesystem C:. La parola /var o C: viene qui definita come elemento. Stiamo quindi parlando anche di un controllo con elementi.

Se vuoi creare un controllo con elementi, devi implementare le seguenti funzioni:

Per testarlo nella pratica, creerai un servizio separato per ogni gruppo di host esistente.

Poiché il plug-in di controllo myhostgroups creato nel capitolo precedente per controllare il gruppo standard check_mk dovrebbe continuare a funzionare, questo plug-in di controllo rimane così com'è. Per l'estensione, crea il nuovo plug-in di controllo myhostgroups_advanced nel file esistente myhostgroups.py. — nel primo passo come in precedenza creando un'istanza della classe CheckPlugin.

Qui puoi trovare il codice vecchio e quello nuovo evidenziati:

Per poter distinguere il nuovo plug-in di controllo da quello vecchio, gli viene assegnato un nome univoco con myhostgroups_advanced. Il parametro sections determina le sezioni dell'output dell'agente a cui il plug-in di controllo si abbona. Qui, myhostgroups viene utilizzato per specificare che il nuovo plug-in di controllo utilizza gli stessi dati di quello vecchio: la sezione del plug-in dell'agente preparata dalla funzione parse. Il nome del servizio ora contiene il segnaposto %s. Il nome dell'elemento verrà inserito in seguito in questo punto da Checkmk. Nelle ultime due righe vengono definiti i nomi della nuova funzione di discovery e della nuova funzione di controllo, che devono ancora essere scritte.

Iniziamo dalla funzione di rilevamento, che ora ha il compito di determinare gli elementi da monitorare: anche questa va inserita in aggiunta a quella esistente:

Come in precedenza, la funzione di rilevamento riceve l'argomento section. I singoli gruppi di host vengono elaborati in un ciclo. Qui sono di interesse tutti i gruppi di host, ad eccezione di check_mk, poiché questo gruppo di host speciale è già stato gestito dal plug-in di controllo esistente myhostgroups. Ogni volta che viene trovato un elemento, viene restituito con yield, che crea un oggetto del tipo Service, il quale a sua volta riceve il nome del gruppo di host come elemento.

Se l'host viene monitorato in un secondo momento, la funzione di controllo viene chiamata separatamente per ogni servizio — e quindi per ogni elemento. Questo ti porta alla definizione della funzione di controllo per il nuovo plug-in di controllo myhostgroups_advanced. La funzione di controllo riceve l'argomento item oltre alla sezione. La prima riga della funzione appare quindi così:

L'algoritmo per la funzione di controllo è semplice: Se il gruppo di host esiste, il servizio viene impostato su OK e vengono elencati il numero e i nomi degli host nel gruppo. La funzione completa per questo:

Il risultato del controllo viene fornito restituendo un oggetto della classe Result tramite yield. Ciò richiede i parametri state e summary. Qui, state definisce lo stato del servizio (nell'esempio OK) e summary il testo che viene visualizzato nell'Summarye del servizio. Questo è puramente informativo e non viene valutato ulteriormente da Checkmk. Puoi trovare ulteriori informazioni al riguardo nella prossima sezione.

Fin qui tutto bene. Ma cosa succede se l’elemento che stai cercando non viene trovato? Questo può accadere se in passato è già stato creato un servizio per un gruppo di host, ma questo gruppo di host ora è scomparso — sia perché il gruppo di host esiste ancora in Checkmk ma non contiene più alcun host, sia perché è stato cancellato completamente. In entrambi i casi, questo gruppo di host non sarà più presente nell’output dell’agente.

La buona notizia: Checkmk se ne occupa! Se un elemento cercato non viene trovato, Checkmk genera automaticamente il risultato UNKNOWN - Item not found in monitoring data per il servizio. Questo è intenzionale ed è una cosa positiva. Se un elemento cercato non viene trovato, puoi semplicemente eseguire Python dalla funzione e lasciare che Checkmk faccia il suo lavoro.

Checkmk sa solo che l'elemento che prima era presente ora non c'è più. Checkmk non conosce il motivo di ciò, ma tu sì. È quindi opportuno non tenere questa informazione per te, ma intercettare questa condizione nella funzione di controllo e visualizzare un messaggio utile.

Cosa è cambiato? Ora la condizione di errore viene gestita per prima. Pertanto, controlla nel ramo if se l’elemento non esiste davvero, imposta lo stato su CRIT ed esci dalla funzione con return. In tutti gli altri casi, restituisci OK come prima.

Ciò significa che hai integrato la situazione dei gruppi di host che scompaiono nella funzione di controllo. Invece di UNKNOWN, il servizio associato sarà ora CRIT e conterrà informazioni sulla causa dello stato critico.

Questo completa il nuovo plug-in di controllo come estensione di quello vecchio. Il plug-in dell'agente esteso e il file esteso per i plug-in di controllo si trovano nuovamente su GitHub. Quest'ultimo contiene il semplice plug-in di controllo myhostgroups del capitolo precedente, la funzione di analisi avanzata e i componenti del nuovo plug-in di controllo myhostgroups_advanced con la creazione del plug-in di controllo, la funzione di rilevamento e la funzione di controllo. Tieni presente che le funzioni devono sempre essere definite prima della creazione dei plug-in di controllo o delle sezioni dell'agente, in modo che non si verifichino errori dovuti a nomi di funzioni non definiti.

Poiché il nuovo plug-in di controllo myhostgroups_advanced fornisce nuovi servizi, devi eseguire un rilevamento dei servizi per questo plug-in di controllo e attivare le modifiche per poter visualizzare questi servizi nel monitoraggio:

Procedi come descritto nel capitolo dedicato ai plug-in di controllo semplici. Non eseguire i primi due comandi per myhostgroups, ma eseguili invece per il nuovo plug-in di controllo myhostgroups_advanced.

Nel monitoraggio di Checkmk, ogni servizio ha uno stato — OK, WARN, ecc. — oltre a una riga di testo. Questo testo si trova nella colonna Summary — come si può vedere nella schermata precedente — e ha quindi il compito di fornire un breve riassunto dello stato del servizio. L'idea è che questo testo non superi i 60 caratteri. Questo garantisce una visualizzazione concisa della tabella senza fastidiose interruzioni di riga.

C'è anche il campo "Details", in cui vengono visualizzati tutti i dettagli sullo stato del servizio, incluse tutte le informazioni del riepilogo. Cliccando sul servizio si apre la pagina del servizio, in cui si possono vedere i due campi "Summary" e "Details" insieme a molti altri.

Quando chiami yield Result(...), puoi decidere quali informazioni sono così importanti da dover essere visualizzate nel riepilogo e per quali è sufficiente che compaiano nei dettagli.

Nel nostro esempio, hai sempre utilizzato una chiamata del seguente tipo:

Ciò significa che il testo definito come "summary" appare sempre nell'Summary — e anche nell'Details. Dovresti quindi utilizzarlo solo per informazioni importanti. Se un gruppo di host contiene molti host, l'elenco di riepilogo può diventare molto lungo — più lungo dei 60 caratteri raccomandati. Se un'informazione è di secondaria importanza, puoi utilizzare "details" per specificare che il suo testo appaia solo nei dettagli:

Nell'esempio sopra, l'elenco degli host viene quindi visualizzato solo nell'Details. L'Summary mostra quindi solo il numero di host nel gruppo:

Oltre a summary e details, c'è un terzo parametro. Con notice specifichi che un testo relativo a un servizio nell'OKe venga visualizzato solo nei dettagli, ma anche nel riepilogo per tutti gli altri stati. In questo modo, dal riepilogo risulta immediatamente chiaro perché il servizio non è OK. Il parametro notice non è particolarmente utile se i testi sono associati in modo permanente agli stati, come nel nostro esempio finora.

In sintesi, questo significa:

Per evitare che il numero di servizi su un host aumenti eccessivamente, spesso si combinano diversi risultati parziali in un unico servizio. Ad esempio, il servizio Memory su Linux non solo controlla l'utilizzo della RAM e dello swap, ma anche la memoria condivisa, le tabelle di pagina e ogni sorta di altre cose.

L'API Check offre un'interfaccia molto comoda per questo. Una funzione di controllo può semplicemente generare un risultato con yield tutte le volte che serve. Lo stato complessivo del servizio si basa poi sul risultato parziale peggiore nell'ordine OK → WARN → UNKNOWN → CRIT.

Nell'esempio, usa questa opzione per definire due risultati aggiuntivi per ogni servizio dei gruppi di host oltre al risultato esistente. Questi valutano la percentuale di host nello stato UP e dei servizi nello stato OK. Usa le colonne aggiuntive della tabella dei gruppi di host precedentemente definita nell'output dell'agente e nella funzione di analisi.

Ora espandi la funzione di controllo in più fasi dall'alto verso il basso:

Il ramo "if" rimane invariato, ovvero i nuovi risultati parziali si applicano solo ai gruppi di host che esistono già. Definisci quindi cinque variabili per le colonne della tabella dei gruppi di host contenuta nella sezione. Da un lato, questo aumenta la leggibilità e, dall'altro, puoi convertire le stringhe lette in numeri con "int()" per le quattro colonne che devono ancora essere utilizzate per il calcolo.

L'unico risultato esistente rimane (quasi) invariato:

Ora è più facile che in precedenza solo l'accesso nella "F-String" di Python all'espressione che restituisce il valore, poiché l'attr è già presente nelle definizioni delle variabili.

Passiamo ora al vero e proprio cuore dell'estensione, ovvero la definizione di un risultato che implementa la seguente affermazione: "Il servizio del gruppo di host è WARN quando il 90% degli host è UP, e CRIT quando l'80% degli host è UP." La convenzione qui è che il controllo passi a WARN o CRIT non appena viene raggiunta la soglia, e non solo quando viene superata. L'API Check fornisce la funzione ausiliaria check_levels per confrontare un valore determinato con i valori di soglia.

Nella prima riga, la percentuale viene calcolata dal numero totale e dal numero di host nello stato "UP" e memorizzata nella variabile "hosts_up_perc". La singola barra (/) esegue una divisione in virgola mobile, il che garantisce che il risultato sia un valore float. Questo è utile perché alcune delle funzioni utilizzate in seguito richiedono un float come input.

Nella seconda riga, il risultato della funzione check_levels viene quindi restituito come oggetto di tipo Result, che puoi trovare nella documentazione dell'API. Questa funzione viene alimentata con la percentuale appena calcolata come valore (hosts_up_perc), i due valori di soglia inferiori (levels_lower), un'etichetta che precede l'output (label) e infine con notice_only=True.

L'ultimo parametro utilizza il parametro notice già introdotto nella sezione precedente per l'oggetto Result(). Con notice_only=True specifichi che il testo relativo al servizio viene visualizzato nel Summary solo se lo stato non è OK. Tuttavia, i risultati parziali che portano a un WARN o a un CRIT saranno in ogni caso sempre visibili nel riepilogo, indipendentemente dal valore di notice_only.

Infine, definisci il terzo risultato allo stesso modo del secondo, che calcola la percentuale di servizi nello stato OK:

Questo completa la funzione di controllo.

Il servizio per un gruppo di host ora valuta tre risultati e visualizza lo stato peggiore tra questi nel monitoraggio, come nell'esempio seguente:

Non sempre, ma spesso, i controlli hanno a che fare con numeri — e questi numeri sono molto spesso valori misurati o calcolati. Nel nostro esempio, il numero di host nel gruppo di host (num_hosts) e il numero di host nello stato "UP" (num_hosts_up) sono i valori misurati. La percentuale di host nello stato "UP" (hosts_up_perc) è un valore calcolato a partire da questi valori. Se un valore del genere può poi essere visualizzato su un intervallo di tempo, viene chiamato anche metrica.

Con il suo sistema di grafici integrato, Checkmk dispone di un componente per memorizzare, valutare e visualizzare tali valori. Questo è completamente indipendente dal calcolo degli stati OK, WARN e CRIT.

In questo esempio, definirai i due valori calcolati, hosts_up_perc e services_ok_perc, come metriche. Le metriche saranno immediatamente visibili nell'interfaccia grafica di Checkmk senza che tu debba fare nulla. Per ogni metrica viene generato automaticamente un grafico.

Le metriche sono determinate dalla funzione di controllo e restituite come risultato aggiuntivo. Il modo più semplice è aggiungere le informazioni sulle metriche alla funzione check_levels() nella chiamata.

Come promemoria, ecco le righe con la chiamata alla funzione check_levels() della sezione precedente:

I due nuovi argomenti per la metrica sono metric_name e boundaries:

Per mantenere le cose semplici e significative, per il nome della metrica usa il nome della variabile in cui è memorizzata la percentuale come valore.

Puoi usare boundaries per fornire al sistema di grafici informazioni sull'intervallo dei valori possibili. Questo si riferisce al valore minimo e massimo possibile. Nel caso di una percentuale, i limiti di 0.0 e 100.0 non sono troppo difficili da determinare. Sono ammessi sia i numeri in virgola mobile che i numeri interi (che vengono convertiti internamente in numeri in virgola mobile), ma non le stringhe. Se viene definito solo un limite dell'intervallo di valori, inserisci semplicemente None per l'altro, ad esempio boundaries = (0.0, None).

Con questa estensione, la funzione check_levels ora restituisce anche un oggetto di tipo Metric tramite yield oltre a Result.

Ora puoi definire la metrica services_ok_perc allo stesso modo. Le ultime righe della funzione di controllo saranno quindi simili a queste:

Con la funzione di controllo estesa, entrambi i grafici sono visibili nel monitoraggio. Nell'elenco dei servizi, l'icona "" ora indica che sono disponibili dei grafici per il servizio. Se passi il mouse sull'icona, i grafici verranno visualizzati in anteprima.

Una panoramica di tutti i grafici, comprese le loro legende e altro ancora, è disponibile nei dettagli del servizio.

Ma cosa fare se il valore della metrica desiderata non è stato definito con la funzione check_levels()? Puoi, ovviamente, definire una metrica indipendentemente da una chiamata di funzione. A questo scopo viene utilizzato l'oggetto Metric(), che puoi anche creare direttamente tramite il suo costruttore. La definizione alternativa di una metrica per il valore hosts_up_perc è la seguente:

Gli argomenti in Metric() sono molto simili a quelli nella chiamata di funzione mostrata sopra: I primi due argomenti per il nome della metrica e il valore sono obbligatori. Inoltre, ci sono due argomenti opzionali: levels per i valori di soglia WARN e CRIT e boundaries per l'intervallo di valori.

Ora usa l'opzione di definire non solo i due valori calcolati, ma tutti i valori misurati come metriche usando Metric() — nel nostro esempio, i quattro valori misurati dalla tabella del gruppo di host. Limitati alle due specifiche obbligatorie del nome e del valore della metrica. Le quattro nuove righe completano l'estensione della funzione di controllo per le metriche:

Questo aumenta il numero di grafici per servizio, ma ti offre anche la possibilità di combinare più metriche in un unico grafico, ad esempio. Mostriamo queste e altre opzioni nella sezione Personalizzazione della visualizzazione delle metriche qui sotto.

Nel file di esempio su GitHub puoi trovare nuovamente l'intera funzione di controllo.

Per creare un nuovo set di regole, crea prima una nuova sottodirectory nella directory della famiglia di plug-in ~/local/lib/python3/cmk_addons/plugins/myhostgroups/. Il nome rulesets è predefinito per questa sottodirectory:

In questa directory, crea quindi un file per la definizione del set di regole. Il nome del file deve basarsi su quello del plug-in di controllo e, come tutti i file dei plug-in, deve avere l'estensione py. Per il nostro esempio, il nome del file ruleset_myhostgroups.py è adatto.

Diamo un'occhiata passo dopo passo alla struttura di questo file. Per prima cosa ci sono alcuni comandi di importazione:

Per prima cosa vengono importate le classi per i testi.

La seconda riga effettua una selezione dalle specifiche del modulo, ovvero gli elementi di base per la GUI utilizzati nel set di regole, ad esempio la selezione binaria (BooleanChoice), la selezione multipla (Dictionary, DictElement), la definizione dei valori di soglia (SimpleLevel, LevelDirection, DefaultValue) e l'inserimento di numeri in virgola mobile (Float). Qui richiedi solo gli elementi logici del modulo e lasci la progettazione della GUI a Checkmk.

L'ultima riga importa le specifiche della regola, che determinano l'ambito di applicazione della regola in Checkmk, ovvero in questo caso la definizione dei parametri di controllo, l'assegnazione a host e item e l'archiviazione sotto un argomento. Poiché il tuo plug-in di controllo myhostgroups_advanced genera diversi servizi, importa qui HostAndItemCondition. Se il tuo controllo non genera un servizio, in altre parole non ha un item, importa invece HostCondition.

Ora passiamo alle definizioni effettive del modulo per l'inserimento dei parametri di controllo. L'utente dovrebbe poter definire separatamente i due valori di soglia per WARN e CRIT sia per il numero di host nello stato UP che per il numero di servizi nello stato OK:

Per farlo, crea una funzione che generi il dizionario. Puoi scegliere liberamente il nome della funzione; è richiesto solo quando crei la regola qui sotto. Il nome dovrebbe iniziare con un trattino basso in modo che la funzione non sia visibile al di fuori del modulo.

L'return Dictionary() è obbligatorio. Al suo interno, usa elements={} per creare gli elementi del dizionario, nell'esempio hosts_up_lower e services_ok_lower. Il modulo del parametro SimpleLevels viene utilizzato per inserire valori di soglia fissi. Nel modulo, definisci prima l'titlee e i numeri in virgola mobile per i valori da inserire (form_spec_template). Usa LevelDirection.LOWER per specificare che lo stato cambierà se i valori scendono al di sotto di questo livello.

Infine, puoi usare prefill_fixed_levels per fornire agli utenti del set di regole dei valori invece di campi di immissione vuoti. Tieni presente che questi valori visualizzati nella GUI non sono i valori predefiniti impostati più avanti nella creazione del plug-in di controllo tramite check_default_parameters. Se vuoi visualizzare nella GUI gli stessi valori predefiniti che si applicano anche alla funzione di controllo, devi mantenere i valori coerenti in entrambi i posti.

Infine, crea il nuovo set di regole utilizzando gli elementi importati e quelli definiti autonomamente. Questo si ottiene creando una nuova istanza della classe CheckParameters. Il nome di questa istanza deve iniziare con rule_spec_:

Si applicano le seguenti spiegazioni:

Una volta creato il file per il set di regole, dovresti verificare se finora tutto funziona — ancora senza una connessione al plug-in di controllo. L'esecuzione di cmk-validate-plugins confermerà ora che il set di regole stesso è valido, ma avviserà che non ha ancora alcun effetto.

Per rendere visibile il set di regole, devi riavviare i processi Python che forniscono l'interfaccia grafica. Questo si ottiene riavviando il server web Apache:

Dopodiché, il set di regole sarà visibile in Setup nella pagina sopra menzionata. Tuttavia, potrai trovare il valore predefinito utilizzando la funzione di ricerca in Setup solo dopo aver riavviato Redis:

Il set di regole che hai appena definito apparirà così nella GUI:

Nella casella "Conditions" troverai il campo di immissione "Host group name" definito tramite l'HostAndItemCondition per limitare la regola ai gruppi di host.

Crea una regola e prova diversi valori, come mostrato nella schermata qui sopra. Se funziona senza errori, ora puoi utilizzare i parametri di controllo nella funzione di controllo.

Il set di regole appena creato è ora collegato al plug-in di controllo completato in via provvisoria nel capitolo precedente. Affinché la regola abbia effetto, devi consentire al plug-in di controllo di accettare i parametri di controllo e indicargli quale regola deve essere utilizzata. Per farlo, aggiungi due nuove righe al file del plug-in di controllo quando crei il plug-in di controllo myhostgroups_advanced:

Con la voce "check_default_parameters" puoi definire i valori predefiniti che si applicano finché non è stata effettivamente creata alcuna regola. Quando converti il plug-in di controllo per i parametri di controllo, questa riga deve essere presente. Nel caso più semplice, passa un dizionario vuoto {}.

In secondo luogo, inserisci check_ruleset_name, ovvero il nome del set di regole. In questo modo Checkmk sa da quale set di regole devono essere determinati i parametri.

Ora Checkmk proverà a passare i parametri alla funzione di controllo. Affinché funzioni, devi estendere la funzione di controllo in modo che si aspetti l'argomento params, che va inserito tra item e section:

Se stai creando un controllo senza un elemento, l'item viene omesso e params si trova all'inizio.

Si consiglia vivamente di far sì che il contenuto della variabile params venga visualizzato con print come primo test:

Quando viene eseguito il plug-in di controllo, le righe stampate (una per ogni servizio) con i valori definiti da una regola appariranno più o meno così:

Ora personalizza ulteriormente la tua funzione di controllo in modo che i parametri passati possano avere effetto. Recupera i due elementi del dizionario definiti nella regola con il nome selezionato lì dai parametri:

Più avanti nella funzione di controllo, i valori di soglia precedentemente hardcoded "fixed", (90.0, 80.0) vengono quindi sostituiti dalle variabili hosts_up_lower e services_ok_lower:

Se è stata configurata una regola, ora puoi monitorare i gruppi di host dell'esempio con i valori di soglia impostati tramite la GUI. Tuttavia, se non è stata definita alcuna regola, questa funzione di controllo andrà in crash, poiché i parametri predefiniti nel plug-in di controllo non saranno stati compilati e il plug-in genererà un errore "KeyError" in assenza di una regola.

Tuttavia, questo problema può essere risolto se i valori predefiniti vengono definiti al momento della creazione del plug-in di controllo:

Dovresti sempre passare i valori predefiniti in questo modo (e non intercettare il caso di parametri mancanti nel plug-in di controllo), poiché questi valori predefiniti possono essere visualizzati anche nell'interfaccia Setup. Ad esempio, nel rilevamento dei servizi di un host, nella pagina Services of host, nel menu Display, c'è l'opzione Show check parameters.

Le modifiche apportate nel capitolo precedente interessano sia il nucleo di monitoraggio che l'interfaccia grafica, nonché i relativi processi di supporto. Pertanto, dopo aver eseguito l'cmk-validate-plugins, devi prima rigenerare la configurazione e poi riavviare il sito:

Le procedure per creare insiemi di regole e definizioni di metriche sono molto simili. Per prima cosa crea una nuova sottodirectory con il nome predefinito graphing nella directory della tua famiglia di plug-in ~/local/lib/python3/cmk_addons/plugins/myhostgroups/.

Quindi crea un file grafico in questa directory, ad esempio graphing_myhostgroups.py.

Per prima cosa ci sono di nuovo alcuni comandi di importazione:

Per il nostro esempio, ora definisci la tua metrica per la percentuale di servizi nello stato "OK". Questo si ottiene creando un'istanza della classe Metric. Il nome di questa istanza deve iniziare con metric_

Ecco la spiegazione:

Questa definizione nel file di grafici garantisce ora che il titolo, l'unità e il colore della metrica vengano visualizzati correttamente.

Come per la creazione di un file di regole, il file di grafici deve essere letto prima che la modifica sia visibile nell'interfaccia grafica. Questo si ottiene riavviando Apache sul sito:

Il grafico della metrica apparirà quindi più o meno così nell'interfaccia grafica di Checkmk:

Se vuoi combinare diverse metriche in un unico grafico (cosa spesso molto utile), avrai bisogno di una definizione di grafico da aggiungere al file di grafici creato nella sezione precedente.

Nel nostro esempio, le due metriche num_services e num_services_ok devono essere visualizzate in un unico grafico. Le definizioni delle metriche per questo vengono create allo stesso modo della sezione precedente per services_ok_perc e hanno il seguente aspetto:

Ora aggiungi un grafico che disegni queste due metriche come linee. Questo si fa tramite un'istanza della classe Graph, dove il nome dell'istanza deve iniziare di nuovo con un prefisso predefinito (graph_):

Il parametro minimal_range descrive l'intervallo minimo coperto dall'asse verticale del grafico, indipendentemente dai valori effettivi della metrica. L'asse verticale verrà esteso se i valori superano l'intervallo minimo, ma non sarà mai più piccolo.

Il risultato è il grafico combinato nella GUI di Checkmk:

Vuoi visualizzare un Perf-O-Meter per una metrica nella riga dell'elenco dei servizi? Potrebbe apparire così, ad esempio:

Per creare un Perf-O-Meter di questo tipo, avrai bisogno di un'altra istanza, questa volta della classe Perfometer, il cui nome inizia con il prefisso perfometer_:

I Perf-O-Meter sono un po' più complicati dei grafici, poiché non hanno una legenda. È quindi difficile visualizzare un intervallo di valori, specialmente quando vengono visualizzati valori assoluti. È più facile visualizzare una percentuale. Questo vale anche per l'esempio sopra riportato:

Inoltre, nella documentazione dell'API Graphing puoi trovare opzioni ancora più sofisticate per implementare le metriche in Perf-O-Meters, ad esempio con le classi Bidirectional e Stacked, che permettono di visualizzare più Perf-O-Meters in uno solo.

Il file di grafici per questo capitolo è disponibile su GitHub. Tra le altre cose, questo file contiene le definizioni delle metriche per i quattro valori misurati e i due valori calcolati.

Le specifiche temporali assolute (timestamp) sono formattate con render.date() o render.datetime(). Le informazioni sono sempre fornite come tempo Unix, ovvero in secondi a partire dal 1° gennaio 1970, 00:00:00 UTC — l'inizio dell'epoca Unix. Questo è anche il formato utilizzato dalla funzione Python time.time().

Il vantaggio di questa rappresentazione è che è molto facile da calcolare, ad esempio per determinare un intervallo di tempo, quando si conoscono l'ora di inizio e quella di fine. La formula è semplicemente duration = end - start. Questi calcoli funzionano indipendentemente dal fuso orario, dai cambiamenti dell'ora legale o dagli anni bisestili.

render.date() restituisce solo la data, mentre render.datetime() aggiunge l'ora. Il risultato dipende dal fuso orario corrente in cui si trova il server Checkmk che sta eseguendo il controllo. Esempi:

Non stupirti se render.datetime(0) non restituisce 00:00 come ora, ma 01:00. Questo perché stiamo scrivendo questa Guida utente nel fuso orario della Germania, che è un'ora avanti rispetto all'ora UTC standard (almeno durante l'ora solare, perché il 1° gennaio non è in ora legale).

Per gli intervalli di tempo (o periodi di tempo) c'è anche la funzione render.timespan(). A questa viene fornita una durata in secondi e la restituisce in un formato leggibile. Per periodi di tempo più lunghi, i secondi o i minuti vengono omessi. Se hai un intervallo di tempo in un oggetto TimeDelta, usa la funzione total_seconds() per leggere il numero di secondi come numero in virgola mobile.

Una frequenza è in pratica il reciproco del tempo. L'unità canonica è l'Hz, che equivale a 1 / sec (il reciproco di un secondo). Un esempio del suo utilizzo è la frequenza di clock di una CPU:

Quando si parla di memoria di lavoro, file, dischi rigidi, file system e simili, l'unità canonica è il byte. Dato che i computer di solito organizzano queste cose in potenze di due, per esempio in unità da 512, 1024 o 65.536 byte, si è stabilito fin dall'inizio che un kilobyte non è 1000, e quindi mille volte l'unità, ma 1024 (2 alla potenza di 10) byte. Questo è certamente illogico, ma molto pratico perché di solito si ottengono numeri tondi. Il leggendario Commodore C64 aveva 64 kilobyte di memoria e non 65.536.

Purtroppo, a un certo punto i produttori di hard disk hanno avuto l'idea di specificare le dimensioni dei loro dischi in unità da 1000. Dato che la differenza tra 1000 e 1024 è del 2,4% per ciascuna dimensione, e queste vengono moltiplicate, un disco da 1 GB (1024 per 1024 per 1024) diventa improvvisamente 1,07 GB. Questo vende meglio.

Questa fastidiosa confusione esiste ancora oggi e continua a generare errori. Per ovviare a questo problema, la Commissione Elettrotecnica Internazionale (IEC) ha definito nuovi prefissi basati sul sistema binario. Di conseguenza, oggi un kilobyte è ufficialmente 1000 byte e un kibibyte è 1024 byte (2 alla potenza di 10). Inoltre, si dovrebbe dire mebibyte, gibibyte e tebibyte. Le abbreviazioni sono quindi KiB, MiB, GiB e TiB.

Checkmk si attiene a questo standard e ti aiuta con una serie di funzioni di rendering personalizzate per assicurarti di ottenere sempre il risultato corretto. Ad esempio, c'è la funzione "render.disksize()" pensata appositamente per i dischi rigidi e i file system, che produce il suo output in potenze di 1000.

Quando si parla delle dimensioni dei file, spesso si usa specificare la dimensione esatta in byte senza arrotondamenti. Questo ha il vantaggio di permetterti di vedere molto rapidamente se un file è cambiato anche minimamente o se due file sono (probabilmente) uguali. Per questo si usa la funzione render.filesize():

Se vuoi visualizzare un valore che non sia la dimensione di un disco rigido o di un file, usa semplicemente la funzione generica render.bytes(). In questo modo otterrai il risultato nella "classica" notazione ufficiale a potenze di 1024:

I networker hanno i loro termini e modi di esprimersi. E come sempre, Checkmk fa di tutto per adottare il modo convenzionale di comunicare in ogni ambito. Ecco perché ci sono tre diverse funzioni di rendering per le velocità di trasmissione dati. Ciò che tutte hanno in comune è che le velocità sono espresse in byte al secondo, anche se l'output effettivo è in bit!

render.nicspeed() rappresenta la velocità massima di una scheda di rete o di una porta di uno switch. Poiché non si tratta di valori misurati, non è necessario arrotondare. Sebbene nessuna porta possa inviare singoli bit, i dati sono espressi in bit per ragioni storiche.

Importante: Tuttavia, anche qui devi passare i byte al secondo!

render.networkbandwidth() è destinato a una velocità di trasmissione effettivamente misurata nella rete. Il valore di input è di nuovo in byte al secondo:

Quando non c'è una rete coinvolta ma vengono comunque visualizzate velocità di trasmissione dati, si usa di nuovo l'unità byte. Il caso più comune è la velocità di I/O dei dischi rigidi. Per questo si usa la funzione "render.iobandwidth()", che in Checkmk funziona con potenze di 1000:

La funzione render.percent() rappresenta una percentuale, arrotondata a due cifre decimali. È un'eccezione rispetto alle altre funzioni in quanto non restituisce il valore naturale effettivo, cioè il rapporto, ma la percentuale reale. Ad esempio, se qualcosa è pieno per metà, non devi passare 0.5 ma 50.

Poiché a volte può essere interessante sapere se un valore è quasi zero o esattamente zero, i valori vengono contrassegnati aggiungendo il carattere ‘<’, per i valori che sono maggiori di zero ma inferiori allo 0,01%.

In conclusione, ecco una panoramica di tutte le funzioni di rendering:

Se si verifica un'eccezione durante il monitoraggio o durante il rilevamento dei servizi nell'Setup, l'Summary contiene i riferimenti al rapporto di crash appena creato. Ad esempio, apparirà così:

Cliccando sull'icona dell' si apre una pagina con i dettagli in cui puoi:

Il traceback ti aiuta, in qualità di sviluppatore, a decidere se c'è un errore nel programma (ad es. la chiamata di una funzione inesistente) o se i dati dell'agente non sono stati elaborati come previsto. Nel primo caso vorrai correggere l'errore, nel secondo caso spesso ha senso non fare nulla.

L'invio del rapporto è ovviamente utile solo per i plug-in di controllo che fanno ufficialmente parte di Checkmk. Se metti a disposizione di terzi i tuoi plug-in, puoi chiedere ai tuoi utenti di inviarti i dati.

Se esegui il tuo plug-in di controllo dalla riga di comando, non riceverai alcuna indicazione dell'ID di eventuali rapporti di crash generati. Vedrai solo il messaggio di errore riassuntivo:

Se aggiungi l'opzione --debug come parametro di chiamata aggiuntivo, riceverai il traceback dall'interprete Python:

Se l'errore non si verifica nuovamente la prossima volta che chiami --debug, ad esempio perché è disponibile un nuovo output dell'agente, puoi anche visualizzare gli ultimi rapporti di crash nel file system:

In ciascuna di queste cartelle ci sono due file:

Negli esempi mostrati sopra, usiamo la funzione print() per visualizzare il contenuto delle variabili o la struttura degli oggetti per te come sviluppatore. Queste funzioni per l'output di debug devono essere rimosse dal plug-in di controllo finito.

In alternativa alla rimozione, puoi anche far visualizzare l'output di debug solo quando il plug-in di controllo viene richiamato dalla console in modalità debug. Per farlo, importa l'oggetto debug dalla toolbox di Checkmk e, se necessario, l'aiuto alla formattazione pprint(). Ora puoi generare l'output di debug in base al valore dell'oggetto debug:

Tieni presente che qualsiasi output di debug rimanente dovrebbe essere usato con parsimonia e limitato a suggerimenti che aiutino gli utenti successivi con il debug. Gli errori utente ovvi e prevedibili (ad esempio, che il contenuto della sezione agente indichi che il plug-in dell'agente è stato configurato in modo errato) dovrebbero ricevere come risposta lo stato UNKNOWN e includere note esplicative nel riepilogo.

La domanda è: come dovresti reagire se l'output dell'agente non è nella forma che ti aspetti, sia che provenga dall'agente Checkmk o che sia ricevuto tramite SNMP. Supponiamo che ti aspetti sempre tre parole per riga, cosa dovresti fare se ne ricevi solo due?

Beh, se questo è un comportamento consentito e noto dell'agente, allora ovviamente devi intercettarlo e lavorare con una distinzione di casi. Tuttavia, se questo non è effettivamente consentito, allora è meglio comportarsi come se la riga fosse sempre composta da tre parole, ad esempio con la seguente funzione di analisi:

Se c'è una riga che non è composta esattamente da tre parole, viene generata un'eccezione e ricevi l'utilissimo rapporto di crash appena menzionato.

Se accedi a chiavi in un dizionario che potrebbero occasionalmente mancare, può ovviamente avere senso reagire di conseguenza. Questo può essere fatto impostando il servizio su CRIT o UNKNOWN e inserendo una nota nel riepilogo riguardo all'output dell'agente che non può essere valutato. In ogni caso, è meglio usare la funzione get() del dizionario per questo piuttosto che intercettare l'eccezione KeyError. Questo perché get() restituisce un oggetto di tipo None o una sostituzione opzionale da passare come secondo parametro se la chiave non è disponibile:

Cosa succede se l'agente restituisce dati corretti, ma l'elemento da controllare manca? Come in questo caso, ad esempio:

Se l'elemento che stai cercando non è presente, il ciclo viene eseguito e Python semplicemente esce alla fine della funzione senza restituire un risultato tramite yield. Ed è proprio questo l'approccio corretto! Perché Checkmk riconosce che l'elemento da monitorare manca e genera lo stato corretto e un testo standard appropriato con UNKNOWN.

Se vuoi simulare particolari output dell'agente, i file nella directory spool sono molto utili. Puoi usarli per testare casi limite che altrimenti sarebbero difficili da ricreare. Oppure puoi usare direttamente l'output dell'agente che ha portato a un rapporto di crash per testare le modifiche a un plug-in di controllo.

Per prima cosa disattiva il tuo plug-in dell'agente normale, ad esempio revocandone l'autorizzazione all'esecuzione. Quindi crea un file nella directory /var/lib/check_mk_agent/spool/ che contenga la sezione dell'agente (o le sezioni dell'agente previste) che il tuo plug-in di controllo si aspetta, inclusa l'intestazione della sezione, e che termini con un carattere di nuova riga. La prossima volta che l'agente verrà chiamato, verrà trasferito il contenuto del file di spool invece dell'output del plug-in dell'agente.

Con alcuni plug-in di controllo che utilizzano elementi, è possibile che su server di grandi dimensioni vengano generati diverse centinaia di servizi. Se non viene utilizzata una funzione di analisi separata, ciò significa che l'intero elenco di centinaia di righe deve essere elaborato per ciascuno dei centinaia di elementi. Il tempo necessario per la ricerca aumenta quindi in proporzione al quadrato del numero di elementi elencati, il che significa decine di migliaia di confronti per centinaia di servizi. Se, invece, l'elenco annidato viene trasferito in un dizionario, il tempo necessario per cercare un elemento aumenta solo in modo lineare con la dimensione del dizionario.

Nel wiki di Python troverai una panoramica dei costi di ricerca in diversi tipi di dati, compresa una spiegazione e la notazione O. L'uso della funzione parse riduce la complessità della ricerca da O(n) a O(1).

Poiché le versioni precedenti di questo articolo non utilizzavano la funzione parse, dovresti identificare tali plug-in di controllo e riscriverli in modo da utilizzare la funzione parse.