Ops-Agent und OpenTelemetry Protocol (OTLP) verwenden

In diesem Dokument wird beschrieben, wie Sie mit dem Ops-Agent und dem OpenTelemetry Protocol-Empfänger (OTLP) benutzerdefinierte Messwerte und Traces aus Anwendungen erfassen können, die mit OpenTelemetry instrumentiert und in Compute Engine ausgeführt werden.

Dieses Dokument ist so aufgebaut:

• Übersicht über die Anwendungsfälle für den OTLP-Empfänger.
• Voraussetzungen für die Verwendung des OTLP-Empfängers.
• Agent für die Verwendung des OTLP-Empfängers konfigurieren.
• Messwerte mit dem Empfänger erfassen. In diesem Abschnitt wird beschrieben, wie Sie Ihre OpenTelemetry-Messwerte in Cloud Monitoring abfragen.
• Traces mit dem Empfänger erfassen. In diesem Abschnitt wird beschrieben, wie Sie ein Dienstkonto zum Schreiben von Daten in Cloud Trace autorisieren.

Übersicht über die Verwendung des OTLP-Empfängers

Mit dem Ops-Agent-OTLP-Empfänger können Sie Folgendes tun:

• Ihre Anwendung mit einem der sprachspezifischen SDKs für OpenTelemetry instrumentieren. Informationen zu den unterstützten Sprachen finden Sie unter OpenTelemetry-Instrumentierung. Die Kombination aus OpenTelemetry SDKs und dem Ops-Agent übernimmt Folgendes für Sie:
  • OTLP-Messwerte aus Ihrer Anwendung erfassen und zur Analyse an Cloud Monitoring senden.
  • OTLP-Spans (Trace-Daten) aus Ihrer Anwendung erfassen und zur Analyse an Cloud Trace senden.
• Traces von Drittanbieteranwendungen erfassen, die integrierte OTLP-Unterstützung oder Plug-ins mit solcher Unterstützung haben, z. B. Anwendungen wie Nginx. Der OTLP-Empfänger im Ops-Agent kann diese Traces erfassen. Ein Beispiel finden Sie unter OpenTelemetry-nginx-Modul.
• Benutzerdefinierte OpenTelemetry-Instrumentierung verwenden.
• Automatische OpenTelemetry-Instrumentierung verwenden.

Sie können den Empfänger verwenden, um Messwerte, Traces oder beides zu erfassen. Nachdem der Ops-Agent Ihre Messwerte erfasst hat, können Sie die Features von Cloud Monitoring, einschließlich Diagrammen, Dashboards und Benachrichtigungsrichtlinien, verwenden, um Ihre Messwerte zu überwachen. Wenn Ihre Anwendung auch Trace-Daten sendet, können Sie diese Daten mit Cloud Trace analysieren.

Vorteile

Vor der Verfügbarkeit des OTLP-Plug-ins für den Ops-Agent wurden Ihre Anwendungen hauptsächlich so zur Erfassung benutzerdefinierter Messwerte und Traces befähigt:

• Mit Clientbibliotheken, die die Monitoring API oder die Trace API implementieren
• Mit älteren OpenCensus-Bibliotheken

Die Verwendung von OpenTelemetry mit dem OTLP-Empfänger hat mehrere Vorteile gegenüber diesen Methoden, darunter:

• OpenTelemetry ist der Ersatz für OpenCensus. Das OpenCensus-Projekt wird archiviert. Weitere Informationen finden Sie unter Was ist OpenTelemetry?.
• Die Aufnahme wird auf Agent-Ebene gesteuert, sodass Sie Ihre Anwendungen nicht noch einmal bereitstellen müssen, wenn sich die Agent-Konfiguration ändert.
• Ihre Anwendungen müssen keine Google Cloud-Anmeldedaten einrichten. Die gesamte Autorisierung erfolgt auf Agent-Ebene.
• Ihr Anwendungscode enthält keinen Google Cloud-spezifischen Monitoring- oder Tracing-Code. Sie müssen die Monitoring API oder die Trace API nicht direkt verwenden.
• Ihre Anwendung überträgt Daten an den Ops-Agent und wenn Ihre Anwendung abstürzt, gehen keine vom Ops-Agent erfassten Daten verloren.

Beschränkungen

Der vom Ops-Agent-Empfänger bereitgestellte OTLP-Listener unterstützt den gRPC-Transport. HTTP, das hauptsächlich für JavaScript-Clients verwendet wird, wird nicht unterstützt. Weitere Informationen zum OpenTelemetry-Protokoll finden Sie unter Protokolldetails.

