OTLP-Aufnahme – Übersicht

In diesem Dokument wird die Verwendung der Telemetry API (OTLP) telemetry.googleapis.com vorgestellt, die das OpenTelemetry Protocol implementiert. Mit der Telemetry API können Sie Log-, Messwert- und Trace-Daten im OTLP-Format in Google Cloud Observability aufnehmen:

  • OTLP-Logdatensätze werden in Logeinträge konvertiert und dann weitergeleitet und gespeichert. Informationen zum Konvertierungsprozess, siehe den Abschnitt OTLP-Logs aufnehmen in diesem Dokument.
  • Messwertdaten werden in Cloud Monitoring aufgenommen. Informationen zu Messwert- und Labelnamen sowie zu den Einschränkungen bei der Aufnahme finden Sie im Abschnitt OTLP-Messwerte aufnehmen in diesem Dokument.
  • Trace-Daten werden in einem Format gespeichert, das im Allgemeinen mit OTLP übereinstimmt. Weitere Informationen finden Sie unter OTLP-Trace-Aufnahme.

Sie können Telemetriedaten aus Anwendungen, die SDKs verwenden, an die Telemetry API senden oder sie aus einem OpenTelemetry Collector exportieren.

Wenn Sie Google Kubernetes Engine verwenden, können Sie Managed OpenTelemetry for GKE verwenden, anstatt einen OpenTelemetry Collector, der die Telemetry API verwendet, manuell bereitzustellen und zu konfigurieren.

Protokollunterstützung

Der OTLP-Endpunkt unterstützt alle OTLP-Transport- und Serialisierungsprotokolle, einschließlich http/protobuf, http/json und grpc. Wenn Sie Daten direkt aus Anwendungen exportieren, die SDKs verwenden, empfehlen wir die Verwendung des gRPC-OTLP-Exporters anstelle von HTTP-Exportern, da die meisten SDK-Exporter keine Unterstützung für die dynamische Aktualisierung von Tokens bieten.

Authentifizierung

Sie müssen Ihre Exporter mit den Anmeldedaten konfigurieren, die zum Senden von Daten an Ihr Google Cloud Projekt erforderlich sind. Wenn Sie beispielsweise Collector verwenden, authentifizieren Sie sich in der Regel mit der Erweiterung googleclientauth mit Google-Anmeldedaten.

Ein Beispiel für die Authentifizierung bei der direkten Exportierung von Trace-Daten finden Sie unter Authentifizierung konfigurieren. In diesem Beispiel wird veranschaulicht, wie Sie den Exporter mit Ihren Google Cloud Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren und Ihrer Anwendung eine sprachspezifische Google Auth-Bibliothek hinzufügen.

Wenn Sie Telemetriedaten mit der Telemetry API an Ihr Google Cloud Projekt senden möchten, müssen Sie außerdem Folgendes tun:

  • Konfigurieren Sie ein Kontingentprojekt. Weitere Informationen finden Sie unter Kontingentprojekt festlegen.

  • Weisen Sie dem Nutzer oder dem Dienstkonto, das von der Anwendung verwendet wird, die folgenden IAM-Rollen (Identity and Access Management) zu:

OTLP-Aufnahme

In diesem Abschnitt wird beschrieben, wie Ihre Log-, Messwert- und Trace-Daten von OTLP in Google Cloud Observability-Datenstrukturen konvertiert werden.

Logdatenaufnahme

Wenn Sie die Telemetry API verwenden, um Logs im OTLP-Format aufzunehmen, werden Ihre Logdaten in Cloud Logging Logeinträge konvertiert. Eine eingehende OTLP-formatierte Loganfrage in JSON hat die folgende allgemeine Struktur:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

Jedes Element in jedem logRecords-Array wird zu einem einzelnen Cloud Logging-Logeintrag. Die resource Attribute bestimmen die überwachte Ressource im resultierenden LogEntry. Weitere Informationen zu den Attributen, die für die Aufnahme von Logs im OTLP-Format erforderlich sind , finden Sie unter Zuordnung von OTLP-Attributen zu Ressourcentypen.

