Questa pagina è stata tradotta dall'API Cloud Translation.

Metriche definite dall'utente dell'agente

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

L'agente Monitoring è un daemon collectd. Oltre a esportare molte metriche di sistema e di terze parti predefinite in Cloud Monitoring, l'agente può esportare le tue metriche dell'applicazione collectd in Monitoring come metriche definite dall'utente. I plug-in collectd possono anche esportare in Monitoring.

Un modo alternativo per esportare le metriche delle applicazioni in Monitoring è utilizzare StatsD. Cloud Monitoring fornisce una configurazione predefinita che mappa le metriche StatsD alle metriche definite dall'utente. Se la mappatura ti soddisfa, non hai bisogno dei passaggi di personalizzazione descritti di seguito. Per ulteriori informazioni, consulta il 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

Installa l'agente Monitoring più recente su un'istanza VM e verifica che funzioni. Per aggiornare l'agente, vedi Aggiornamento dell'agente.
Configura collectd per ottenere i dati di monitoraggio dalla tua applicazione. Collectd supporta molti framework di applicazioni e endpoint di monitoraggio standard tramite i plug-in di lettura. Trova un plug-in di lettura adatto a te.
(Facoltativo) Per comodità, aggiungi la documentazione di riferimento di collectd dell'agente alle pagine man del tuo sistema aggiornando la variabile MANPATH e poi eseguendo mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
Le pagine del manuale sono per stackdriver-collectd.

File e directory importanti

I seguenti file e directory, creati installando l'agente, sono pertinenti per l'utilizzo dell'agente Monitoring (collectd):

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

Nota: la configurazione predefinita di sistema di collectd, /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 metriche definite dall'utente dall'agente, inserisci 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 di collectd dell'agente. Puoi aggiungere queste pagine al set di pagine man del tuo sistema. Per maggiori dettagli, consulta la sezione Prima di iniziare.
/etc/init.d/stackdriver-agent: Lo script init per l'agente.

Come Monitoring gestisce le metriche collectd

Come contesto, gli agenti di Monitoring elaborano le metriche collectd e le inviano a Monitoring, che tratta ogni metrica come membro di una delle seguenti categorie:

Metriche definite dall'utente. Le metriche di Collectd 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 collectd vengono inviate a Monitoring utilizzando un'API interna. Vengono accettate ed elaborate solo le metriche nell'elenco delle metriche selezionate.
Metriche eliminate. Le metriche raccolte che non sono presenti nell'elenco delle metriche curate e non sono metriche definite dall'utente vengono eliminate automaticamente da Monitoring. L'agente stesso non è a conoscenza di quali metriche vengono accettate o scartate.

Scrivere metriche definite dall'utente con l'agente

Configura l'agente in modo che invii i punti dati delle metriche a Monitoring. Ogni punto deve essere associato a una metrica definita dall'utente, che definisci con un descrittore di metrica. Questi concetti vengono introdotti in Metriche, serie temporali e risorse e descritti in dettaglio in Struttura delle serie temporali e Panoramica delle metriche definite dall'utente.

Puoi fare in modo che una metrica collectd 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 un'etichetta STRING di Monitoring denominata color, la chiave dei metadati sarà label:color e il valore della chiave potrebbe essere "blue". Puoi avere fino a 10 etichette per tipo di metrica.

Puoi utilizzare una catena di filtri collectd 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 una sola origine dati, tutte le metriche collectd che vuoi utilizzare con questa funzionalità devono avere una sola origine dati.

Esempio

In questo esempio monitoreremo le connessioni Nginx attive da due servizi Nginx, my_service_a e my_service_b. Li invieremo a Monitoring utilizzando una metrica definita dall'utente. Procederemo nel seguente modo:

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

Metriche collectd in entrata

Collectd prevede che le metriche siano costituite dai seguenti componenti. I primi cinque componenti costituiscono l'identificatore collectd 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	Valore o valori previsti
Organizzatore	any
Plug-in	`curl_json`
Istanza plug-in	`nginx_my_service_a` o `nginx_my_service_b`¹
Tipo	`gauge`
Type instance	`active-connections`
`[value]`	qualsiasi valore²

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