Der OTLP-Empfänger erfasst keine Logs. Sie können Logs mithilfe des Ops-Agents und anderer Empfänger erfassen und Loginformationen in OTLP-Spans aufnehmen. Der OTLP-Empfänger unterstützt aber keine direkte Erfassung von Logs. Informationen zum Erfassen von Logs mit dem Ops-Agent finden Sie unter Logging-Konfigurationen.

Vorbereitung

Sie müssen die Ops-Agent-Version 2.37.0 oder höher installieren, um OTLP-Messwerte und -Traces mithilfe des OTLP-Empfängers und des Ops-Agents zu erfassen.

In diesem Dokument wird davon ausgegangen, dass Sie bereits eine OpenTelemetry-basierte Anwendung haben, die mit einem der OpenTelemetry SDKs geschrieben wurde. Die Verwendung von OpenTelemetry SDKs wird in diesem Dokument nicht behandelt. Informationen zu SDKs und zu den unterstützten Sprachen finden Sie unter OpenTelemetry-Instrumentierung.

Ops-Agent konfigurieren

So konfigurieren Sie den Ops-Agent für die Verwendung des OTLP-Empfängers:

1. Ändern Sie die Nutzerkonfigurationsdatei für den Ops-Agent so, dass er den OTLP-Empfänger enthält.
2. Starten Sie den Ops-Agent neu.

Die folgenden Abschnitte beschreiben die einzelnen Schritte.

Nutzerkonfigurationsdatei für Ops-Agent ändern

Fügen Sie der Nutzerkonfigurationsdatei für den Ops-Agent die Konfigurationselemente für den OTLP-Empfänger hinzu:

• Für Linux: /etc/google-cloud-ops-agent/config.yaml
• Für Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Allgemeine Informationen zum Konfigurieren des Agents finden Sie unter Konfigurationsmodell.

Der OTLP-Empfänger führt den Konfigurationsabschnitt combined für den Ops-Agent ein. Bei Verwendung des Empfängers müssen Sie Dienste für Messwerte und Traces konfigurieren, auch wenn Sie nicht beides verwenden.

In den folgenden Abschnitten werden die Konfigurationsschritte für den OTLP-Empfänger beschrieben.

Empfängerabschnitt combined hinzufügen

Sie platzieren den Empfänger für OTLP-Messwerte und -Traces im Abschnitt combined. Im Abschnitt combined sind keine Prozessoren oder Dienste zulässig. Sie dürfen keinen anderen Empfänger mit demselben Namen wie ein Empfänger im Abschnitt combined konfigurieren. Im folgenden Beispiel wird otlp als Name des Empfängers verwendet.

Die minimale combined-Konfiguration für OTLP sieht so aus:

combined:
  receivers:
    otlp:
      type: otlp

Der Empfänger otlp hat die folgenden Konfigurationsoptionen:

• type: erforderlich. Muss otlp lauten.
• grpc_endpoint: Optional. Der gRPC-Endpunkt, den der OTLP-Empfänger überwacht. Die Standardeinstellung ist 0.0.0.0:4317.

• metrics_mode: Optional. Die Standardeinstellung ist googlemanagedprometheus, was bedeutet, dass der Empfänger OTLP-Messwerte als Prometheus-formatierte Messwerte sendet. Dazu wird die Prometheus API verwendet, die auch von Managed Service for Prometheus verwendet wird.

  Wenn Sie die Messwerte stattdessen mit der Monitoring API als benutzerdefinierte Cloud Monitoring-Messwerte senden möchten, setzen Sie die Option metrics_mode auf den Wert googlecloudmonitoring.

  Diese Auswahl wirkt sich darauf aus, wie Ihre Messwerte aufgenommen und für die Abrechnung gemessen werden. Weitere Informationen zu Messwertformaten finden Sie unter Aufnahmeformate für OTLP-Messwerte.

OTLP-Pipelines zu den Diensten hinzufügen

Der OTLP-Empfänger kann Messwerte und Traces erfassen. Daher müssen Sie einen Dienst für Messwerte und für Traces definieren. Wenn Sie keine Messwerte oder Traces erfassen, können Sie leere Dienste erstellen. Wenn Sie bereits Dienste mit anderen Pipelines haben, können Sie ihnen die OTLP-Pipeline hinzufügen.

Im Folgenden werden die Dienste metrics und traces mit dem OTLP-Empfänger in den Pipelines dargestellt:

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

Wenn Sie weder den Dienst metrics noch den Dienst traces für die OTLP-Erfassung verwenden möchten, lassen Sie den OTLP-Empfänger in der Pipeline für den Dienst weg. Der Dienst muss vorhanden sein, auch wenn er keine Pipelines hat. Wenn Ihre Anwendung Daten eines bestimmten Typs sendet und es keine entsprechende Pipeline mit dem Empfänger gibt, verwirft der Ops-Agent die Daten.

