Plug-in StatsD

Attenzione: a partire dal 28 settembre 2026, l'agente Monitoring legacy non sarà più supportato. Non vengono più forniti manutenzione standard e correzioni di bug. Ti consigliamo vivamente di eseguire la migrazione a una delle alternative supportate. Per saperne di più su questo ritiro, consulta Fine del supporto degli agenti di monitoraggio e logging legacy.

StatsD è un protocollo per l'invio di metriche e un daemon per l'aggregazione dei dati delle metriche. Configurando il plug-in StatsD dell'agente Monitoring, l'agente funge da daemon StatsD che scrive le metriche in Monitoring.

L'utilizzo del plug-in StatsD con la sua configurazione predefinita è il modo più semplice per inserire le metriche definite dall'utente in Monitoring. Il plug-in StatsD è disponibile solo nell'agente Stackdriver Monitoring per Linux.

L'agente Monitoring può anche esportare altre metriche collectd come metriche definite dall'utente, ma non esiste una semplice configurazione predefinita. Per maggiori dettagli, consulta Metriche definite dall'utente dall'agente.

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

Discovery

Il monitoraggio non rileva automaticamente StatsD. Per utilizzare le metriche StatsD, configura il plug-in StatsD come descritto nella sezione successiva.

Configurazione del plug-in StatsD

Prerequisiti

Il plug-in StatsD richiede la versione 5.5.2-356 o successive dell'agente Monitoring. Per aggiornare l'agente, consulta Aggiornamento dell'agente.

Attivare il plug-in

Sulla tua istanza VM supportata che esegue Linux, esegui le seguenti operazioni:

