 |
This is a machine translation based on the English version of the article. It might or might not have already been subject to text preparation. If you find errors, please file a GitHub issue that states the paragraph that has to be improved. |
1. Perché i controlli locali?
Checkmk monitora già molti tipi di dati rilevanti utilizzando un gran numero di plug-in di controllo standard. Tuttavia, ogni ambiente IT è unico, per cui spesso possono sorgere esigenze molto specifiche. Con i check locali hai la possibilità di estendere l'agente Checkmk sull'host di destinazione per creare in modo semplice e veloce i tuoi servizi.
Questi plug-in di controllo locali si differenziano per un aspetto significativo dagli altri controlli: il calcolo di uno stato avviene direttamente nell'host su cui vengono recuperati i dati. In questo modo non è necessaria la complessa creazione di controlli in Python e la scelta del linguaggio di codifica per gli script è completamente libera.
2. Scrivere un semplice check locale
2.1. Creazione dello script
Un controllo locale può essere scritto in qualsiasi linguaggio di programmazione supportato dallo stato dell'host di destinazione. Lo script deve essere costruito in modo che ogni controllo produca una riga di stato composta da quattro parti. Ecco un esempio:
0 "My service" myvalue=73 My output text which may contain spacesLe quattro parti sono separate da spazi vuoti e hanno il seguente significato:
| Esempio di valore | Significato | Descrizione |
|---|---|---|
|
Stato |
Lo stato del servizio viene indicato con un numero: |
|
Nome del servizio |
Il nome del servizio come mostrato in Checkmk, nell'output del controllo tra doppi apici. |
|
Valore e metriche |
Valori metrici dei dati. Per maggiori informazioni sulla costruzione dei valori, consulta il capitolo sulle metriche. In alternativa è possibile inserire un segno meno se il controllo non produce metriche. |
|
Dettagli sullo stato |
I dettagli dello stato come saranno mostrati in Checkmk. Questa parte può contenere anche degli spazi vuoti. |
Tra le quattro parti di questo output deve sempre esserci esattamente uno spazio (ASCII 0x20). All'interno dei dettagli dello stato, gli spazi possono essere utilizzati in qualsiasi ordine.
|
Eventuali deviazioni dalle specifiche appena descritte possono funzionare, ma non devono. Le versioni future di Checkmk potrebbero applicare questo formato di output e ignorare i check locali che si discostano. |
Se non sei sicuro di un possibile output, puoi semplicemente testarlo scrivendo un piccolo script con il comando echo. Inserisci l'output che vuoi testare nel comando echo. Il nostro esempio utilizza le virgolette doppie all'esterno, poiché le variabili all'interno (variabili d'ambiente e quelle impostate nello script) vengono valutate. Di conseguenza, devi racchiudere le virgolette per il nome del servizio con \ in modo che questi caratteri non vengano interpretati dalla shell come la fine e l'inizio di una stringa (e quindi rimossi dall'output):
#!/bin/bash
echo "0 \"My 1st service\" - This static service is always OK"Per gli host Windows, lo script avrà un aspetto molto simile a questo:
@echo off
echo 0 "My 1st service" - This static service is always OKEntrambi gli script producono lo stesso risultato nell'output:
0 "My 1st service" - This static service is always OKPer Checkmk è importante solo l'output, non il modo in cui è stato creato.
A proposito: puoi scrivere un numero qualsiasi di output in uno script. Ogni linea di output avrà il proprio servizio creato in Checkmk. Pertanto, non sono ammessi caratteri di newline nell'output, a meno che non siano mascherati, ad esempio per un output multilinea in Checkmk.
Il modo in cui è possibile verificare se lo script locale verrà invocato correttamente dall'agente è illustrato nell'analisi degli errori.
|
Se viene utilizzato il core di Nagios (sempre nel Checkmk Raw), i seguenti caratteri speciali non sono ammessi nel nome del servizio: |
2.2. Distribuire lo script
Una volta che lo script è stato scritto, può essere distribuito ai nomi host appropriati. Il percorso utilizzato dipende dal sistema operativo. Un elenco dei nomi dei percorsi si trova in File e directory qui sotto.
Non dimenticare di rendere lo script eseguibile sui sistemi Unix. Il percorso mostrato in questo esempio è per Linux:
root@linux# chmod +x /usr/lib/check_mk_agent/local/mylocalcheckSe utilizzi l'Agent Bakery, lo script può essere distribuito con una procedura rule-based. Per maggiori informazioni sulla creazione di regole, consulta il capitolo Distribuzione tramite Agent Bakery.
2.3. Aggiungere il servizio al monitoraggio
Ad ogni invocazione dell'agente Checkmk, anche il check locale contenuto nello script verrà eseguito e aggiunto all'output dell'agente. Anche la scoperta del servizio funziona automaticamente come per gli altri servizi:
Una volta aggiunto il servizio al monitoraggio e attivate le modifiche, l'implementazione del servizio auto-creato con l'aiuto di un check locale sarà completa. Se dovesse sorgere un problema durante la scoperta del servizio, l'analisi degli errori può essere d'aiuto.
3. Funzioni estese
3.1. Metriche
Con un check locale è possibile impostare anche le metriche. Per attivarle, il valore del check deve sempre restituire P. Poi lo stato verrà calcolato da Checkmk.
La sintassi generale per questi dati è la seguente:
metricname=value;warn;crit;min;maxdove value è il valore corrente, warn e crit impostano le soglie (superiori) e min e max fissano l'intervallo di valori - ad esempio in questo modo:
count=73;80;90;0;100Tutti i valori sono separati da un punto e virgola. Tutti i valori, ad eccezione di value, sono facoltativi. Se un valore non è richiesto, il campo rimane vuoto o viene omesso alla fine, come nel caso di warn, crit e max:
count=42;;;0Nota: nelle edizioni commerciali i valori di min e max possono essere impostati, ma solo per motivi di compatibilità. Limitare il grafico associato a un certo intervallo di valori non ha alcun effetto nelle edizioni commerciali.
3.2. Nome della metrica
Devi prestare particolare attenzione alla scelta dell'identificativo di questa metrica, che nell'esempio qui riportato si chiama metricname. Ti consigliamo di anteporre il prefisso all'identificativo per evitare sovrapposizioni con metriche già presenti in Checkmk.
Quindi, ad esempio, invece di chiamare semplicemente "corrente" una metrica che rappresenta il numero di richieste in attesa in una coda che stai monitorando, ti consigliamo di usare un identificatore più chiaro con un prefisso, ad esempio: mycompany_current_requests.
Se dovessi scegliere un identificatore che esiste già in Checkmk, la rappresentazione delle metriche nei grafici verrebbe sovrascritta con le definizioni già esistenti.
Naturalmente, puoi anche riutilizzare intenzionalmente una metrica esistente in Checkmk. Ad esempio, per la metrica della corrente elettrica puoi semplicemente utilizzare l'identificatorecurrent nel tuo check locale. In caso di dubbio, però, dovrai cercare da solo la definizione di questa metrica in ~/lib/python3/cmk/gui/plugins/metric.
OMD[mysite]:~$ grep -r -A 4 'metric_info\["current"\]' ./lib/python3/cmk/gui/plugins/metrics/3.3. Metriche multiple
È anche possibile ottenere l'output di più metriche, separate dal carattere "pipe" |, ad esempio in questo modo:
count1=42|count2=23Attenzione: Negli host Windows devi anteporre un caret (^) alla pipe nello script, in modo che non venga interpretata.
@echo off
echo 0 "My 2nd service" count1=42^|count2=23 A service with 2 graphsUn output completo con due metriche sarà simile a questo:
root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
0 "My 2nd service" count1=42|count2=23 A service with 2 graphsDopo aver incluso il nuovo servizio nel monitoraggio, vedrai il testo dello stato del servizio nel campo Summary dell'elenco dei servizi. Dopo aver fatto clic sul servizio, verrà visualizzata la pagina con i dettagli del servizio. Le metriche sono mostrate nel campo Details e sotto di esso vedrai i grafici del servizio generati automaticamente da Checkmk:
3.4. Calcolo dinamico dello stato
Nei capitoli precedenti hai imparato come impostare i valori di soglia per le metriche e come visualizzarli nei grafici. Il passo successivo è quello di utilizzare queste soglie per calcolare dinamicamente lo stato del servizio. Checkmk offre esattamente queste opzioni per estendere un check locale.
Se inserisci la lettera P invece di un numero nel primo campo dell'output che determina lo stato, lo stato del servizio verrà calcolato in base alla soglia fornita.
L'output sarà quindi simile a questo:
root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 1st dynamic service" count=40;30;50 Result is computed from two threshold values
P "My 2nd dynamic service" - Result is computed with no values... e la visualizzazione in un servizio sarà come questa:
La visualizzazione differisce in due punti da quella vista in precedenza:
Per i servizi nello stato WARN o CRIT, il sito Summary del servizio mostra tutte le informazioni importanti sulle metriche (nome, valore, soglie). Ciò significa che puoi sempre vedere come questo stato è stato calcolato da un valore. Per tutti gli altri stati, le informazioni sulle metriche sono visualizzate solo nel campo Details.
Se non è stata superata alcuna metrica, lo stato del servizio sarà sempre OK.
3.5. Soglie superiori e inferiori
Alcuni parametri hanno non solo una soglia superiore ma anche una soglia inferiore. Un esempio è l'umidità. In questi casi, il check locale ha la possibilità di passare due valori di soglia per gli stati WARN e CRIT, separati da due punti e che rappresentano rispettivamente il valore di soglia inferiore e superiore.
La sintassi generale è la seguente:
metricname=value;warn_lower:warn_upper;crit_lower:crit_upper... e nell'esempio è così:
root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 3rd service" humidity=37;40:60;30:70 A service with lower and upper thresholds... e nella visualizzazione di un servizio si presenta così:
Se ti interessa solo la soglia inferiore, tralascia i campi della soglia superiore:
root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 4th dynamic service" count_lower=37;40:;30: A service with lower thresholds onlyCon questo output, specifichi che il servizio deve diventare WARN se il valore è inferiore a 40 e CRIT se è inferiore a 30: quindi, al valore specificato di 37, il servizio otterrà lo stato WARN.
3.6. Uscite su più righe
È disponibile anche l'opzione di distribuire un output su più righe. Poiché Checkmk viene eseguito in ambiente Linux, puoi utilizzare la sequenza Escape '\n' per forzare un'interruzione di riga. Anche se a causa del linguaggio di script il backslash stesso deve essere evaso, verrà interpretato correttamente da Checkmk:
root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My service" humidity=37;40:60;30:70 My service output\nA line with details\nAnother line with detailsNei dettagli del servizio, queste righe aggiuntive saranno visibili sotto la dicitura Summary:
3.7. Esecuzione asincrona e cache dell'output
L'output dei controlli locali, come quello dei plug-in dell'agente, può essere memorizzato nella cache. Questo può essere necessario se uno script ha un tempo di elaborazione più lungo. Tale script viene eseguito in modo asincrono e solo in un intervallo di tempo definito e l'ultimo output viene memorizzato nella cache. Se l'agente viene interrogato di nuovo prima della scadenza del tempo, utilizza questa cache per il check locale e lo restituisce nell'output dell'agente.
Nota: la cache è disponibile solo per AIX, FreeBSD, Linux, OpenWrt e Windows.
Configurazione di Linux
In Linux o in un altro sistema operativo Unix, qualsiasi plug-in può essere eseguito in modo asincrono. Per un check locale, la configurazione necessaria è molto simile a quella di un plug-in. A tal fine, crea una sottodirectory chiamata per il numero di secondi in cui vuoi che l'output venga memorizzato nella cache e inserisci il tuo script in quella sottodirectory.
Nell'esempio seguente, il check locale verrà eseguito solo ogni 10 minuti (600 secondi):
root@linux# /usr/lib/check_mk_agent/local/600/mylocalcheck
2 "My cached service" count=4 Some output of a long running scriptI dati in cache vengono scritti in una directory cache.
Per un servizio che fornisce dati in cache, le informazioni specifiche della cache vengono aggiunte alla visualizzazione del servizio:
Configurazione di Windows
Anche in Windows la configurazione è analoga a quella di un plug-in. Invece di utilizzare una sottodirectory speciale come in Linux & Co, le opzioni vengono impostate in un file di configurazione:
local:
enabled: yes
execution:
- pattern : $CUSTOM_LOCAL_PATH$\mylocalcheck.bat
async : yes
run : yes
cache_age : 600Come puoi vedere sopra, in Windows puoi configurare separatamente l'esecuzione asincrona (con async) e l'intervallo di tempo (con cache_age).
In alternativa, su Windows puoi anche effettuare la configurazione nell'agent bakery.
4. Distribuzione tramite l'Agent bakery
Se stai già utilizzando l'Agent bakery, puoi distribuire gli script con i check locali a diversi host anche in questo modo.
Per farlo, crea prima la directory custom sul server Checkmk come utente dell'istanza Checkmk sotto ~/local/share/check_mk/agents/ e in essa una sottodirectory per ogni pacchetto di check locali:
OMD[mysite]:~$ cd ~/local/share/check_mk/agents
OMD[mysite]:~$ ~/local/share/check_mk/agents$ mkdir -p custom/mycustompackage/lib/local/La directory del pacchetto nell'esempio precedente è mycustompackage. Sotto di essa, la directory lib contrassegna lo script come plug-in di controllo o come check locale. La successiva directory local alloca quindi il file in modo esplicito. Inserisci lo script con il check locale in questa directory.
Importante: Su Linux, puoi configurare l'esecuzione asincrona in modo analogo a quanto descritto nel capitolo precedente, creando una directory sotto custom/mycustompackage/lib/local/ con il numero di secondi dell'intervallo di esecuzione e collocandovi lo script. In Windows, puoi utilizzare i set di regole Set execution mode for plugins and local checks e Set cache age for plugins and local checks. Questi e altri set di regole per i check locali in Windows si trovano nell'agent bakery all'indirizzo Agent rules > Windows Agent.
Nell'ambiente di configurazione di Checkmk, la directory dei pacchetti mycustompackage verrà visualizzata come una nuova opzione: apri Setup > Agents > Windows, Linux, Solaris, AIX, crea una nuova regola con Agents > Agent rules > Generic options > Deploy custom files with agent e seleziona il pacchetto appena creato:
Checkmk integrerà quindi autonomamente il check locale nel pacchetto di installazione per il sistema operativo appropriato. Dopo aver attivato le modifiche e aver infornato l'agente, la configurazione sarà completa. Ora gli agenti devono solo essere distribuiti.
5. Analisi degli errori
5.1. Testare lo script
Se incontri dei problemi con uno script scritto da te, devi controllare le seguenti potenziali fonti di errore:
Lo script si trova nella directory corretta?
Lo script è eseguibile e i permessi di accesso sono corretti? Questo è particolarmente importante se non stai eseguendo l'agente o lo script sotto root o l'account LocalSystem.
-
L'output è conforme alla sintassi indicata? L'output del check locale deve essere conforme alla sintassi descritta nei capitoli Creazione dello script e Funzioni estese, altrimenti non è possibile garantire un'esecuzione priva di errori.
I problemi e gli errori possono sorgere in particolare quando un check locale è destinato a svolgere un'attività che richiede un vero e proprio plug-in di controllo, ad esempio quando l'output del check locale stesso contiene un header di sezione o la definizione di un nome host utilizzato per il trasporto di dati piggyback.
 |