Ops-Agent neu starten

Sie müssen den Ops-Agent neu starten, um Konfigurationsänderungen anzuwenden.

Linux

1. Führen Sie den folgenden Befehl auf der Instanz aus, um den Agent neu zu starten:

   sudo systemctl restart google-cloud-ops-agent
   

2. Führen Sie den folgenden Befehl aus, um zu überprüfen, ob der Agent neu gestartet wurde. Prüfen Sie dann, ob die Komponenten „Metrics-Agent“ und „Logging-Agent“ gestartet wurden:

   sudo systemctl status "google-cloud-ops-agent*"
   

Windows

1. Stellen Sie mithilfe von RDP oder einem ähnlichen Tool eine Verbindung zu Ihrer Instanz her und melden Sie sich bei Windows an.
2. Öffnen Sie ein PowerShell-Terminal mit Administratorberechtigungen. Klicken Sie dazu mit der rechten Maustaste auf das PowerShell-Symbol und wählen Sie Als Administrator ausführen aus.
3. Führen Sie den folgenden PowerShell-Befehl aus, um den Agent neu zu starten:

   Restart-Service google-cloud-ops-agent -Force
   

4. Führen Sie den folgenden Befehl aus, um zu überprüfen, ob der Agent neu gestartet wurde. Prüfen Sie dann, ob die Komponenten „Metrics-Agent“ und „Logging-Agent“ gestartet wurden:

   Get-Service google-cloud-ops-agent*
   

OTLP-Messwerte erfassen

Wenn Sie den OTLP-Empfänger zum Erfassen von Messwerten aus Ihren OpenTelemetry-Anwendungen verwenden, ist die primäre Konfigurationsmethode für den Empfänger die API, die Sie zur Aufnahme der Messwerte verwenden möchten.

Sie wählen diese Methode, indem Sie die Option metrics_mode in der Konfiguration des otlp-Empfängers ändern oder den Standardwert verwenden. Die Auswahl hat Einfluss darauf, wie Ihre OTLP-Messwerte in Cloud Monitoring aufgenommen werden und wie diese Daten für Abrechnungszwecke gemessen werden.

Hinweis: Die Anzahl und Kardinalität der von Ihrer Anwendung ausgegebenen Messwerte liegen unter Ihrer Kontrolle. Es gibt keine spezielle Auswahl von Messwerten. Wie viele Daten Sie aufnehmen, hängt von Ihrer Anwendung ab.

Die Auswahl von metrics_mode hat keinen Einfluss darauf, ob Sie Diagramme, Dashboards und Benachrichtigungsrichtlinien im Bereich „Überwachung“ erstellen können.

• Informationen zum Erstellen von Diagrammen und Dashboards finden Sie unter Dashboards und Diagramme.
• Weitere Informationen zu Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungen.

In den folgenden Abschnitten werden Unterschiede der Formaten beschrieben, die von den Messwertmodi verwendet werden. Außerdem wird erläutert, wie Sie die aufgenommenen Daten zur Verwendung in Monitoring abfragen.

Aufnahmeformate für OTLP-Messwerte

Der OTLP-Empfänger stellt die Option metrics_mode bereit, die die API angibt, die zum Aufnehmen Ihrer Messwertdaten verwendet wird. Standardmäßig verwendet der Empfänger die Prometheus API. Der Standardwert für die Option metrics_mode ist googlemanagedprometheus. Die Messwerte werden mit der gleichen API aufgenommen, die von Managed Service for Prometheus verwendet wird.

Sie können den Empfänger so konfigurieren, dass Ihre Messwertdaten stattdessen an die Cloud Monitoring API gesendet werden. Zum Senden von Daten an die Monitoring API legen Sie den Wert der Option metrics_mode auf googlecloudmonitoring fest, wie im folgenden Beispiel gezeigt:

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

Das von Ihnen verwendete Aufnahmeformat bestimmt, wie die OTLP-Messwerte in Cloud Monitoring zugeordnet werden. Sie können Diagramme, Dashboards und Benachrichtigungsrichtlinien in Monitoring für Messwerte beider Messwertformate erstellen, Sie verweisen jedoch in Abfragen anders auf Messwerte.

Das Aufnahmeformat bestimmt auch das Preismodell, das für die Datenaufnahme verwendet wird.

