OTLP-Unterstützung in Google Cloud Observability

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

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

  • Logdaten: Konvertiert OTLP-Logeinträge 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 konsistent ist.

Wenn Sie Arbeitslasten in der Google Kubernetes Engine ausführen, können Sie Managed OpenTelemetry for 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 direkt aus Anwendungen mit SDKs exportieren, empfehlen wir die Verwendung des gRPC-OTLP-Exporters anstelle von HTTP-Exportern, da die meisten SDK-Exporter die dynamische Tokenaktualisierung nicht unterstützen.

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, verwenden Sie in der Regel die Erweiterung googleclientauth, um sich mit Google-Anmeldedaten zu authentifizieren.

Ein Beispiel für die Authentifizierung beim direkten Export von Trace-Daten finden Sie unter Authentifizierung konfigurieren. In diesem Beispiel wird gezeigt, wie Sie den Exporter mit Ihren Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) von Google Cloudkonfigurieren 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 die Anwendung verwendet, die folgenden IAM-Rollen (Identity and Access Management) zu:

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

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 zum Aufnehmen von OTLP-formatierten Logs verwenden, werden Ihre Logdaten in Logeinträge von Cloud Logging konvertiert. Eine eingehende OTLP-formatierte Loganfrage im JSON-Format 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 Zuordnung von OTLP-Attributen zu Ressourcentypen.

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

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 eigenständig sind und nicht mit externen Ressourcenschemas verknüpft sind, werden alle OTLP-Ressourcen-, Bereichs- und Entitätsmetadaten in jeden Logeintrag kopiert.

Aufnahme von Messwertdaten

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

Wenn Messwerte mit einem OpenTelemetry Collector und dem Exporter otlphttp in Cloud Monitoring aufgenommen oder direkt mit einem OpenTelemetry SDK gesendet werden, werden die OTLP-Messwerte den 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 bei der Konvertierung für jede eindeutige OpenTelemetry-Ressource 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 nicht das vollständige UTF-8-Format 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 im Satz _:./- enthalten.
  • Datenpunkte mit Attributen (d. h. Labelschlü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 im Satz _. enthalten. In Labelwerten sind alle Sonderzeichen 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 Aufnahmekontingente 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 Spans enthält eine Kopie der resourceSpans.resource.attributes-Daten.
  • Das Feld instrumentation_scope jedes Spans enthält eine Kopie der scopeSpans.scope-Daten.
  • Jeder Span entspricht einem Eintrag im Array scopeSpans.spans. Felder wie traceId, spanId und kind werden Feldern mit ähnlichen Namen im Trace-Schema zugeordnet.

Weitere Informationen finden Sie in folgenden Dokumenten:

Abrechnung

Die Abrechnung für Log-, Messwert- und Trace-Daten, die über die Telemetry API aufgenommen werden, hängt vom Telemetriesignal ab. Ausführliche Informationen finden Sie auf der Seite „Abrechnung“.

Abrechnung von Logdaten

Wenn Sie die Telemetry API zum Aufnehmen von Logs verwenden, kann sich die Änderung des Logvolumens auf die Speicher- und Abrechnungswerte in Cloud Logging auswirken.

Die größten Änderungen am Speicher und an der Abrechnung für Ihr Google Cloud -Projekt treten auf, wenn beide der 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 scopeLogs.scope-Felder werden für jeden einzelnen Logeintrag in das otel-Feld kopiert.

Da diese Ressourcen- und Bereichsmetadaten in jeden einzelnen Logeintrag kopiert werden, kann sich das gespeicherte Logvolumen erhöhen.

Wir empfehlen Folgendes, um das Speichervolumen zu minimieren:

  • Verwenden Sie einen OpenTelemetry Collector-Prozessor, z. B. einen transform-Prozessor, um unnötige Ressourcen- oder Bereichsattribute vor dem Exportieren der Daten zu verwerfen.
  • Wenn Sie die zusätzlichen Metadaten im Feld otel nicht benötigen, 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 Gebühren 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 die Seite „Observability Analytics“ auch 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 beim Abfragen exponentieller Histogramme beibehalten, werden möglicherweise unerwartete Ergebnisse zurückgegeben. Die typischeren histogram_quantile(.99, sum by (le) (metric))-Abfragen sollten funktionieren.

  • Delta-Messwerte können unter bestimmten Umständen, z. B. bei sehr dünnbesetzten Deltas, möglicherweise nicht richtig abgefragt werden.

Limits und Kontingente

Die API-Limits der Telemetrie 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