Metriche definite dall'utente dall'agente

Questa guida spiega come configurare l'agente Monitoring per riconoscere ed esportare le metriche delle applicazioni in Cloud Monitoring.

L'agente Monitoring è un daemon collectd. Oltre a esportare molte metriche predefinite di sistema e di terze parti in Cloud Monitoring, l'agente può esportare le tue metriche delle applicazioni raccolte in Monitoring come metriche definite dall'utente. Anche i plug-in raccolti possono esportare in Monitoring.

Un modo alternativo per esportare le metriche delle applicazioni in Monitoring è utilizzare StatsD. Cloud Monitoring offre una configurazione predefinita che mappa le metriche StatsD a quelle definite dall'utente. Se la mappatura ti soddisfa, non hai bisogno dei passaggi di personalizzazione descritti di seguito. Per ulteriori informazioni, consulta la sezione relativa al plug-in StatsD.

Per saperne di più sulle metriche, consulta i seguenti documenti:

Questa funzionalità è disponibile solo per gli agenti in esecuzione su Linux. Non è disponibile su Windows.

Prima di iniziare

Installare l'agente Monitoring più recente su un'istanza VM e verificare che funzioni. Per aggiornare l'agente, consulta Aggiornamento dell'agente.
Configura collectd per ottenere i dati di monitoraggio dalla tua applicazione. Collectd supporta molti framework di applicazioni ed endpoint di monitoraggio standard tramite i suoi plug-in di lettura. Trovate un plug-in di lettura che funzioni per voi.
(Facoltativo) Per comodità, aggiungi la documentazione di riferimento raccolta dall'agente alle pagine man del sistema aggiornando la variabile MANPATH ed eseguendo mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
Le pagine man sono per stackdriver-collectd.

File e directory importanti

I seguenti file e directory, creati tramite l'installazione dell'agente, sono pertinenti per l'utilizzo dell'agente Monitoring (raccolti):

/etc/stackdriver/collectd.conf: Il file di configurazione raccolto utilizzato dall'agente. Modifica questo file per cambiare la configurazione generale.