In den folgenden Abschnitten werden die Preise, die strukturellen Unterschiede zwischen einem von der Prometheus API aufgenommenen Messwert und demselben von der Monitoring API aufgenommenen Messwert sowie das Verweisen auf die Messwerte in Abfragen beschrieben.

Preise und Kontingente

Das von Ihnen verwendete Aufnahmeformat bestimmt, wie die OTLP-Messwerte abgerechnet werden:

• Prometheus API: Wenn Sie die Prometheus API verwenden, um die Messwerte Ihrer Anwendung aufzunehmen, werden die Daten auf Basis der probenbasierten Preise abgerechnet, als ob die Messwerte über Managed Service for Prometheus eingegangen wären:

  • Die aktuellen Preise finden Sie unter Preisübersicht für Cloud Monitoring.
  • Weitere Informationen zum Zählen der Proben und zum Schätzen von Kosten finden Sie unter Preisbeispiele basierend auf aufgenommenen Proben.

• Monitoring API: Wenn Sie die Monitoring API verwenden, um die Messwerte Ihrer Anwendung aufzunehmen, unterliegen die Daten den volumenbasierten Preisen, z. B. Daten aus anderen Integrationen in den Ops-Agent.

  • Die aktuellen Preise finden Sie unter Preisübersicht für Cloud Monitoring.
  • Weitere Informationen zum Aufnahmevolumen und zur Schätzung der Kosten finden Sie unter Preisbeispiele auf der Grundlage der aufgenommenen Byte.

Messwerte, die mit dem OTLP-Empfänger aufgenommen wurden, werden bei der Aufnahme in Cloud Monitoring als „benutzerdefinierte“ Messwerte betrachtet und unterliegen den Kontingenten und Limits für benutzerdefinierte Messwerte.

Messwertstruktur

Cloud Monitoring beschreibt das Format der Messwertdaten mithilfe eines Schemas, das als Messwertdeskriptor bezeichnet wird. Der Messwertdeskriptor enthält den Namen des Messwerts, den Datentyp der Messwerte, den Zusammenhang zwischen den einzelnen Werten und früheren Werten sowie die mit den Werten verknüpften Labels. Wenn Sie den OTLP-Empfänger für die Aufnahme von Messwerten mithilfe der Prometheus API konfigurieren, unterscheidet sich der erstellte Messwertdeskriptor von dem bei der Verwendung der Monitoring API erstellten Messwertdeskriptor.

Prometheus API: Wenn Sie die Prometheus API verwenden, um die Messwerte Ihrer Anwendung aufzunehmen, wird jeder Messwert mithilfe der standardmäßigen OpenTelemetry-zu-Prometheus-Transformation umgewandelt und einem überwachten Ressourcentyp von Cloud Monitoring zugeordnet.

• Die Transformation umfasst die folgenden Änderungen:
  • Dem Namen des OTLP-Messwerts wird der String prometheus.googleapis.com/ (Präfix) vorangestellt.
  • Alle nicht alphanumerischen Zeichen wie Punkte (.) im OTLP-Messwertnamen werden durch Unterstriche (_) ersetzt.
  • An den Namen des OTLP-Messwerts wird ein String (Postfix) angehängt, der die Messwertart angibt, z. B. /gauge oder /counter.
• Die folgenden Labels, die Werte aus der OTLP-Ressource enthalten, werden dem Messwert hinzugefügt:
  • instance_name: Der Wert des Ressourcenattributs host.name.
  • machine_type: Der Wert des Ressourcenattributs host.type.

• Die mit den Messwertmessungen erfasste überwachte Ressource ist der generische Typ prometheus_target. Die generierte Prometheus-Zeitreihe enthält die folgenden Labels aus der prometheus_target-Ressource, die mit Werten aus der OTLP-Ressource gefüllt sind:

  • location: Der Wert des Ressourcenattributs cloud.availability_zone.
  • namespace: Der Wert des Ressourcenattributs host.id.

  Der Ressourcentyp prometheus_target enthält auch diese Labels:

  • project_id: Die Kennung des Google Cloud-Projekts, z. B. my-project, in dem der Ops-Agent ausgeführt wird.
  • cluster: Der Wert ist immer __gce__, wenn Messwerte vom Ops-Agent erfasst werden.

Wenn in den eingehenden OTLP-Daten die Ressourcenattribute fehlen, die für Labelwerte verwendet werden, werden die Werte aus Informationen zur VM übernommen, die den Ops-Agent ausführt. Dieses Verhalten bedeutet, dass OTLP-Daten ohne diese Ressourcenattribute mit denselben Labels angezeigt werden wie die Daten, die vom Ops-Agent-Prometheus-Empfänger erfasst werden.

