Metriche definite dall'utente dall'agente

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

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

Un modo alternativo per esportare le metriche delle applicazioni in Monitoring consiste nell'utilizzare StatsD. Cloud Monitoring offre una configurazione predefinita che mappa le metriche StatsD a quelle definite dall'utente. Se la mappatura ti soddisfa, non sono necessari i passaggi di personalizzazione descritti di seguito. Per saperne di più, consulta il plug-in StatsD.

Per ulteriori informazioni sulle metriche, consulta i seguenti documenti:

Questa funzionalità è disponibile soltanto per gli agenti che eseguono 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 la sezione Aggiornamento dell'agente.

  • Configura collected per ottenere i dati di monitoraggio dalla tua applicazione. Collected supporta molti framework di applicazioni ed endpoint di monitoraggio standard tramite i suoi plug-in di lettura. Trova un plug-in di lettura adatto a te.

  • (Facoltativo) Per comodità, aggiungi la documentazione di riferimento raccolta dell'agente alle pagine man del tuo sistema aggiornando la variabile MANPATH e quindi eseguendo mandb:

    export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb

    Le pagine dedicate agli utenti si riferiscono a stackdriver-collectd.

Directory e file importanti

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

/etc/stackdriver/collectd.conf

Il file di configurazione raccolto utilizzato dall'agente. Modifica questo file per cambiare la configurazione generale.

/etc/stackdriver/collectd.d/

La directory per i file di configurazione aggiunti dall'utente. Per inviare metriche definite dall'utente dall'agente, posiziona i file di configurazione richiesti, discussi di seguito, in questa directory. 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 relativa alla versione della raccolta dell'agente. Puoi aggiungere queste pagine al gruppo di man pagine del tuo sistema; consulta la sezione Prima di iniziare per i dettagli.

/etc/init.d/stackdriver-agent

Lo script init per l'agente.

In che modo Monitoring gestisce le metriche raccolte

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

  • Metriche definite dall'utente Le metriche raccolte che hanno la chiave di metadati stackdriver_metric_type e un'unica 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 ignorate. Le metriche raccolte che non sono nell'elenco delle metriche selezionate e non sono metriche definite dall'utente vengono ignorate senza problemi da Monitoring. L'agente non sa quali metriche sono accettate o ignorate.

Scrivi metriche definite dall'utente con l'agente

Configura 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 vengono introdotti in Metriche, serie temporali e risorse e descritti in dettaglio nelle sezioni Struttura delle serie temporali e Panoramica delle metriche definite dall'utente.

Puoi fare in modo che una metrica raccolta venga considerata 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 monitoraggio 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 raccolti per modificare i metadati per le metriche. Poiché le catene di filtri non possono modificare l'elenco di origini dati e le metriche definite dall'utente supportano solo una singola origine dati, tutte le metriche raccolte che vuoi utilizzare con questa struttura devono 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. Invieremo questi dati a Monitoring utilizzando una metrica definita dall'utente. Seguiremo questi passaggi:

  1. Identifica le metriche raccolte per ogni servizio Nginx.

  2. Definire un descrittore della metrica Monitoring.

  3. Configura una catena di filtri raccolti per aggiungere metadati alle metriche raccolte, in modo da soddisfare le aspettative dell'agente Monitoring.

Metriche raccolte in entrata

La raccolta raccoglie 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 da 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_b1
Tipo gauge
Digita l'istanza active-connections
[value] qualsiasi valore2

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

Descrittore della metrica di monitoraggio e serie temporali

Sul lato Monitoring, progetta un descrittore della metrica per la metrica definita dall'utente. Il descrittore seguente è 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.
  • Tipo: GAUGE
  • Tipo: DOUBLE