Zur Unterstützung der Aufnahme von Logs im OTLP-Format enthält die Cloud Logging LogEntry-Struktur ein zusätzliches Feld, otel. Da sich die Datenmodelle von OTLP und Cloud Logging in der Struktur unterscheiden, wird im Feld otel eine Kopie der Ressourcen-, Bereichs- und Entitätsmetadaten aus der eingehenden OTLP-Anfrage gespeichert.

Wenn Sie beispielsweise eine OTLP-resourceLogs Nutzlast wie die folgende an die Telemetry API senden, enthält jeder resultierende Logeintrag ein resource Feld (für die überwachte Ressource) und ein otel Feld, wie auf den anderen Tabs gezeigt:

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Da Cloud Logging-Logeinträge in sich geschlossen sind und nicht mit externen Ressourcenschemas verknüpft sind, werden alle OTLP-Ressourcen-, Bereichs- und Entitätsmetadaten in jeden Logeintrag kopiert.

Messwertdatenaufnahme

OTLP für Prometheus-Messwerte funktioniert nur mit OpenTelemetry Collector Version 0.140.0 oder höher.

Wenn Messwerte mit einem OpenTelemetry Collector und dem otlphttp-Exporter in Cloud Monitoring aufgenommen oder direkt mit einem OpenTelemetry SDK gesendet werden, werden die OTLP-Messwerte Cloud Monitoring-Messwertstrukturen zugeordnet. Informationen zu diesen Zuordnungen finden Sie hier:

Google Cloud Observability konvertiert Messwerte in das Prometheus-Zeitreihenformat. Messwertnamen dürfen entweder keine Domain oder die Domain prometheus.googleapis.com haben. Nach der Konvertierung enthält der Messwertname das Präfix prometheus.googleapis.com und ein zusätzliches Suffix, das auf der OTLP-Punktart basiert. Der resultierende Cloud Monitoring-Messwert hat die folgende Struktur:

prometheus.googleapis.com/{metric_name}/{suffix}

Außerdem wird für jede eindeutige OpenTelemetry-Ressource durch die Konvertierung ein target_info Messwert hinzugefügt, der alle Ressourcenattribute außer service.name, service.instance.id, und service.namespace enthält.

Da Messwertnamen und Labelschlüssel in Cloud Monitoring kein vollständiges UTF-8 unterstützen, können Messwertdaten abgelehnt werden:

  • Messwertnamen, die nicht dem regulären Ausdruck [a-zA-Z][a-zA-Z0-9_:./-]* entsprechen, werden abgelehnt. Die einzigen Sonderzeichen, die in Messwertnamen zulässig sind, sind _:./-.
  • Datenpunkte, die Attribute (d. h. Labelschlüssel) enthalten, die nicht dem regulären Ausdruck [a-zA-Z_][a-zA-Z0-9_.]* entsprechen, werden abgelehnt. Die einzigen Sonderzeichen, die in Labelschlüsseln zulässig sind, sind _.. In Labelwerten sind alle Sonderzeichen zulässig.

Verwenden Sie die replace_pattern Funktion , um Ihre Messwertnamen und ‑attribute zu transformieren, damit Ihre Messwerte aus diesen Gründen nicht abgelehnt werden.

Trace-Datenaufnahme

Unabhängig davon, ob Sie die Telemetry API oder die Cloud Trace API verwenden, werden eingehende Trace-Daten in einem Format gespeichert, das mit OTLP übereinstimmt. Wir empfehlen jedoch die Verwendung der Telemetry API, da sie höhere Aufnahmekontingente als die Cloud Trace API bietet.

Hier ist ein Beispiel für Trace-Daten, die von einer Anwendung an Ihr Google Cloud Projekt gesendet werden können:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Jedes Element in jedem scopeSpans.spans-Array wird zu einem einzelnen gespeicherten Span:

  • Das Feld resource jedes Spans enthält eine Kopie der resourceSpans.resource.attributes Daten.
  • Das Feld instrumentation_scope jedes Spans enthält eine Kopie der Daten scopeSpans.scope.
  • Jeder Span entspricht einem Eintrag im Array scopeSpans.spans. Felder wie traceId, spanId und kind werden ähnlichen Feldern im Trace-Schema zugeordnet.

Weitere Informationen finden Sie in den folgenden Dokumenten:

Abrechnung

Die Abrechnung für Log-, Messwert- und Trace-Daten, die mit der Telemetry API aufgenommen werden, hängt vom Telemetriesignal ab. Vollständige Informationen finden Sie auf der Seite Abrechnung.