Monitoring API: Wenn Sie die Monitoring API verwenden, um die Messwerte Ihrer Anwendung aufzunehmen, wird jeder Messwert so verarbeitet:

• Dem Namen des OTLP-Messwerts wird der String workload.googleapis.com/ vorangestellt, es sei denn, der OTLP-Messwertname enthält bereits diesen String oder eine andere gültige Messwertdomain wie custom.googleapis.com. Wir empfehlen die Verwendung der Domain „workload“.
• Die mit den Messwertmessungen erfasste überwachte Ressource ist der Compute Engine-VM-Typ gce_instance.

Die folgenden Beispiele zeigen die Messwertdeskriptoren für ein Paar von OpenTelemetry-Messwerten. Die Messwerte werden von einer Anwendung erstellt, die die Go-OpenTelemetry-Messwertbibliothek verwendet. Auf dem Tab Prometheus API wird der Messwertdeskriptor angezeigt, der erstellt wird, wenn der OTLP-Empfänger den standardmäßigen Prometheus-Messwertmodus verwendet. Auf dem Tab Monitoring API wird der Messwertdeskriptor angezeigt, der erstellt wird, wenn der OTLP-Empfänger den Messwertmodus googlecloudmonitoring verwendet.

Nichts ändert sich in der Anwendung, die den Messwert erstellt. Die einzige Änderung betrifft den vom OTLP-Empfänger verwendeten Messwertmodus.

Die Anwendung erstellt den OTLP-Messgerätmesswert otlp.test.gauge, der 64-Bit-Gleitkommawerte aufzeichnet. Die folgenden Tabs zeigen den Messwertdeskriptor, den jede Aufnahme-API erstellt:

Prometheus API

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

Monitoring API

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

Die Anwendung erstellt einen OTLP-Zählermesswert otlp.test.cumulative, der zunehmende 64-Bit-Gleitkommawerte aufzeichnet. Die folgenden Tabs zeigen den Messwertdeskriptor, den jede Aufnahme-API erstellt:

Prometheus API

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

Monitoring API

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

In der folgenden Tabelle werden einige der Formatunterschiede beschrieben, die durch die für die Aufnahme von OTLP-Messwerten verwendeten APIs entstehen:

	Prometheus API	Monitoring API
Messwertdomain	prometheus.googleapis.com	workload.googleapis.com
OTLP-Messwertname	Bei der Aufnahme geändert	Wie angegeben verwendet
Überwachte Ressource	prometheus_target	gce_instance

Aufnahmeformate und Abfragen

Der im OTLP-Empfänger verwendete Messwertmodus wirkt sich darauf aus, wie Sie die resultierenden Messwerte in Cloud Monitoring abfragen, wenn Sie Diagramme, Dashboards und Benachrichtigungsrichtlinien erstellen.

Wenn Sie ein Diagramm, ein Dashboard oder eine Benachrichtigungsrichtlinie in Cloud Monitoring konfigurieren, enthält die Konfiguration eine Abfrage der Daten, für die das Diagramm, das Dashboard oder die Benachrichtigungsrichtlinie ausgeführt wird.

Cloud Monitoring unterstützt die folgenden Tools zum Abfragen von Messwertdaten:

• Eine auf dem Query Builder basierende Oberfläche, die in Tools wie Metrics Explorer, die Dashboard Builder-Oberfläche und die Benachrichtigungsrichtlinien-Konfigurationsoberfläche integriert ist.
• Monitoring Query Language (MQL): Eine textbasierte Abfragesprache speziell für Cloud Monitoring.
• Prometheus Query Language (PromQL): Die textbasierte Abfragesprache, die vom Open-Source-Prometheus verwendet wird.

Informationen zum Abfragen von OTLP-Messwerten mit diesen Tools finden Sie hier:

• Mit der Prometheus API aufgenommene OTLP-Messwerte abfragen
• Mit der Monitoring API aufgenommene OTLP-Messwerte abfragen

Mit der Prometheus API aufgenommene OTLP-Messwerte abfragen

In diesem Abschnitt wird gezeigt, wie Sie mit der Prometheus API aufgenommene OTLP-Messwerte abfragen. Dies ist der Standardmesswertmodus für den OTLP-Empfänger.

Die Abfragen basieren auf den OTLP-Messwerten, die unter Messwertstruktur beschrieben werden:

• otlp.test.gauge: Ein OTLP-Messgerätmesswert, der 64-Bit-Gleitkommawerte aufzeichnet.
• otlp.test.cumlative: Ein OTLP-Zählermesswert, der zunehmende 64-Bit-Gleitkommawerte aufzeichnet.

