StatsD-Plug-in

Achtung: Am 28. September 2026 hat der Legacy-Monitoring-Agent das Ende des Supports erreicht. Standardwartung und Fehlerkorrekturen werden nicht mehr bereitgestellt. Wir empfehlen dringend, zu einer der unterstützten Alternativen zu migrieren. Weitere Informationen zu dieser Einstellung finden Sie unter Ende des Supports für Legacy-Monitoring- und -Logging-Agents.

StatsD ist ein Protokoll zum Senden von Messwerten und ein Daemon für die Aggregation von Messwertdaten. Durch die Konfiguration des StatsD-Plug-ins des Monitoring-Agents fungiert der Agent als StatsD-Daemon, der Messwerte in Monitoring schreibt.

Das StatsD-Plug-in mit seiner Standardkonfiguration ist die einfachste Möglichkeit, benutzerdefinierte Messwerte in Monitoring zu übertragen. Das StatsD-Plug-in ist nur im Linux-Stackdriver Monitoring-Agent verfügbar.

Der Monitoring-Agent kann auch andere collectd-Messwerte als benutzerdefinierte Messwerte exportieren, aber es gibt keine einfache Standardkonfiguration. Weitere Informationen finden Sie unter Benutzerdefinierte Messwerte vom Agenten.

Diese Funktion ist nur für Agenten verfügbar, die unter Linux ausgeführt werden. Es ist unter Windows nicht verfügbar.

Erkennung

StatsD wird beim Monitoring nicht automatisch erkannt. Wenn Sie StatsD-Messwerte verwenden möchten, konfigurieren Sie das StatsD-Plug-in wie im nächsten Abschnitt beschrieben.

StatsD-Plug-in konfigurieren

Voraussetzungen

Für das StatsD-Plug-in ist Version 5.5.2-356 oder höher des Monitoring-Agents erforderlich. Informationen zum Aktualisieren des Agents finden Sie unter Agent aktualisieren.

Plug-in aktivieren

Führen Sie auf Ihrer unterstützten VM-Instanz unter Linux folgende Schritte aus:

1. Laden Sie die Datei statsd.conf herunter und speichern Sie sie mit dem folgenden Befehl im Verzeichnis /etc/stackdriver/collectd.d/:

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

2. Die Standardkonfigurationsdatei weist den Agent an, StatsD-Messwerte am Standard-StatsD-Port 8125 zu akzeptieren.

   Wenn Sie einige Messwerte an Ihren eigenen StatsD-Daemon und andere an den StatsD-Daemon des Agents senden möchten, ändern Sie die Porteinstellungen in der Konfigurationsdatei.

3. Starten Sie den Monitoring-Agent neu, um die StatsD-Konfiguration zu übernehmen. Führen Sie dazu folgenden Befehl aus:

   sudo service stackdriver-agent restart
   

Weitere Informationen zum collectd statsd-Plug-in finden Sie unter Plugin:StatsD.

Standardzuordnung zu benutzerdefinierten Messwerten

Damit Sie schnell loslegen können, enthält das StatsD-Plug-in des Agents eine Standardkonfiguration für collectd, die StatsD-Messwerte benutzerdefinierten Stackdriver-Messwerten zuordnet:

• Alle Messwerte aus dem StatsD-Plug-in weisen statsd in der collectd-Komponente plugin auf.

• Jeder StatsD-Messwerttyp, der in der collectd-Komponente type enthalten ist, hat einen entsprechenden benutzerdefinierten Messwerttypnamen.

• Der StatsD-Messwertname, der in der collectd-Komponente type_instance enthalten ist, wird als Wert eines Labels namens metric gespeichert.

  Der Wert des Labels metric unterscheidet sich für den Messwerttyp Timer: Er enthält sowohl den Messwertnamen als auch den Namen eines Zählers: "average", "upper", "lower", "sum", "percentile-50" und "percentile-95".

In der folgenden Tabelle sehen Sie beispielsweise, wie die unterstützten StatsD-Messwerttypen und der Name des Messwerts benutzerdefinierten Messwerten in Monitoring zugeordnet werden:

StatsD-Typ	StatsD-Name	Stackdriver-Messwerttyp	Messwertart	Werttyp	Messwertlabel(s)
Zähler	my.counter	custom.googleapis.com/statsd/derive	CUMULATIVE	INT64	metric:my.counter
Messgerät	my.gauge	custom.googleapis.com/statsd/gauge	GAUGE	DOUBLE	metric:my.gauge
Set	my.set	custom.googleapis.com/statsd/objects	GAUGE	DOUBLE	metric:my.set
Timer^1	my.timer	custom.googleapis.com/statsd/latency	GAUGE	DOUBLE	metric:my.timer-average
		(gleich)	(gleich)	(gleich)	metric:my.timer-upper
		(gleich)	(gleich)	(gleich)	metric:my.timer-lower
		(gleich)	(gleich)	(gleich)	metric:my.timer-sum
		(gleich)	(gleich)	(gleich)	metric:my.timer-percentile-50
		(gleich)	(gleich)	(gleich)	metric:my.timer-percentile-95
		custom.googleapis.com/statsd/gauge	GAUGE	(gleich)	metric:my.timer-count

Hinweise:
¹ Es geht eine Reihe von StatsD-Timer-Messwerten mit demselben Namen ein. Der Agent aggregiert StatsD-Timer-Messwerte und exportiert zusammenfassende Daten in sieben verschiedene Zeitachsen.

Weitere Informationen zu StatsD-Typen finden Sie in der StatsD-Spezifikation.

Exportierte Messwerte anpassen

Der StatsD-Standardkonfiguration wurde für einen schnellen Einstieg entwickelt. Dieser Abschnitt hilft Ihnen dabei, die Konfiguration an komplexere Anforderungen anzupassen.

Sie sollten mit benutzerdefinierten Messwerten vertraut sein. Eine Einführung in Messwerte finden Sie unter Messwerte, Zeitachsen und Ressourcen. Weitere Informationen finden Sie unter Übersicht über benutzerdefinierte Messwerte.

Folgende Elemente lassen sich anpassen:

• Sie können die Werte ändern, die dem Standardlabel metric zugewiesen sind. Wenn Sie mehr Labelwerte verwenden, enthält der benutzerdefinierte Messwert mehr Zeitreihen. Wenn Sie weniger Labelwerte verwenden, erhalten Sie weniger Zeitreihen.

• Sie können die Typen benutzerdefinierter Messwerte ändern. Sie müssen nicht die vordefinierten Typen verwenden, die in der Standardkonfiguration enthalten sind. Sie können beispielsweise Messwerte mit einem bestimmten Namen identifizieren und einen anderen benutzerdefinierten Messwerttyp für sie verwenden.

• Wenn Sie die benutzerdefinierten Messwerttypen ändern, können Sie auch die Labels ändern, die mit den einzelnen Typen verknüpft sind. In der Standardkonfiguration ist ein einziges Label enthalten, Sie können jedoch weitere Labels hinzufügen oder den Labelschlüssel ändern.

Wenn Sie die Messwerttypen ändern, sollten Sie die neuen benutzerdefinierten Messwerttypen in der Monitoring API definieren. Weitere Informationen finden Sie im folgenden Abschnitt Messwerttyp entwerfen.

Beispiel

Angenommen, Sie verwenden StatsD, um eine Anwendung zu überwachen, die aus den zwei Diensten my_service_a und my_service_b besteht. Für jeden Dienst, den Sie in Monitoring exportieren möchten, müssen Sie einen Zählermesswert erstellen, der die Anzahl der fehlgeschlagenen Anfragen darstellt. Sie möchten nicht die standardmäßigen StatsD-Messwerttypen verwenden.

Eingehende collectd-Messwerte

Bevor Sie eigene Messwerttypen definieren, sollten Sie die Struktur eines collectd-Messwerts und die Standardzuordnung eines StatsD-Messwerts zu benutzerdefinierten Messwerten verstehen.

Collectd-Messwerte, einschließlich StatsD-Messwerte, umfassen folgende Komponenten:

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

In diesem Beispiel haben die StatsD-Messwerte, die Sie exportieren möchten, in collectd die folgenden Kennzeichnungen:

Komponente	Erwartete Werte
Host	Beliebig
Plug-in	statsd
Plug-in-Instanz	Nicht festgelegt^1
Typ	derive^2
Typinstanz	[SERVICE_NAME].GET.[CODE]^3
[VALUE]	Beliebiger Wert^4

Hinweise:
¹ Das StatsD-Plug-in lässt diese Komponente derzeit leer.
² Ein StatsD-Zählermesswert wird dem collectd-Typ derive zugeordnet. ³ Eine Typinstanz könnte beispielsweise my_service_a.GET.500 sein. ⁴ [VALUE] ist in der Regel ein Zeitstempel und eine Zahl mit doppelter Genauigkeit.

