OTLP-Unterstützung in Google Cloud Observability

Sie können Log-, Messwert- und Trace-Daten im OTLP-Format in Google Cloud Observability aufnehmen, indem Sie die Telemetry (OTLP) API verwenden, die das OpenTelemetry Protocol implementiert. Mit dieser API können Sie anbieterneutrale Telemetriedaten aus OpenTelemetry SDKs und Collectors erfassen, ohne benutzerdefinierte Google Cloud Exporters zu verwenden.

Wenn Sie Telemetrie mit der Telemetry API an Ihr Projekt senden, verarbeitet Google Cloud Observability jedes Signal so:

  • Logdaten:Konvertiert OTLP-Logdatensätze in Logeinträge und leitet sie zur Speicherung weiter.
  • Messwertdaten:Ordnet Messwertdaten Prometheus-Zeitreihen in Cloud Monitoring zu.
  • Trace-Daten:Speichert verteilte Traces in einem Format, das im Allgemeinen mit OTLP übereinstimmt.

Wenn Sie Arbeitslasten in Google Kubernetes Engine ausführen, können Sie Managed OpenTelemetry für GKE verwenden, anstatt einen OpenTelemetry Collector manuell bereitzustellen und zu verwalten.

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 das dynamische Aktualisieren 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 Collectors verwenden, authentifizieren Sie sich in der Regel mit der Erweiterung googleclientauth mit Google-Anmeldedaten.

Ein Beispiel für die Authentifizierung bei Verwendung des direkten Exports von Tracedaten 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:

  • Kontingentprojekt konfigurieren 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:

    • Rolle Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) für das Kontingentprojekt.
    • Die Rolle Cloud Telemetry Writer (roles/telemetry.writer) für das Projekt. Mit dieser Rolle kann Ihre Anwendung Log-, Messwert- und Tracedaten schreiben.

OTLP-Aufnahme

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

Datenaufnahme von Protokollen

Wenn Sie die Telemetry API zum Erfassen von OTLP-formatierten Logs verwenden, werden Ihre Logdaten in Cloud Logging-Logeinträge konvertiert. Eine eingehende OTLP-formatierte Log-Anfrage 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 dazu, welche Attribute für die Aufnahme von OTLP-formatierten Logs erforderlich sind, finden Sie unter OTLP-Attribute zur Zuordnung von Ressourcentypen.

Zur Unterstützung der Aufnahme von OTLP-formatierten Logs enthält die Cloud Logging-Struktur LogEntry 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 zu sehen ist:

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 werden, werden alle OTLP-Ressourcen-, ‑Bereichs- und ‑Entitätsmetadaten in jeden Logeintrag kopiert.

Aufnahme von Messwertdaten

OTLP für Prometheus-Messwerte funktioniert nur, wenn Sie den OpenTelemetry Collector in Version 0.140.0 oder höher verwenden.

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. Weitere 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 der Messwert target_info hinzugefügt, der alle Ressourcenattribute mit Ausnahme von service.name, service.instance.id und service.namespace enthält.

Da Messwertnamen und Labelschlüssel in Cloud Monitoring nicht vollständig 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 mit Attributen (Label-Schlüsseln), 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 _.. Alle Sonderzeichen sind in Labelwerten zulässig.

Damit Ihre Messwerte aus diesen Gründen nicht abgelehnt werden, verwenden Sie die Funktion replace_pattern, um Ihre Messwertnamen und Attribute zu transformieren.

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 kompatibel ist. Wir empfehlen jedoch die Verwendung der Telemetry API, da sie höhere Erfassungsquoten als die Cloud Trace API bietet.

Im Folgenden finden Sie ein Beispiel für Trace-Daten, die von einer Anwendung an Ihr Google Cloud -Projekt gesendet werden könnten:

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

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

  • Das Feld resource jedes Zeitraums enthält eine Kopie der resourceSpans.resource.attributes-Daten.
  • Das Feld instrumentation_scope jedes Zeitraums enthält eine Kopie der scopeSpans.scope-Daten.
  • 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 folgenden Dokumenten:

Abrechnung

Die Abrechnung von Log-, Messwert- und Tracedaten, die über die Telemetry API aufgenommen werden, hängt vom Telemetriesignal ab. Weitere Informationen

Abrechnung von Logdaten

Wenn Sie die Telemetry API zum Erfassen von Logs verwenden, kann sich das Logvolumen ändern. Das kann sich auf die Speicher- und Abrechnungswerte von Cloud Logging auswirken.

Die größten Änderungen an Speicher und Abrechnung für Ihr Google Cloud -Projekt treten ein, wenn Folgendes zutrifft:

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

Um das Speichervolumen zu minimieren, empfehlen wir Folgendes:

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

Abrechnung von Messwertdaten

Die Abrechnung für OTLP-Messwerte erfolgt unter der SKU „Aufgenommene Prometheus-Stichproben“, die auch für Messwerte aus 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 Gebühren für diese Daten berechnet werden.

Log-, Messwert- und Trace-Daten abfragen

Mit den Explorer-Seiten „Log-Explorer“, „Metrics Explorer“ und „Trace-Explorer“ können Sie Ihre Log-, Messwert- und Tracedaten abfragen. Sie können Ihre Log- und Tracedaten auch mit SQL auf der Seite „Observability Analytics“ 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 Sonderzeichen abfragen, die nicht dem Doppelpunkt (:) und dem Unterstrich (_) entsprechen, 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 beim Abfragen exponentieller Histogramme beibehalten, kann das zu unerwarteten Ergebnissen führen. Je typischer die histogram_quantile(.99, sum by (le) (metric))-Anfragen sind, desto wahrscheinlicher ist es, dass sie funktionieren.

  • Unter bestimmten Umständen, z. B. bei sehr spärlichen Deltas, werden Deltamesswerte möglicherweise nicht richtig abgefragt.

Limits und Kontingente

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

Außerdem gelten die folgenden Kontingente und Limits:

  • Log-Daten: 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 Samples pro Sekunde. Sie können eine Kontingenterhöhung anfordern.

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

Nächste Schritte