Diese Messwerte werden mit den folgenden Messwerttypen in Cloud Monitoring aufgenommen, die als Namen fungieren:

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

Mithilfe der Prometheus API aufgenommene Messwerte werden dem überwachten Ressourcetyp prometheus_target zugeordnet.

Die Tabs zeigen, wie grundlegende Abfragen beim Abfragen der Messwerte mithilfe der Google Cloud Console aussehen. In diesen Beispielen wird der Metrics Explorer verwendet. Die Prinzipien sind jedoch für Dashboards und Benachrichtigungsrichtlinien identisch.

Query Builder-Oberfläche

Wenn Sie Messwertdaten mit einer Query Builder-Oberfläche abfragen möchten, geben Sie den Messwerttyp und den Typ der überwachten Ressource an, indem Sie dies in für die Suche geeignete Felder eingeben. Es gibt weitaus weniger Ressourcentypen als Messwerttypen. Daher ist es in der Regel am effizientesten, nach dem Ressourcentyp zu suchen und dann das Menü der zugehörigen Messwerte zu verwenden, um den Messwerttyp zu finden.

Wenn Sie in das Suchfeld "prometheus" eingeben, enthalten die Ergebnisse die überwachte Ressource prometheus_target, die mit dem Anzeigenamen "Prometheus-Ziel" angegeben wird, sowie den Satz von Messwerten, die in die Ressource schreiben. Die Messwerte sind nach dem Namen kategorisiert. Die beiden Beispielmesswerte werden als Kategorie Otlp angezeigt. Sie können Prometheus/otlp_test_cumulative/counter oder Prometheus/otlp_test_gauge/gauge auswählen.

Weitere Informationen zur Verwendung des Query Builders finden Sie unter Abfragen mit Menüs erstellen.

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_gauge/gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_cumulative/counter:

MQL

Zum Abfragen von Messwertdaten mit MQL verwenden Sie eine fetch-Anweisung und geben den Messwerttyp sowie den Typ der überwachten Ressource mit :: dazwischen an. Einfache MQL-Abfragen für die Beispielmesswerte sehen so aus:

• fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
• fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

Weitere Informationen zum Erstellen von MQL-Abfragen finden Sie unter Beispiel-MQL-Abfragen.

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_gauge/gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_cumulative/counter:

PromQL

Wenn Sie PromQL zum Abfragen von Messwertdaten verwenden, die mit der Prometheus API aufgenommen wurden, müssen Sie nur die geänderte Form des ursprünglichen OTLP-Messwertnamens angeben. Sie müssen nicht den String mit Präfix prometheus.googleapis.com/ oder den Postfix-Typ angeben.

Wenn der Messwert nur einem überwachten Ressourcetyp zugeordnet werden kann, müssen Sie die Ressource nicht angeben. Wie unter Messwertstruktur beschrieben, werden OTLP-Messwerte, die mit der Prometheus API aufgenommen wurden, nur dem überwachten Ressourcetyp prometheus_target zugeordnet. Trivial PromQL-Abfragen für die Beispielmesswerte sehen so aus:

• otlp_test_gauge
• otlp_test_cumulative

Weitere Informationen zur Verwendung von PromQL in Cloud Monitoring zum Abfragen von Messwerten, die über die Prometheus API aufgenommen wurden, finden Sie unter Google Cloud Managed Service for Prometheus-Daten in Cloud Monitoring. Informationen zur PromQL-Sprache finden Sie unter Prometheus abfragen.

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_gauge/gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts prometheus.googleapis.com/otlp_test_cumulative/counter:

Mit der Monitoring API aufgenommene OTLP-Messwerte abfragen

In diesem Abschnitt wird gezeigt, wie Sie OTLP-Messwerte mithilfe der Monitoring API abfragen. Zum Auswählen der Cloud Monitoring API legen Sie für das Feld metrics_mode des OTLP-Empfängers den Wert googlecloudmonitoring fest.

Die Abfragen basieren auf den OTLP-Messwerten, die unter Messwertstruktur beschrieben werden:

• otlp.test.gauge: Ein OTLP-Messgerätmesswert, der 64-Bit-Gleitkommawerte aufzeichnet.
• otlp.test.cumlative: Ein OTLP-Zählermesswert, der zunehmende 64-Bit-Gleitkommawerte aufzeichnet.

Diese Messwerte werden mit den folgenden Messwerttypen in Cloud Monitoring aufgenommen, die als Namen fungieren:

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

Mit der Monitoring API aufgenommene Messwerte werden dem überwachten Ressourcetyp gce_instance zugeordnet.