Die folgende Tabelle zeigt, wie dieser Messwert standardmäßig zugeordnet wird:

StatsD-Typ	StatsD-Name	Stackdriver-Messwerttyp	Messwertart	Werttyp	Messwertlabels
Zähler	my_service_a.GET.500	custom.googleapis.com/statsd/derive	CUMULATIVE	INT64	metric:my_servce_a.GET.500
Zähler	my_service_b.GET.403	custom.googleapis.com/statsd/derive	CUMULATIVE	INT64	metric:my_servce_b.GET.403

Die Standardzuordnung könnte Ihnen verschiedene Schwierigkeiten bereiten:

• Dieser spezielle Zählermesswert ([SERVICE_NAME].GET.[CODE]) hat denselben nutzerdefinierten Messwerttyp wie alle anderen Zählermesswerte. Sie können die Daten für diese Messgröße nicht einfach abrufen, da Stackdriver derzeit keine regulären Ausdrücke für die Suche nach Labels unterstützt.

• Sie können nicht einfach Daten für einzelne Dienste oder einzelne Antwortcodes in Ihren Daten abrufen. Beispielsweise ist die Gesamtzahl der Fehler (aller Art), die in my_service_a aufgetreten sind, nicht problemlos abrufbar.

• Die Standardkonfiguration exportiert alle StatsD-Messwerte zu Stackdriver, was kostspielig werden könnte, wenn Sie nur an bestimmten Messwerten interessiert sind.

Messwerttyp entwerfen

Eine ausführliche Beschreibung zum Erstellen von Messwerttypen finden Sie unter Benutzerdefinierten Messwerttyp erstellen.

Der folgende benutzerdefinierte Messwerttyp ist eine gute Wahl für die Daten in diesem Beispiel, da er nur den StatsD-Messwert enthält, an dem Sie interessiert sind, und die Auswahl der Labels dazu beiträgt, die Daten besser zu organisieren:

• Typ: custom.googleapis.com/http/request_errors
• Labels:
  • service_name (STRING): der Name des Dienstes
  • response_code (INT64): der HTTP-Antwortcode
• Art: CUMULATIVE
• Werttyp: INT64

Die folgende Tabelle zeigt die gewünschte Zuordnung von StatsD zu Stackdriver:

StatsD-Typ	StatsD-Name	Stackdriver-Messwerttyp	Messwertart	Werttyp	Messwertlabels
Zähler	my_service_a.GET.500	custom.googleapis.com/http/request_errors	CUMULATIVE	INT64	service_name:my_service_a, response_code:500
Zähler	my_service_b.GET.403	custom.googleapis.com/http/request_errors	CUMULATIVE	INT64	service_name:my_service_b, response_code:403

Nachdem Sie den Messwerttyp entworfen haben, erstellen Sie ihn mit metricDescriptors.create. Informationen dazu, wie Sie den Messwerttyp von Monitoring erstellen lassen, finden Sie unter Automatisches Erstellen von Messwertdeskriptoren.

Zuordnungskonfiguration

Wenn Sie den StatsD-Messwert in den neuen benutzerdefinierten Messwerttyp exportieren möchten, ersetzen Sie den Inhalt der Standardkonfiguration des StatsD-Plug-ins, /etc/stackdriver/collectd.d/statsd.conf, durch den folgenden Code:

<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>

Hinweis :Wenn Sie diese Konfigurationsdatei installieren, wird die Standard-StatsD-Zuordnung entfernt. Wenn Sie die Standardzuordnung für andere StatsD-Messwerte beibehalten möchten, müssen Sie die Rule aus der Standard-StatsD-Konfiguration nach der neuen rewrite_request_errors-Regel hinzufügen.

Agent neu starten

Starten Sie Ihren Agent neu, um die neue Konfiguration zu übernehmen. Führen Sie dazu folgenden Befehl auf Ihrer VM-Instanz aus:

sudo service stackdriver-agent restart

Die Informationen zu benutzerdefinierten Messwerten werden sofort in Monitoring übertragen.

Nächste Schritte

Das Anpassen des StatsD-Plug-ins erfolgt ebenso wie die Anpassung von collectd-Messwerten für Monitoring. Weitere Informationen finden Sie in den Abschnitten „Referenz“ und „Fehlerbehebung“ des Artikels Benutzerdefinierte Messwerte des Agenten.