Descrittore della metrica di monitoraggio e serie temporale

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

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

Dopo aver progettato il descrittore della metrica, puoi crearlo utilizzando projects.metricDescriptors.create oppure puoi fare in modo che venga creato per te dai metadati delle serie temporali, descritti di seguito. Per saperne di più, consulta Creazione di descrittori di metriche in questa pagina.

I dati delle serie temporali per questo descrittore della metrica devono contenere le seguenti informazioni, a causa del modo in cui è definito ildescrittore della metricaa:

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

Altre informazioni sulle serie temporali, tra cui la risorsa monitorata associata, ovvero 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 nulla di speciale.

La 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 applicare la nuova configurazione eseguendo il seguente comando sull'istanza VM:

sudo service stackdriver-agent restart

Le informazioni sulle metriche definite dall'utente iniziano a essere trasferite a Monitoraggio.

Riferimenti e best practice

Descrittori delle metriche e serie temporali

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

Descrittori delle metriche. Un descrittore della metrica ha le seguenti parti significative:

Un tipo di 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 consentire agli utenti di tenere più facilmente traccia delle metriche. I tipi di metrica non possono contenere trattini. Per le regole di denominazione esatte, consulta Denominazione di tipi di metrica ed etichette.
Fino a 10 etichette per annotare i dati delle metriche, ad esempio device_name, fault_type o response_code. I valori delle etichette non sono specificati nel descrittore della metrica.
Il tipo e il valore dei punti dati, ad esempio "un valore di indicatore di tipo double". Per ulteriori informazioni, consulta MetricKind e ValueType.

Serie temporali. Un punto dati della metrica è composto dai 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 e il tipo di valore 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 di descrittori delle metriche

Non è necessario creare un descrittore della metrica in anticipo. Quando un punto dati arriva in Monitoring, il tipo di metrica, le etichette e il valore del punto possono essere utilizzati per creare automaticamente un descrittore della metrica cumulativa o di tipo indicatore. Per saperne di più, consulta Creazione automatica di descrittori di metriche.

Tuttavia, la creazione di un descrittore della metrica personalizzato presenta dei vantaggi:

Puoi includere una documentazione ben strutturata per la metrica e le relative etichette.
Puoi specificare altri tipi e generi di metriche. Le uniche combinazioni (tipo, tipo) supportate dall'agente sono (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Per saperne di più, vedi Tipi di metriche e tipi di valore.
Puoi specificare tipi di etichetta diversi da STRING.

Se scrivi un punto dati in Monitoring che utilizza un tipo di metrica non definito, viene creato un nuovodescrittore della metricaa per il punto dati. Questo comportamento può essere un problema quando esegui il debug del codice che scrive i dati delle metriche: l'errore ortografico nel tipo di metrica genera descrittori di metriche spurie.

Dopo aver creato un descrittore della metrica o dopo che è stato creato per te, non può essere modificato. Ad esempio, non puoi aggiungere o rimuovere etichette. Puoi solo eliminare il descrittore della metrica, che elimina tutti i relativi dati, e poi ricrearlo nel modo che preferisci.

Per maggiori dettagli sulla creazione di descrittori di metriche, vedi Creazione della metrica.

Prezzi

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

Per ulteriori informazioni, consulta le sezioni di Cloud Monitoring della pagina Prezzi di Google Cloud Observability.

Limiti

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

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

Risoluzione dei problemi

Questa sezione spiega come configurare il plug-in write_log dell'agente Monitoring per scaricare l'intero insieme di punti metrici, inclusi i metadati. Può essere utilizzato per determinare quali punti devono essere trasformati, nonché per assicurarsi 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 root, modifica il seguente file di configurazione:
```
/etc/stackdriver/collectd.conf
```
Subito dopo LoadPlugin write_gcm, aggiungi:
```
LoadPlugin write_log
```
Subito dopo <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
```

Queste modifiche stamperanno una riga di log per ogni valore della metrica segnalato, inclusi l'identificatore collectd completo, le voci di metadati e il valore.

Output di write_log

Se il passaggio precedente è andato a buon fine, nei log di sistema dovresti visualizzare l'output di write_log:

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"}]