Die Tabs zeigen, wie grundlegende Abfragen beim Abfragen der Messwerte mithilfe der Google Cloud Console aussehen. In diesen Beispielen wird der Metrics Explorer verwendet. Die Prinzipien sind jedoch für Dashboards und Benachrichtigungsrichtlinien identisch.

Query Builder-Oberfläche

Wenn Sie Messwertdaten mit einer Query Builder-Oberfläche abfragen möchten, geben Sie den Messwerttyp und den Typ der überwachten Ressource an, indem Sie dies in für die Suche geeignete Felder eingeben. Es gibt weitaus weniger Ressourcentypen als Messwerttypen. Daher ist es in der Regel am effizientesten, nach dem Ressourcentyp zu suchen und dann das Menü der zugehörigen Messwerte zu verwenden, um den Messwerttyp zu finden.

Wenn Sie "gce_instance" in das Suchfeld eingeben, werden in den Ergebnissen der Ressourcentyp mit seinem Anzeigenamen "VM-Instanz" sowie der Satz von Messwerten angezeigt, die in die Ressource schreiben. Die Messwerte sind nach Name kategorisiert. Die beiden Beispielmesswerte werden als Kategorie Otlp angezeigt. Sie können Workload/otlp_test_cumulative oder Workload/otlp_test_gauge auswählen.

Weitere Informationen zur Verwendung des Query Builders finden Sie unter Abfragen mit Menüs erstellen.

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.cumulative:

MQL

Zum Abfragen von Messwertdaten mit MQL verwenden Sie eine fetch-Anweisung und geben den Messwerttyp sowie den Typ der überwachten Ressource mit :: dazwischen an. Einfache MQL-Abfragen für die Beispielmesswerte sehen so aus:

• fetch workload.googleapis.com/otlp.test.gauge::gce_instance
• fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

Weitere Informationen zum Erstellen von MQL-Abfragen finden Sie unter Beispiel-MQL-Abfragen.

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.cumulative:

PromQL

Wenn Sie PromQL zum Abfragen von Messwertdaten verwenden, die mithilfe der Monitoring API aufgenommen wurden, müssen Sie den Messwertnamen den PromQL-Konventionen zuordnen. Die grundlegenden Zuordnungsregeln umfassen Folgendes:

• Ersetzen Sie den ersten / durch :.
• Ersetzen Sie alle anderen Sonderzeichen (einschließlich . und anderer /-Zeichen) durch _.

Weitere Informationen zu den Zuordnungsregeln finden Sie unter Cloud Monitoring-Messwerte PromQL zuordnen.

Die Monitoring-Messwerttypen für die Beispielmesswerte werden folgendermaßen PromQL zugeordnet:

• workload_googleapis_com:otlp_test_gauge
• workload_googleapis_com:otlp_test_cumulative

Wenn der Messwert nur einem überwachten Ressourcetyp zugeordnet werden kann, müssen Sie die Ressource nicht angeben. Die Beispielmesswerte werden dem überwachten Ressourcentyp gce_instance zugeordnet. Wie aber in Messwertstruktur beschrieben, ist gce_instance nur einer der möglichen Messwerttypen. Daher müssen die PromQL-Abfragen für diese Messwerte einen Filter für den Ressourcentyp gce_instance enthalten. Wenn Sie den Filter einschließen möchten, fügen Sie den folgenden String am Ende der zugeordneten Messwertnamen hinzu: {monitored_resource="gce_instance"}.

Weitere Informationen zur Verwendung von PromQL in Cloud Monitoring finden Sie unter PromQL in Cloud Monitoring. Informationen zur PromQL-Sprache finden Sie unter Prometheus abfragen.

Trivial PromQL-Abfragen für die Beispielmesswerte sehen so aus:

• workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
• workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.gauge:

Der folgende Screenshot zeigt das Ergebnis der Abfrage des Messwerts workload.googleapis.com/otlp.test.cumulative:

Messwertnutzung und -diagnose in Cloud Monitoring ansehen

Auf der Cloud Monitoring-Seite Messwertverwaltung können Sie den Betrag steuern, den Sie für abrechenbare Messwerte ausgeben, ohne die Beobachtbarkeit zu beeinträchtigen. Die Seite Messwertverwaltung enthält folgende Informationen:

• Aufnahmevolumen für byte- und probenbasierte Abrechnung für Messwertdomains und einzelne Messwerte
• Daten zu Labels und zur Kardinalität von Messwerten
• Anzahl der Lesevorgänge für jeden Messwert.
• Verwenden Messwerten in Benachrichtigungsrichtlinien und benutzerdefinierten Dashboards
• Rate von Messwert-Schreibfehlern