In Linux, quando lo script dell'agente o il plug-in viene richiamato direttamente in una shell, potrebbero essere disponibili variabili d'ambiente diverse rispetto a quando viene richiamato dall'Agent Controller dell'agente Checkmk. In Windows, anche l'Agent Controller viene eseguito sotto l'account LocalSystem, ma la chiamata nel terminale viene effettuata sotto un normale user o amministratore. Oltre alle variabili d'ambiente, questo può significare che mancano i permessi. Per poter analizzare l'output dello script dell'agente il più vicino possibile alle condizioni in cui viene richiamato l'agente Checkmk, dovresti utilizzare l'Agent Controller in modalità dump, se possibile. |
5.2. Testare l'output dell'agente sull'host di destinazione
Se lo script è corretto, è possibile eseguire l'agente sull'host. Con i sistemi operativi Unix come Linux, BSD, ecc. è disponibile il comando seguente. Con l'opzione -A è possibile specificare il numero di righe aggiuntive da visualizzare dopo un hit. Questo numero può essere personalizzato in base al numero di righe di output previste:
root@linux# cmk-agent-ctl dump | grep -v grep | grep -A2 "<<<local"
<<<local:sep(0)>>>
P "My service" humidity=37;40:60;30:70 My service output\nA line with details\nAnother line with details
cached(1618580356,600) 2 "My cached service" count=4 Some output of a long running scriptNell'ultima riga, puoi riconoscere un servizio cache dalle informazioni precedenti di cache con l'intervallo di tempo Unix corrente e l'intervallo di esecuzione in secondi.
In Windows, con PowerShell e la Cmdlet Select-String puoi ottenere un risultato molto simile a quello ottenuto con il comando grep in Linux. Nel comando seguente, le due cifre dietro il parametro Context determinano il numero di righe da emettere prima e dopo l'hit:
PS C:\Program Files (x86)\checkmk\service> ./cmk-agent-ctl.exe dump | Select-String -Pattern "<<<local" -Context 0,3
> <<<local:sep(0)>>>
0 "My 1st service" - This static service is always OK
cached(1618580520,600) 1 "My cached service on Windows" count=4 Some output of a long running script |
A seconda dell'ambiente, del linguaggio di programmazione utilizzato, della versione di Windows e di altre condizioni, in Windows ci si trova spesso di fronte al set di caratteri UTF-16. Inoltre, è frequente la combinazione di Carriage Return e Line Feed per le interruzioni di riga. Tuttavia, Checkmk, in quanto applicazione Linux, si aspetta UTF-8 e Line Feed semplici senza se e senza ma. Il nostro articolo sulla directory di spool include un capitolo che spiega la risoluzione dei problemi legati al set di caratteri. |
5.3. Test dell'output dell'agente Checkmk sul server Checkmk
Come ultimo passo, il processo di output dello script può essere testato sul server Checkmk con il comando cmk - una volta per la scoperta del servizio:
OMD[mysite]:~$ cmk -IIv --detect-plugins=local mycmkserver
Discovering services and host labels on: mycmkserver
mycmkserver:
...
+ EXECUTING DISCOVERY PLUGINS (1)
2 local
SUCCESS - Found 2 services, no host labels... e anche il processo dell'output del servizio con un comando simile:
OMD[mysite]:~$ cmk -nv --detect-plugins=local mycmkserver
Checkmk version 2.0.0p2
+ FETCHING DATA
...
+ PARSE FETCHER RESULTS
Received no piggyback data
My cached service Some output of a long running script(!!), Cache generated 6 minutes 52 seconds ago, Cache interval: 10 minutes 0 seconds, Elapsed cache lifespan: 68.71%
My service My service output\, humidity: 37.00 (warn/crit below 40.00/30.00)(!)Per entrambi i comandi abbiamo accorciato l'output delle righe non rilevanti per questo tema.
Se ci sono errori in un check locale, Checkmk li identificherà nell'output del servizio. Questo vale anche per le metriche errate, per le informazioni false o incomplete nell'output dello script o per uno stato del servizio non valido. Questi messaggi di errore dovrebbero aiutare a identificare rapidamente gli errori in uno script.
6. File e directory
6.1. Directory degli script sull'host di destinazione
| Nome del percorso | Sistema operativo |
|---|---|
|
AIX |
|
FreeBSD |
|
HP-UX, Linux, OpenBSD, OpenWrt e Solaris |
|
Windows |
6.2. Directory cache sull'host di destinazione
I dati della cache delle singole sezioni, compresa la sezione local, vengono archiviati qui e aggiunti nuovamente all'agente ad ogni esecuzione, finché i dati sono validi.
| Nome del percorso | Sistema operativo |
|---|---|
|
AIX |
|
FreeBSD |
|
Linux, OpenWrt e Solaris |