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. Der Agent kann viele vordefinierte System- und Drittanbietermesswerte nach Cloud Monitoring exportieren. Er kann auch Ihre eigenen gclid-Anwendungsmesswerte als benutzerdefinierte Messwerte nach Monitoring exportieren. Ihre collectd-Plug-ins können auch in Monitoring exportiert werden

Alternativ können Sie auch StatsD, um Anwendungsmesswerte nach Monitoring zu exportieren. Cloud Monitoring bietet eine Standardkonfiguration, die StatsD-Messwerte benutzerdefinierten Messwerten zuordnet. Wenn Sie mit dieser Zuordnung zufrieden sind, sind die unten beschriebenen Anpassungsschritte nicht erforderlich. Weitere Informationen finden Sie im Abschnitt zum StatsD-Plug-in.

Weitere Informationen zu Messwerten finden Sie in den folgenden Dokumenten:

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

Hinweise

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. Zum Senden benutzerdefinierter Messwerte vom Agent speichern Sie die erforderlichen Konfigurationsdateien, wie unten beschrieben, in diesem Verzeichnis. 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: Sammelmesswerte mit dem Metadatenschlüssel stackdriver_metric_type und einer einzelnen 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: Erfasste Messwerte, die nicht in der Liste der ausgewählten Messwerte enthalten sind 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 Agent schreiben

Sie konfigurieren den Agent so, dass er Messwertdatenpunkte an Monitoring sendet. Jeder Punkt muss einem benutzerdefinierten Messwert zugeordnet sein, den Sie mit einem Messwertdeskriptor definieren. Diese Konzepte werden unter Messwerte, Zeitachsen und Ressourcen vorgestellt und unter Struktur von Zeitachsen und Benutzerdefinierte Messwerte – Übersicht ausführlich beschrieben.

Sie können einen gclid-Messwert als benutzerdefinierten Messwert behandeln lassen. Dazu fügen Sie ihm 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 Collect-Messwerte, die Sie mit dieser Funktion verwenden möchten, nur eine einzige Datenquelle haben.

Beispiel

In diesem Beispiel werden aktive Nginx-Verbindungen von zwei Nginx-Diensten überwacht, my_service_a und my_service_b. Wir senden diese mithilfe eines benutzerdefinierten Messwerts an Monitoring. 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 benutzerdefinierten Messwert 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

Erstellen Sie für Monitoring einen Messwertdeskriptor für Ihren benutzerdefinierten Messwert. Der folgende Deskriptor ist eine vernünftige Wahl für die Daten in diesem Beispiel:

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

Nachdem Sie den Messwertdeskriptor entworfen haben, können Sie ihn mit projects.metricDescriptors.create erstellen oder ihn aus den Zeitachsenmetadaten erstellen lassen (siehe unten). 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

Ihre benutzerdefinierten Messwertinformationen werden nun 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 Details finden Sie unter Benutzerdefinierte Messwerte – Übersicht und Struktur von Zeitachsen.

Messwertdeskriptoren: Ein Messwertdeskriptor umfasst insbesondere Folgendes:

Ein Typ im Format 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 Messwerttypen und Labels benennen.
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. ein Gauge-Wert vom Typ „double“. Weitere Informationen finden Sie unter MetricKind und ValueType.

Zeitreihe: Ein Messwertdatenpunkt umfasst insbesondere Folgendes:

Der Typ des zugehörigen Messwertdeskriptors.
Werte für alle Labels des Messwertdeskriptors.
Ein 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 brauchen Messwertdeskriptoren nicht im Voraus zu erstellen. Wenn ein Datenpunkt in Monitoring eingeht, können der Messwerttyp, die Labels und der Wert des Punkts verwendet werden, um automatisch einen Gauge- oder kumulativen Messwertdeskriptor 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 beim Debuggen von Code zum Schreiben von Messwertdaten zu einem Problem werden, da falsche Schreibweisen des Messwerttyps 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 jedoch nicht. Abrechenbare Messwerte werden entweder nach der Anzahl der Byte oder der Anzahl der aufgenommenen Stichproben berechnet.

Weitere Informationen zu Cloud Monitoring-Preisen finden Sie in den folgenden Dokumenten:

Limits

In Cloud Monitoring gelten in jedem Projekt Limits für die Anzahl der Messwertzeitreihen und der benutzerdefinierten Messwertdeskriptoren. 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"}]