Mit der Messwertverwaltung können Sie auch unnötige Messwerte ausschließen, sodass keine Kosten für die Datenaufnahme anfallen.

So rufen Sie die Seite Messwertverwaltung auf:

1. Rufen Sie in der Google Cloud Console die Seite  Messwertverwaltung auf:

   Zur Messwertverwaltung

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

2. Wählen Sie in der Symbolleiste das Zeitfenster aus. Standardmäßig werden auf der Seite Messwertverwaltung Informationen zu den Messwerten angezeigt, die am Vortag erfasst wurden.

Weitere Informationen zur Seite Messwertverwaltung finden Sie unter Messwertnutzung ansehen und verwalten.

OTLP-Traces erfassen

Wenn Sie den Ops-Agent so konfiguriert haben, dass Traces erfasst werden, Sie aber beim Ausführen Ihrer Anwendung keine Traces in Cloud Trace erhalten, müssen Sie dem Compute Engine-Dienstkonto, das der Agent verwendet, möglicherweise eine zusätzliche Rolle zuweisen. Standardmäßig erhält das Dienstkonto die Rollen, die das Schreiben von Messwerten und Logs, aber nicht von Traces erlauben.

In den folgenden Abschnitten wird beschrieben, wie Sie dem Dienstkonto die erforderliche Cloud Trace-Autorisierung erteilen.

Rollen ermitteln, die dem Dienstkonto zugewiesen wurden

Führen Sie den folgenden gcloud projects get-iam-policy-Befehl aus, um die einem Dienstkonto zugewiesenen Rollen anzuzeigen:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Die Ausgabe sieht in etwa so aus:

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

Wenn die Ausgabe entweder roles/cloudtrace.agent oder roles/cloudtrace.admin enthält, hat das Dienstkonto ausreichende Berechtigungen zum Schreiben von Traces. Informationen zum Zuweisen einer dieser Rollen zum Dienstkonto finden Sie im folgenden Abschnitt.

Cloud Trace-Rolle dem Dienstkonto zuweisen

Für ein Dienstkonto ist normalerweise die Rolle „Cloud Trace Agent“, roles/cloudtrace.agent, geeignet. Führen Sie den folgenden gcloud projects add-iam-policy-binding-Befehl aus, um diese Rolle dem Dienstkonto zuzuweisen:

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

Sie können dann den Befehl gcloud projects get-iam-policy ausführen, um zu prüfen, ob die Änderung vorgenommen wurde:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Die Ausgabe enthält jetzt roles/cloudtrace.agent:

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

Weitere Informationen zum Verwalten von IAM-Rollen finden Sie unter Zugriff auf Projekt, Ordner und Organisationen verwalten.

Nachdem Sie das vom Ops-Agent verwendete Dienstkonto autorisiert haben, Daten in Cloud Trace zu schreiben, und Sie Ihre OpenTelemetry-Anwendung ausführen, werden die Traces in Cloud Trace angezeigt:

OTLP-Empfänger deaktivieren

Wenn Sie sowohl die OTLP-Messwerte als auch die Traces mithilfe des Ops-Agents erfassen und die Erfassung entweder von Messwerten oder von Traces deaktivieren möchten, aber nicht von beidem, gehen Sie so vor:

1. Deaktivieren Sie die Erfassung entweder von Messwerten oder von Traces, indem Sie eine der folgenden Änderungen an der Nutzerkonfigurationsdatei config.yaml vornehmen:

   • Entfernen Sie die Pipeline otlp aus dem Dienst metrics.
   • Entfernen Sie die Pipeline otlp aus dem Dienst traces.

2. Starten Sie den Ops-Agent neu.

So deaktivieren Sie die Erfassung von OTLP-Messwerten und -Traces durch den Ops-Agent:

1. Entfernen Sie die OTLP-Konfiguration aus der Nutzerkonfigurationsdatei:

   • Löschen Sie den gesamten Abschnitt combined, einschließlich des Empfängers otlp.
   • Entfernen Sie die Pipeline otlp aus dem Dienst metrics.
   • Löschen Sie den gesamten Dienst traces.

2. Starten Sie den Ops-Agent neu.

Nächste Schritte

Nachdem die Anwendungsmesswerte und -Traces aufgenommen wurden, können Sie Ihre Daten mit der Google Cloud Console überwachen und analysieren.

• Informationen zu Dashboards und zu den verschiedenen Diagrammtypen, die Sie erstellen können, finden Sie unter Dashboards und Diagramme.
• Informationen zu den Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungsrichtlinien verwenden.
• Informationen zum Analysieren von Trace-Daten finden Sie unter Traces suchen und untersuchen.