Nota: la configurazione raccolta predefinita di sistema, /etc/collectd.conf, non viene utilizzata dall'agente Monitoring.
/etc/stackdriver/collectd.d/: La directory per i file di configurazione aggiunti dall'utente. Per inviare dall'agente metriche definite dall'utente, devi inserire in questa directory i file di configurazione richiesti, descritti di seguito. Per la compatibilità con le versioni precedenti, l'agente cerca anche i file in /opt/stackdriver/collectd/etc/collectd.d/.
/opt/stackdriver/collectd/share/man/*: La documentazione per la versione dell'agente raccolto. Puoi aggiungere queste pagine al gruppo di pagine man del sistema. Per informazioni dettagliate, consulta Prima di iniziare.
/etc/init.d/stackdriver-agent: Lo script di inizializzazione dell'agente.

In che modo Monitoring gestisce le metriche raccolte

Come background, l'agente Monitoring elabora le metriche raccolte e le invia a Monitoring, che tratta ogni metrica come membro di una delle seguenti categorie:

Metriche definite dall'utente. Le metriche raccolte che hanno la chiave dei metadati stackdriver_metric_type e una singola origine dati vengono gestite come metriche definite dall'utente e inviate a Monitoring utilizzando il metodo projects.timeSeries.create nell'API Monitoring.
Metriche selezionate. Tutte le altre metriche raccolte vengono inviate a Monitoring utilizzando un'API interna. Solo le metriche nell'elenco delle metriche selezionate vengono accettate ed elaborate.
Metriche eliminate. Le metriche raccolte che non sono incluse nell'elenco delle metriche selezionate e non definite dall'utente vengono eliminate automaticamente da Monitoring. L'agente stesso non sa quali metriche vengono accettate o eliminate.

Scrivere metriche definite dall'utente con l'agente

Configuri l'agente per inviare punti dati delle metriche a Monitoring. Ogni punto deve essere associato a una metrica definita dall'utente, che definisci con un descrittore della metrica. Questi concetti sono presentati in Metriche, serie temporali e risorse e descritti dettagliatamente negli articoli Struttura delle serie temporali e Panoramica delle metriche definite dall'utente.

Puoi fare in modo che una metrica raccolta venga trattata come una metrica definita dall'utente aggiungendo i metadati appropriati alla metrica:

stackdriver_metric_type : (obbligatorio) il nome della metrica esportata. Esempio: custom.googleapis.com/my_custom_metric.
label:[LABEL] : (facoltativo) etichette aggiuntive per la metrica esportata. Ad esempio, se vuoi che un'etichetta STRING di monitoraggio sia denominata color, la chiave dei metadati sarà label:color e il valore della chiave potrebbe essere "blue". Puoi definire fino a 10 etichette per tipo di metrica.

Puoi utilizzare una catena di filtri raccolti per modificare i metadati delle metriche. Poiché le catene di filtri non possono modificare l'elenco delle origini dati e le metriche definite dall'utente supportano solo una singola origine dati, qualsiasi metrica raccolta che vuoi utilizzare con questa struttura deve avere una singola origine dati.

Esempio

In questo esempio monitoreremo le connessioni Nginx attive da due servizi Nginx, my_service_a e my_service_b. Le invieremo a Monitoring utilizzando una metrica definita dall'utente. Adotteremo i seguenti passaggi:

Identificare le metriche raccolte per ogni servizio Nginx.
Definisci un descrittore della metrica di Monitoring.
Configurare una catena di filtri raccolti per aggiungere metadati alle metriche raccolte, in modo da soddisfare le aspettative dell'agente Monitoring.

Metriche raccolte in entrata

Il report raccolto prevede che le metriche siano composte dai seguenti componenti. I primi cinque componenti costituiscono l'identificatore raccolto per la metrica:

    Host, Plugin, Plugin-instance, Type, Type-instance, [value]

In questo esempio, le metriche che vuoi inviare come metrica definita dall'utente hanno i seguenti valori:

Componente	Valori previsti
Organizzatore	qualsiasi
Plug-in	`curl_json`
Istanza plug-in	`nginx_my_service_a` oppure `nginx_my_service_b`¹
Tipo	`gauge`
Digita istanza	`active-connections`
`[value]`	qualsiasi valore²

Note:
¹ Nell'esempio, questo valore codifica sia il nome dell'applicazione (Nginx) sia il nome del servizio connesso.
² Il valore è in genere un timestamp e un numero a precisione doppia. Monitoring gestisce i dettagli dell'interpretazione dei vari tipi di valori. I valori composti non sono supportati dall'agente Monitoring.

Serie temporale e descrittore della metrica di monitoraggio

In Monitoring, progetta un descrittore della metrica per la metrica definita dall'utente. Il descrittore seguente è una scelta ragionevole per i dati di questo esempio:

Nome: custom.googleapis.com/nginx/active_connections
Etichette:
- service_name (STRING): il nome del servizio connesso a Nginx.
Tipo: GAUGE
Tipo: DOUBLE

Dopo aver progettato il descrittore della metrica, puoi crearlo utilizzando projects.metricDescriptors.create o lasciarlo creare per te dai metadati delle serie temporali, discussi di seguito. Per saperne di più, consulta la sezione Creazione dei descrittori delle metriche in questa pagina.

I dati della serie temporale per questo descrittore di metrica devono contenere le seguenti informazioni, a causa del modo in cui è definito il descrittore della metrica:

Tipo di metrica: custom.googleapis.com/nginx/active_connections
Valori delle etichette delle metriche:
- service_name: "my_service_a" o "my_service_b"

Altre informazioni sulle serie temporali, tra cui la risorsa monitorata associata (l'istanza VM che invia i dati) e il punto dati della metrica, vengono ottenute automaticamente dall'agente per tutte le metriche. Non devi fare niente di speciale.

La tua catena di filtri

Crea un file /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf contenente il seguente codice:

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  <Rule "jump_to_custom_metrics_from_curl_json">
    # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
    <Match regex>
      Plugin "^curl_json$"
      PluginInstance "^nginx_"
    </Match>
    <Target "jump">
      # Go execute the following chain; then come back.
      Chain "PreCache_curl_json"
    </Target>
  </Rule>
  # Continue processing metrics in the default "PreCache" chain.
</Chain>

# Following is a NEW filter chain, just for your metric.
# It is only executed if the default chain "jumps" here.
<Chain "PreCache_curl_json">

  # The following rule does all the work for your metric:
  <Rule "rewrite_curl_json_my_special_metric">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^curl_json$"                   # Match on plugin.
      PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
      Type "^gauge$"                         # Match on type.
      TypeInstance "^active-connections$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
      # Specify a value for the "service_name" label; clean it up in the next Target:
      MetaData "label:service_name" "%{plugin_instance}"
    </Target>

    <Target "replace">
      # Remove the "nginx_" prefix in the service_name to get the real service name:
      MetaData "label:service_name" "nginx_" ""
    </Target>
  </Rule>

  # The following rule is run after rewriting your metric, or
  # if the metric wasn't one of your user-defined metrics. The rule returns
  # to the default "PreCache" chain. The default processing
  # will write all metrics to Cloud Monitoring,
  # which will drop any unrecognized metrics: ones that aren't
  # in the list of curated metrics and don't have
  # the user-defined metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

Carica la nuova configurazione

Riavvia l'agente per scegliere la nuova configurazione eseguendo questo comando sulla tua istanza VM:

sudo service stackdriver-agent restart

Le informazioni sulle metriche definite dall'utente iniziano a confluire in Monitoring.

Riferimenti e best practice

Descrittori delle metriche e serie temporali

Per un'introduzione alle metriche di Cloud Monitoring, consulta Metriche, serie temporali e risorse. Ulteriori dettagli sono disponibili in Panoramica delle metriche definite dall'utente e Struttura delle serie temporali.

Descrittori delle metriche. Un descrittore della metrica contiene i seguenti elementi significativi:

Un tipo del modulo custom.googleapis.com/[NAME1]/.../[NAME0]. Ad esempio:
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
La denominazione consigliata è gerarchica per facilitare il tracciamento delle metriche da parte degli utenti. I tipi di metrica non possono contenere trattini; per le regole di denominazione esatte, consulta Assegnazione di etichette e tipi di metriche di denominazione.
Fino a 10 etichette per annotare i dati delle metriche, come device_name, fault_type o response_code. I valori delle etichette non sono specificati nel descrittore della metrica.
Il tipo e il tipo di valore dei punti dati, ad esempio "un valore indicatore di tipo decimale". Per maggiori informazioni, vedi MetricKind e ValueType.

Serie temporali: Un punto dati di una metrica contiene i seguenti elementi significativi:

Il tipo di descrittore della metrica associato.
Valori per tutte le etichette del descrittore della metrica.
Un valore con timestamp coerente con il tipo di valore e il tipo del descrittore della metrica.
La risorsa monitorata da cui provengono i dati, in genere un'istanza VM. Lo spazio per la risorsa è integrato, quindi il descrittore non ha bisogno di un'etichetta separata.

Creazione dei descrittori delle metriche

Non è necessario creare in anticipo un descrittore della metrica. Quando un punto dati arriva in Monitoring, è possibile utilizzare il tipo di metrica, le etichette e il valore del punto per creare automaticamente un indicatore o un descrittore della metrica cumulativa. Per maggiori informazioni, consulta Creazione automatica dei descrittori delle metriche.

Tuttavia, la creazione di un descrittore della metrica personalizzato offre alcuni vantaggi:

Puoi includere una documentazione esaustiva per la metrica e le relative etichette.
Puoi specificare altri tipi e tipi di metriche. Le uniche combinazioni (tipo, tipo) supportate dall'agente sono (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Per ulteriori informazioni, consulta Tipi di metriche e tipi di valore.
Puoi specificare tipi di etichetta diversi da STRING.

Se scrivi in Monitoring un punto dati che utilizza un tipo di metrica non definito, viene creato un nuovo descrittore della metrica per quel punto dati. Questo comportamento può rappresentare un problema quando esegui il debug del codice che scrive i dati della metrica. Se inserisci un tipo di metrica errato, i descrittori delle metriche potrebbero essere errati.

Una volta creato o creato per te, un descrittore della metrica non può essere modificato. Ad esempio, non puoi aggiungere o rimuovere etichette. Puoi solo eliminare il descrittore della metrica, che ne elimina tutti i dati, per poi ricreare il descrittore come preferisci.

Per saperne di più sulla creazione dei descrittori delle metriche, consulta Creazione della metrica.

Prezzi

In generale, le metriche di sistema di Cloud Monitoring sono gratuite, mentre quelle provenienti da sistemi, agenti o applicazioni esterni. Le metriche fatturabili vengono fatturate in base al numero di byte o al numero di campioni importati.

Per maggiori informazioni sui prezzi di Cloud Monitoring, consulta i seguenti documenti:

Limiti

Cloud Monitoring prevede dei limiti per il numero di serie temporali delle metriche e il numero di descrittori delle metriche definiti dall'utente in ogni progetto. Per maggiori dettagli, consulta Quote e limiti.

Se scopri di aver creato descrittori delle metriche che non vuoi più, puoi trovarli ed eliminarli utilizzando l'API Monitoring. Per ulteriori informazioni, consulta projects.metricDescriptors.

Risoluzione dei problemi

Questa sezione spiega come configurare il plug-in write_log dell'agente Monitoring per eseguire il dump dell'intero set di punti metrica, inclusi i metadati. Questo può essere usato per determinare quali punti devono essere trasformati e per garantire che le trasformazioni si comportino come previsto.

Abilitazione di write_log

Il plug-in write_log è incluso nel pacchetto stackdriver-agent. Per attivare il plug-in:

Come principale, modifica il seguente file di configurazione:
```
/etc/stackdriver/collectd.conf
```
Subito dopo il giorno LoadPlugin write_gcm, aggiungi:
```
LoadPlugin write_log
```
Subito dopo il giorno <Plugin "write_gcm">…</Plugin>, aggiungi:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Cerca <Target "write">…</Target> e dopo ogni Plugin "write_gcm", aggiungi:
```
Plugin "write_log"
```
Salva le modifiche e riavvia l'agente:
```
sudo service stackdriver-agent restart
```

Per queste modifiche verrà stampata una riga di log per ogni valore della metrica riportato, inclusi l'identificatore raccolto completo, le voci di metadati e il valore.

Output di write_log

Se hai avuto esito positivo nel passaggio precedente, dovresti vedere l'output di write_log nei log di sistema:

Linux basato su Debian: /var/log/syslog
Linux basato su Red Hat: /var/log/messages

Le righe di esempio riportate di seguito sono state formattate per facilitarne la lettura in questo documento.

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[0], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]