Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Messwerte vom Agent

In diesem Leitfaden wird erläutert, wie Sie den Monitoring-Agent so konfigurieren können, dass er App-Messwerte in Cloud Monitoring erkennt und exportiert.

Der Monitoring-Agent ist ein collectd-Daemon. Neben dem Export vieler vordefinierter System- und Drittanbietermesswerte in Cloud Monitoring kann der Agent Ihre eigenen Collected-Anwendungsmesswerte als benutzerdefinierte Messwerte in Monitoring exportieren. Ihre collectd-Plug-ins können auch in Monitoring exportiert werden

Alternativ können Sie auch StatsD verwenden, um Anwendungsmesswerte nach Monitoring zu exportieren. Cloud Monitoring stellt eine Standardkonfiguration zur Verfügung, in der StatsD-Messwerte den benutzerdefinierten Messwerten zugeordnet werden. Wenn Sie mit dieser Zuordnung zufrieden sind, können Sie die unten beschriebenen Anpassungsschritte überspringen. Weitere Informationen finden Sie im Abschnitt zum StatsD-Plug-in.

Weitere Informationen zu Messwerten finden Sie in den folgenden Dokumenten:

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

Hinweis

Installieren Sie den neuesten Monitoring-Agent auf einer VM-Instanz und überprüfen Sie dann, ob er funktioniert. Informationen zum Aktualisieren des Agents finden Sie unter Agent aktualisieren.
Konfigurieren Sie collectd, um Monitoringdaten aus Ihrer Anwendung abzurufen. Collectd unterstützt viele Anwendungs-Frameworks und standardmäßige Monitoringendpunkte über seine Lese-Plug-ins. Suchen Sie nach einem Lese-Plug-in, das sich für Ihre Zwecke eignet.
(Optional) Fügen Sie die collectd-Referenzdokumentation der Einfachheit halber den man-Seiten Ihres Systems hinzu. Aktualisieren Sie dazu die Variable MANPATH und führen Sie dann mandb aus:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
Die man-Seiten sind für stackdriver-collectd.

Wichtige Dateien und Verzeichnisse

Folgende Dateien und Verzeichnisse, die bei der Installation des Agents erstellt werden, sind für die Verwendung des Monitoring-Agents (collectd) relevant:

/etc/stackdriver/collectd.conf: Die vom Agent verwendete collectd-Konfigurationsdatei. Bearbeiten Sie diese Datei, um die allgemeine Konfiguration zu ändern.