Dopo aver progettato il descrittore della metrica, puoi crearlo utilizzando projects.metricDescriptors.create oppure lasciare che venga creato per te dai metadati della serie temporale, descritti di seguito. Per ulteriori informazioni, consulta Creazione dei descrittori delle 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 è descritto 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 relative alle serie temporali, tra cui la risorsa monitorata associata, l'istanza VM che invia i dati, e il punto dati della metrica vengono acquisite automaticamente dall'agente per tutte le metriche. Non devi fare nulla 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 recuperare la nuova configurazione eseguendo il comando seguente 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 nelle sezioni Panoramica delle metriche definite dall'utente e Struttura della serie temporale.

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

  • 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 rendere le metriche più facili da monitorare. I tipi di metriche non possono contenere trattini; per le regole di denominazione esatte, consulta Tipi di metriche ed etichette di denominazione.

  • Fino a 10 etichette per annotare i dati della metrica, ad esempio 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 di misurazione di tipo doppio". Per ulteriori informazioni, consulta MetricKind e ValueType.

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

  • Il tipo del descrittore della metrica associata.

  • Valori per tutte le etichette del descrittore della metrica.

  • Un valore con timestamp che corrisponde al tipo e al 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 al descrittore non serve un'etichetta separata.

Creazione dei descrittori delle metriche

Non devi creare un descrittore della metrica in anticipo. 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 ulteriori informazioni, consulta la sezione Creazione automatica di descrittori delle metriche.

Tuttavia, offre la possibilità di creare un descrittore della metrica personalizzato:

  • Puoi includere della documentazione utile per la metrica e le relative etichette.

  • Puoi specificare altri tipi e metriche di tipo. Le uniche combinazioni (tipo, tipo) supportate dall'agente sono (GAUGE, DOUBLE) e (CUMULATIVE, INT64). Per ulteriori informazioni, consulta Tipi di metriche e valori.

  • Puoi specificare tipi di etichette diversi da STRING.

Se scrivi un punto dati in Monitoring che utilizza un tipo di metrica non definito, viene creato un nuovo descrittore della metrica per il punto dati. Questo comportamento può essere un problema quando esegui il debug del codice che scrive i dati delle metriche, poiché l'errore di ortografia nel tipo di metrica dà origine a descrittori di metriche falsi.

Dopo aver creato un descrittore della metrica o dopo averlo creato per te, non puoi modificarlo. Ad esempio, non puoi aggiungere o rimuovere etichette. Puoi eliminare solo il descrittore della metrica, che elimina tutti i suoi dati, e poi ricrearlo nel modo che preferisci.

Per ulteriori dettagli sulla creazione dei descrittori delle metriche, consulta Creazione della metrica.

Costi e limiti

Cloud Monitoring addebita i costi delle metriche raccolte, sia quelle definite dall'utente sia quelle dell'agente, in base al volume dei dati delle metriche ricevuti. Per i dettagli, consulta Prezzi della suite operativa di Google Cloud.

Oltre ai prezzi, Cloud Monitoring prevede limiti relativi al numero di serie temporali delle metriche e al numero di descrittori delle metriche definite dall'utente in ogni progetto GCP. Per maggiori dettagli, consulta Quote e limiti.

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

Risolvere i problemi

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

Abilitazione di write_log

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

  1. Come root, modifica il seguente file di configurazione:

    /etc/stackdriver/collectd.conf

  2. Subito dopo il giorno LoadPlugin write_gcm, aggiungi:

    LoadPlugin write_log

  3. Subito dopo il giorno <Plugin "write_gcm">…</Plugin>, aggiungi:

    <Plugin "write_log">
  Format JSON
</Plugin>

  4. Cerca <Target "write">…</Target> e, dopo ogni Plugin "write_gcm", aggiungi:

    Plugin "write_log"

  5. Salva le modifiche e riavvia l'agente:

    sudo service stackdriver-agent restart

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

Output di write_log

Se hai completato l'operazione nel passaggio precedente, dovresti visualizzare l'output di write_log nei log di sistema:

  • Linux basato su Debian: /var/log/syslog
  • Linux basato su cappello rosso: /var/log/messages

Le righe di esempio riportate di seguito sono state formattate per semplificarne 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"}]