Abrechnung von Logdaten

Wenn Sie die Telemetry API verwenden, um Logs aufzunehmen, kann sich die Speichernutzung und die Abrechnung von Cloud Logging aufgrund einer Änderung des Logvolumens ändern.

Die größten Änderungen bei der Speichernutzung und Abrechnung für Ihr Google Cloud Projekt treten auf, wenn beide folgenden Bedingungen erfüllt sind:

  • Das Feld resource enthält Attribute mit hoher Kardinalität oder eine große Anzahl von Attributen. Diese Ressourcenattribute bestimmen die überwachte Ressource im resultierenden LogEntry.
  • Das Feld scopeLogs enthält eine große Anzahl von Elementen in den logRecords-Arrays. Die Felder scopeLogs.scope werden für jeden einzelnen Logeintrag in das Feld otel kopiert.

Da diese Ressourcen- und Bereichsmetadaten in jeden einzelnen Logeintrag kopiert werden, kann das gespeicherte Logvolumen zunehmen.

So minimieren Sie das Speichervolumen:

  • Verwenden Sie einen OpenTelemetry Collector-Prozessor wie einen transform-Prozessor, um unnötige Ressourcen- oder Bereichsattribute zu entfernen, bevor Sie die Daten exportieren.
  • Wenn die zusätzlichen Metadaten im Feld otel nicht erforderlich sind, verwenden Sie die Legacy-Zuordnungsoption gcp.use_legacy_mapping, die verhindert, dass das Feld otel ausgefüllt wird.

Abrechnung von Messwertdaten

Die Abrechnung für OTLP-Messwerte erfolgt unter der SKU „Prometheus Samples Ingested“, die auch für Messwerte von Google Cloud Managed Service for Prometheus verwendet wird.

Abrechnung von Trace-Daten

Die API, die Sie zum Senden von Trace-Daten an Ihr Projekt verwenden, hat keinen Einfluss darauf, wie die Kosten für diese Daten berechnet werden.

Log-, Messwert- und Trace-Daten abfragen

Sie können die Explorer-Seiten – Log-Explorer, Metrics Explorer und Trace-Explorer – verwenden, um Ihre Log-, Messwert- und Trace-Daten abzufragen. Sie können auch die Seite „Observability Analytics“ verwenden, um Ihre Log- und Trace-Daten mit SQL zu analysieren.

Die folgenden Tipps können hilfreich sein, wenn Sie Ihre Messwertdaten mit dem Metrics Explorer abfragen:

  • Wichtig: Wenn Sie Messwertnamen und Labelschlüssel mit anderen Sonderzeichen als dem Doppelpunkt (:) und dem Unterstrich (_) abfragen, müssen Sie sie gemäß der UTF-8-Spezifikation von PromQL in geschweifte Klammern ({}) und Anführungszeichen (") setzen. Die folgenden Abfragen sind beispielsweise gültig:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • Wenn Sie das Label le beibehalten, wenn Sie exponentielle Histogramme abfragen, kann dies zu unerwarteten Ergebnissen führen. Die typischeren histogram_quantile(.99, sum by (le) (metric)) Abfragen sollten funktionieren.

  • Delta-Messwerte werden unter bestimmten Umständen möglicherweise nicht richtig abgefragt, z. B. bei sehr spärlichen Deltas.

Limits und Kontingente

Die Limits der Telemetry API gelten für alle Signaltypen.

Darüber hinaus gelten die folgenden Kontingente und Limits:

  • Logdaten: Es gelten die Kontingente und Limits der Cloud Logging API.

  • Messwertdaten: Es gelten die Kontingente und Limits der Cloud Monitoring API. Messwerte dürfen beispielsweise nicht mehr als 200 Labels haben.

    Das Standardkontingent für Messwerte, die von der Telemetry API aufgenommen werden, beträgt 60.000 Anfragen pro Minute. Bei einer maximalen Batchgröße von 200 Punkten pro Anfrage entspricht dieses Kontingent einem effektiven Standardkontingent von 200.000 Stichproben pro Sekunde. Sie können eine Kontingenterhöhung anfordern.

  • Trace-Daten: Es gelten keine zusätzlichen Kontingente oder Limits.

Nächste Schritte