Hinweis: Die Standardkonfiguration des Systems für collectd, /etc/collectd.conf, wird vom Monitoring-Agent nicht verwendet.
/etc/stackdriver/collectd.d/: Das Verzeichnis für vom Nutzer hinzugefügte Konfigurationsdateien. Damit benutzerdefinierte Messwerte vom Agent gesendet werden, sollten Sie die erforderlichen Konfigurationsdateien, die unten beschrieben werden, in diesem Verzeichnis ablegen. Aus Gründen der Abwärtskompatibilität sucht der Agent auch in /opt/stackdriver/collectd/etc/collectd.d/ nach Dateien.
/opt/stackdriver/collectd/share/man/*: Die Dokumentation für die Agent-Version von collectd. Sie können diese Seiten in den man-Seiten Ihres Systems einfügen. Einzelheiten dazu finden Sie unter Vorbereitung.
/etc/init.d/stackdriver-agent: Das Initialisierungsskript für den Agent.

Wie Monitoring collectd-Messwerte verarbeitet

collectd-Messwerte werden vom Monitoring-Agent im Hintergrund verarbeitet und an Monitoring gesendet. Dort wird jeder Messwert einer der folgenden Kategorien zugeordnet und entsprechend behandelt:

Benutzerdefinierte Messwerte collectd-Messwerte mit dem Metadatenschlüssel stackdriver_metric_type und einer einzigen Datenquelle werden als benutzerdefinierte Messwerte behandelt und mithilfe der Methode projects.timeSeries.create in der Monitoring API an Monitoring gesendet.
Ausgewählte Messwerte: Alle anderen collectd-Messwerte werden mithilfe einer internen API an Monitoring gesendet. Akzeptiert und verarbeitet werden dabei allerdings nur solche Messwerte, die auf der Liste ausgewählter Messwerte stehen.
Verworfene Messwerte: collectd-Messwerte, die nicht auf der Liste der ausgewählten Messwerte stehen und keine benutzerdefinierten Messwerte sind, werden von Monitoring ohne Meldung verworfen. Der Agent selbst weiß nicht, welche Messwerte akzeptiert oder verworfen werden.

Benutzerdefinierte Messwerte mit dem Agenten schreiben

Sie konfigurieren den Agent so, dass er Messwertdatenpunkte an Monitoring sendet. Jeder Datenpunkt muss mit einem benutzerdefinierten Messwert verknüpft sein, den Sie mit einem Messwertdeskriptor definieren. Diese Konzepte werden unter Messwerte, Zeitachsen und Ressourcen vorgestellt und unter Struktur von Zeitachsen sowie unter Übersicht über benutzerdefinierte Messwerte ausführlich beschrieben.

Sie können festlegen, dass ein collectd-Messwert wie ein benutzerdefinierter Messwert behandelt wird. Fügen Sie ihm hierfür die richtigen Metadaten hinzu:

stackdriver_metric_type: (erforderlich) den Namen des exportierten Messwerts. Beispiel: custom.googleapis.com/my_custom_metric.
label:[LABEL]: (optional) zusätzliche Labels für den exportierten Messwert. Wenn Sie beispielsweise das STRING-Label color für Monitoring verwenden möchten, wäre Ihr Metadatenschlüssel label:color und der Wert des Schlüssels könnte "blue" sein. Sie können bis zu zehn Labels pro Messwerttyp haben.

Mithilfe einer collectd-Filterkette lassen sich die Metadaten für Ihre Messwerte ändern. Da Filterketten die Liste der Datenquellen nicht ändern können und benutzerdefinierte Messwerte nur eine einzige Datenquelle unterstützen, müssen alle collectd-Messwerte, die Sie mit dieser Einrichtung verwenden möchten, eine einzige Datenquelle haben.

Beispiel

In diesem Beispiel werden aktive Nginx-Verbindungen von zwei Nginx-Diensten überwacht, my_service_a und my_service_b. Sie werden mithilfe eines benutzerdefinierten Messwerts an Monitoring gesendet. Dazu sind folgende Schritte auszuführen:

Identifizieren Sie die collectd-Messwerte für jeden Nginx-Dienst.
Definieren Sie einen Monitoring-Messwertdeskriptor.
Konfigurieren Sie eine collectd-Filterkette, um den collectd-Messwerten Metadaten hinzuzufügen und damit die Anforderungen des Monitoring-Agents zu erfüllen.

Eingehende collectd-Messwerte

Collectd erwartet, dass Messwerte aus folgenden Komponenten bestehen. Die ersten fünf Komponenten bilden die collectd-Kennzeichnung für den Messwert:

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

In diesem Beispiel haben die Messwerte, die Sie als benutzerdefinierte Messwerte senden möchten, die folgenden Werte:

Komponente	Erwartete Werte
Host	Beliebig
Plug-in	`curl_json`
Plug-in-Instanz	`nginx_my_service_a` oder `nginx_my_service_b`¹
Typ	`gauge`
Typinstanz	`active-connections`
`[value]`	Beliebiger Wert²

Hinweis:
¹ Im Beispiel codiert dieser Wert sowohl die Anwendung (Nginx) als auch den verbundenen Dienstnamen.
² Der Wert ist in der Regel ein Zeitstempel und eine Zahl mit doppelter Genauigkeit. Die Interpretation der verschiedenen Arten von Werten erfolgt in Monitoring. Zusammengesetzte Werte werden vom Monitoring-Agent nicht unterstützt.

Messwertdeskriptor und Zeitachsen in Monitoring

Entwerfen Sie in Monitoring einen Messwertdeskriptor für Ihren benutzerdefinierten Messwert. Der folgende Deskriptor ist für die Daten in diesem Beispiel angemessen:

Name: custom.googleapis.com/nginx/active_connections
Labels:
- service_name (STRING): Der Name des Dienstes, der mit Nginx verbunden ist.
Art: GAUGE
Typ: DOUBLE

Sobald Sie den Messwertdeskriptor entworfen haben, können Sie ihn mithilfe von projects.metricDescriptors.create erstellen oder aus den Zeitachsenmetadaten erstellen lassen, wie unten erläutert. Weitere Informationen finden Sie auf dieser Seite unter Messwertdeskriptoren erstellen.

Die Zeitachsendaten für diesen Messwertdeskriptor müssen aufgrund der Art, wie der Messwertdeskriptor definiert ist, die folgenden Informationen enthalten:

Messwerttyp: custom.googleapis.com/nginx/active_connections
Messwertlabelwerte:
- service_name: entweder "my_service_a" oder "my_service_b"

Andere Zeitachseninformationen werden vom Agent für alle Messwerte automatisch ermittelt. Dies schließt die zugehörige überwachte Ressource, also die VM-Instanz, die die Daten sendet, sowie den Datenpunkt des Messwerts ein. Sie müssen nichts Besonderes tun.

Filterkette

Erstellen Sie eine Datei /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf mit folgendem Code:

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>

Neue Konfiguration laden

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 Ihren benutzerdefinierten Messwerten werden jetzt an Monitoring übertragen.

Referenz und Best Practices

Messwertdeskriptoren und Zeitachsen

Eine Einführung in die Cloud Monitoring-Messwerte erhalten Sie unter Messdaten, Zeitachsen und Ressourcen. Weitere Informationen finden Sie unter Übersicht über benutzerdefinierte Messwerte und Struktur von Zeitachsen.

Messwertdeskriptoren: Ein Messwertdeskriptor umfasst insbesondere Folgendes:

Einen Typ des Formulars custom.googleapis.com/[NAME1]/.../[NAME0]. Beispiel:
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
Die empfohlene Benennung ist hierarchisch, damit Nutzer die Messwerte leichter im Auge behalten können. Messwerttypen dürfen keine Bindestriche enthalten. Die genauen Benennungsregeln finden Sie unter Benennen von Messwerttypen und -labels.
Bis zu zehn Labels, um die Messwertdaten zu beschreiben, z. B. device_name, fault_type oder response_code. Die Werte der Labels werden nicht im Messwertdeskriptor angegeben.
Die Art und den Werttyp der Datenpunkte, z. B. GAUGE-Wert vom Typ DOUBLE. Weitere Informationen finden Sie unter MetricKind und ValueType.

Zeitreihendiagramm: Ein Messwertdatenpunkt umfasst insbesondere Folgendes:

Der Typ des zugehörigen Messwertdeskriptors.
Werte für alle Labels des Messwertdeskriptors.
Einen Zeitstempelwert, der dem Werttyp und der Art des Messwertdeskriptors entspricht.
Die überwachte Ressource, aus der die Daten stammen, normalerweise eine VM-Instanz. Platz für die Ressource ist standardmäßig vorhanden. Somit braucht der Deskriptor kein separates Label dafür.

Messwertdeskriptoren erstellen

Sie müssen keinen Messwertdeskriptor im Voraus erstellen. Wenn ein Datenpunkt in Monitoring eingeht, können der Messwerttyp, die Labels und der Wert des Punkts dazu verwendet werden, automatisch einen Messwertdeskriptor „Gauge“ (Messgerät) oder „Cumulative“ (Kumulativ) zu erstellen. Weitere Informationen finden Sie unter Messwertdeskriptoren automatisch erstellen.

Das Erstellen eines eigenen Messwertdeskriptors hat jedoch seine Vorteile:

Sie können eine gut durchdachte Dokumentation für den Messwert und seine Labels einbeziehen.
Sie können zusätzliche Arten und Typen von Messwerten angeben. Die einzigen Kombinationen (Art, Typ), die vom Agent unterstützt werden, sind (GAUGE, DOUBLE) und (CUMULATIVE, INT64). Weitere Informationen finden Sie unter Messwertarten und Werttypen.
Sie können auch andere Labeltypen als STRING angeben.

Wenn Sie in Monitoring einen Datenpunkt schreiben, der einen nicht definierten Messwerttyp verwendet, wird für den Datenpunkt ein neuer Messwertdeskriptor erstellt. Dies kann ein Problem darstellen, wenn Sie Fehler in dem Code beheben, durch den Messwertdaten geschrieben werden, da falsch geschriebene Messwerttypen zu falschen Messwertdeskriptoren führen.

Nachdem Sie einen Messwertdeskriptor erstellt haben oder er für Sie erstellt wurde, kann er nicht mehr geändert werden. Es lassen sich beispielsweise keine Labels einfügen oder entfernen. Sie können den Messwertdeskriptor lediglich löschen, wodurch auch alle seine Daten gelöscht werden, und ihn dann wie gewünscht neu erstellen.

Weitere Informationen zum Erstellen von Messwertdeskriptoren finden Sie unter Messwert definieren.

Preise

Im Allgemeinen sind Cloud Monitoring-Systemmesswerte kostenlos, Messwerte von externen Systemen, Agents oder Anwendungen hingegen nicht. Abrechenbare Messwerte werden entweder nach der Anzahl der aufgenommenen Byte oder der Anzahl der aufgenommenen Stichproben abgerechnet.

Weitere Informationen zu den Preisen für Cloud Monitoring finden Sie in den folgenden Dokumenten:

Limits

In Cloud Monitoring ist die Anzahl der Messwertzeitreihen und die der benutzerdefinierten Messwertdeskriptoren in jedem Projekt begrenzt. Einzelheiten finden Sie unter Kontingente und Limits.

Wenn Sie feststellen, dass Sie zuvor erstellte Messwertdeskriptoren nicht mehr benötigen, können Sie die Deskriptoren mit der Monitoring API suchen und löschen. Weitere Informationen finden Sie unter projects.metricDescriptors.

Fehlerbehebung

In diesem Abschnitt wird erläutert, wie Sie das Plug-in write_log des Monitoring-Agents konfigurieren, um den vollständigen Satz von Messwertpunkten auszugeben, einschließlich Metadaten. Dadurch können Sie bestimmen, welche Punkte transformiert werden müssen, und bestätigen, dass sich die Transformationen erwartungsgemäß verhalten.

write_log aktivieren

Das Plug-in write_log ist im Paket stackdriver-agent enthalten. So aktivieren Sie das Plug-in:

Bearbeiten Sie als Root die folgende Konfigurationsdatei:
```
/etc/stackdriver/collectd.conf
```
Fügen Sie direkt nach LoadPlugin write_gcm Folgendes hinzu:
```
LoadPlugin write_log
```
Fügen Sie direkt nach <Plugin "write_gcm">…</Plugin> Folgendes hinzu:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Suchen Sie nach <Target "write">…</Target> und fügen Sie nach jedem Plugin "write_gcm" Folgendes hinzu:
```
Plugin "write_log"
```
Speichern Sie die Änderungen und starten Sie den Agent neu:
```
sudo service stackdriver-agent restart
```

Durch diese Änderungen wird eine Logzeile pro gemeldetem Messwert ausgegeben, einschließlich der vollständigen collectd-Kennzeichnung, der Metadateneinträge und des Werts.

Ausgabe von write_log

Wenn Sie den vorherigen Schritt erfolgreich ausführen konnten, sollten Sie die Ausgabe von write_log in den Systemlogs sehen:

Debian-basiertes Linux: /var/log/syslog
Red Hat-basiertes Linux: /var/log/messages

Die folgenden Beispielzeilen wurden formatiert, damit sie in diesem Dokument leichter zu lesen sind.

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