1. Scarica statsd.conf e inseriscilo in /etc/stackdriver/collectd.d/ utilizzando questo comando:

   (cd /etc/stackdriver/collectd.d/ && sudo curl -O https://raw.githubusercontent.com/Stackdriver/stackdriver-agent-service-configs/master/etc/collectd.d/statsd.conf)
   

2. Il file di configurazione predefinito indica all'agente di accettare le metriche StatsD sulla porta StatsD predefinita, 8125.

   Se vuoi inviare alcune metriche al tuo daemon StatsD e altre metriche al daemon StatsD dell'agente, modifica le impostazioni della porta nel file di configurazione.

3. Riavvia l'agente Monitoring per recuperare la configurazione di StatsD eseguendo questo comando:

   sudo service stackdriver-agent restart
   

Per saperne di più sul plug-in collectd statsd, consulta Plug-in:StatsD.

Mappatura predefinita alle metriche definite dall'utente

Per iniziare rapidamente, il plug-in StatsD dell'agente viene fornito con una configurazione collectd predefinita che esegue il mapping delle metriche StatsD alle metriche definite dall'utente di Stackdriver:

• Tutte le metriche del plug-in StatsD hanno statsd nel componente plugin di collectd.

• Ogni tipo di metrica StatsD, contenuto nel componente collectd type, ha un nome di tipo di metrica definito dall'utente corrispondente.

• Il nome della metrica StatsD, contenuto nel componente collectd type_instance, viene memorizzato come valore di un'etichetta denominata metric.

  Il valore dell'etichetta metric è diverso per il tipo di metrica Timer: include sia il nome della metrica sia il nome di un contatore: media, superiore, inferiore, somma, percentile 50 e percentile 95.

Ad esempio, la tabella seguente mostra come i tipi di metriche StatsD supportati e il nome della metrica vengono mappati alle metriche definite dall'utente di Monitoring:

Tipo StatsD	Nome StatsD	Tipo di metrica Stackdriver	Tipo di metrica	Tipo di valore	Etichetta o etichette della metrica
Contatore	my.counter	custom.googleapis.com/statsd/derive	Cumulativo	Int64	metrica:my.counter
Misuratore	my.gauge	custom.googleapis.com/statsd/gauge	Misuratore	Doppio	metrica:my.gauge
Imposta	my.set	custom.googleapis.com/statsd/objects	Misuratore	Doppio	metrica:my.set
Timer^1	my.timer	custom.googleapis.com/statsd/latency	Misuratore	Doppio	metrica:my.timer-average
		(stesso)	(stesso)	(stesso)	metrica:my.timer-upper
		(stesso)	(stesso)	(stesso)	metrica:my.timer-lower
		(stesso)	(stesso)	(stesso)	metrica:my.timer-sum
		(stesso)	(stesso)	(stesso)	metric:my.timer-percentile-50
		(stesso)	(stesso)	(stesso)	metric:my.timer-percentile-95
		custom.googleapis.com/statsd/gauge	Misuratore	(stesso)	metrica:my.timer-count

Note:
¹ Esiste una sequenza in entrata di metriche del timer StatsD con lo stesso nome. L'agente aggrega le metriche del timer StatsD ed esporta i dati di riepilogo in 7 diverse serie temporali.

Per ulteriori informazioni sui tipi di StatsD, consulta le specifiche di StatsD.

Personalizzare le metriche esportate

La configurazione predefinita di StatsD è progettata per consentirti di iniziare rapidamente. Questa sezione ti aiuta a personalizzare la configurazione in base a esigenze più complesse.

Devi avere familiarità con le metriche definite dall'utente. Per un'introduzione alle metriche, consulta Metriche, serie temporali e risorse. Per saperne di più, consulta la panoramica delle metriche definite dall'utente.

Puoi personalizzare i seguenti elementi:

• Puoi modificare i valori assegnati all'etichetta metric predefinita. L'utilizzo di più valori delle etichette comporta un numero maggiore di serie temporali nella metrica definita dall'utente. L'utilizzo di un numero inferiore di valori di etichetta comporta un numero inferiore di serie temporali.

• Puoi modificare i tipi di metriche definite dall'utente. Non devi utilizzare i tipi predefiniti forniti nella configurazione predefinita. Ad esempio, potresti identificare le metriche con un determinato nome e utilizzare un tipo di metrica definita dall'utente diverso.

• Se modifichi i tipi di metriche definite dall'utente, puoi anche modificare le etichette associate a ogni tipo. La configurazione predefinita ha una sola etichetta, ma puoi aggiungerne altre o modificare la chiave di etichetta.

Se modifichi i tipi di metrica, devi definire i nuovi tipi di metrica definita dall'utente nell'API Monitoring. Per maggiori dettagli, consulta la sezione seguente, Progettazione di un tipo di metrica.

Esempio

Supponiamo che tu stia utilizzando StatsD per monitorare un'applicazione composta da due servizi, my_service_a e my_service_b. Per ogni servizio, vuoi esportare in Monitoring una metrica di conteggio che rappresenti il numero di richieste non riuscite. Non vuoi utilizzare i tipi di metrica StatsD predefiniti.

Metriche collectd in entrata

Prima di definire i tuoi tipi di metriche, è importante comprendere la struttura di una metrica collectd e in che modo una metrica StatsD viene mappata per impostazione predefinita nelle metriche definite dall'utente.

Le metriche di Collectd, incluse quelle di StatsD, includono i seguenti componenti:

    Host, Plugin, Plugin-instance, Type, Type-instance

In questo esempio, le metriche StatsD che vuoi esportare hanno i seguenti identificatori in collectd:

Componente	Valore o valori previsti
Organizzatore	any
Plug-in	statsd
Istanza plug-in	unset^1
Tipo	derive^2
Type instance	[SERVICE_NAME].GET.[CODE]^3
[VALUE]	qualsiasi valore^4

Note:
¹ Il plug-in StatsD attualmente lascia vuoto questo componente.
² Una metrica Contatore StatsD è mappata al tipo derive di collectd. ³ Ad esempio, un'istanza di tipo potrebbe essere my_service_a.GET.500. ⁴ [VALUE] è in genere un timestamp e un numero a precisione doppia.

La seguente tabella mostra come questa metrica verrebbe mappata per impostazione predefinita:

Tipo StatsD	Nome StatsD	Tipo di metrica Stackdriver	Tipo di metrica	Tipo di valore	Etichette metriche
Contatore	my_service_a.GET.500	custom.googleapis.com/statsd/derive	Cumulativo	Int64	metric:my_servce_a.GET.500
Contatore	my_service_b.GET.403	custom.googleapis.com/statsd/derive	Cumulativo	Int64	metric:my_servce_b.GET.403

La mappatura predefinita potrebbe presentare alcune difficoltà:

• Questa metrica del contatore specifica ([SERVICE_NAME].GET.[CODE]) ha lo stesso tipo di metrica definita dall'utente di tutte le altre metriche del contatore. Non puoi ottenere facilmente solo i dati di questa metrica, perché Stackdriver al momento non supporta le ricerche con espressioni regolari sulle etichette.

• Non puoi recuperare facilmente i dati per singoli servizi o singoli codici di risposta nei tuoi dati. Ad esempio, non puoi ottenere facilmente il numero totale di errori (di tutti i tipi) che si sono verificati in my_service_a.

• La configurazione predefinita esporta tutte le metriche StatsD in Stackdriver, il che potrebbe essere costoso se ti interessano solo determinate metriche.

Progettare un tipo di metrica

Per una discussione completa sulla creazione di tipi di metriche, vedi Creare un tipo di metrica definito dall'utente.

Il seguente tipo di metrica definita dall'utente è una scelta ragionevole per i dati in questo esempio, perché contiene solo la metrica StatsD che ti interessa e perché la scelta delle etichette aiuta a organizzare meglio i dati:

• Tipo: custom.googleapis.com/http/request_errors
• Etichette:
  • service_name (STRINGA): il nome del servizio.
  • response_code (INT64): il codice di risposta HTTP.
• Kind: CUMULATIVE
• Tipo di valore: INT64

La tabella seguente mostra il mapping desiderato da StatsD a Stackdriver:

Tipo StatsD	Nome StatsD	Tipo di metrica Stackdriver	Tipo di metrica	Tipo di valore	Etichette metriche
Contatore	my_service_a.GET.500	custom.googleapis.com/http/request_errors	Cumulativo	Int64	service_name:my_service_a, response_code:500
Contatore	my_service_b.GET.403	custom.googleapis.com/http/request_errors	Cumulativo	Int64	service_name:my_service_b, response_code:403

Una volta progettato il tipo di metrica, crealo utilizzando metricDescriptors.create. Per informazioni su come consentire a Monitoring di creare il tipo di metrica per te, consulta Creazione automatica dei descrittori delle metriche.

Configurazione mappatura

Per esportare la metrica StatsD nel nuovo tipo di metrica definita dall'utente, sostituisci i contenuti della configurazione predefinita del plug-in StatsD, /etc/stackdriver/collectd.d/statsd.conf, con il seguente codice:

<Plugin statsd>
  Host "127.0.0.1"
  Port "8125"
  DeleteSets true
  TimerPercentile 50.0
  TimerPercentile 95.0
  TimerLower true
  TimerUpper true
  TimerSum true
  TimerCount true
</Plugin>

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">
  # The following rule does all the work for your metric:
  <Rule "rewrite_request_errors">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^statsd$"
      TypeInstance "^.*\\.GET\\..*$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/http/request_errors"
      # Initialize the labels from the "type_instance" label; clean the values up in the next Target below.
      MetaData "label:service_name" "%{type_instance}"
      MetaData "label:response_code" "%{type_instance}"
    </Target>

    <Target "replace">
      # Remove ".GET.[code]" to get the real service name.
      MetaData "label:service_name" "\\.GET\\.[0-9]*$" ""
      # Remove "[service].GET." to get the real response code.
      MetaData "label:response_code" "^[^\\.]*\\.GET\\." ""
    </Target>
  </Rule>
</Chain>

Nota :l'installazione di questo file di configurazione rimuove il mapping StatsD predefinito. Se vuoi conservare il mapping predefinito per altre metriche StatsD, devi aggiungere Rule dalla configurazione StatsD predefinita dopo la nuova regola rewrite_request_errors.

Riavvia l'agente

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 visualizzate in Monitoring immediatamente.

Passaggi successivi

La personalizzazione del plug-in StatsD è uguale alla personalizzazione delle metriche collectd per Monitoring. Per ulteriori informazioni, consulta le sezioni Riferimento e Risoluzione dei problemi dell'articolo Metriche definite dall'utente dall'agente.