v1.logs-Übersicht

In diesem Dokument wird beschrieben, wie Logdaten, die mit der Telemetry (OTLP) API an your Google Cloud project gesendet werden, einer Cloud Logging Struktur zugeordnet werden. Diese API implementiert das OpenTelemetry Line Protocol. Sie können Daten an diese API senden, wenn Sie Ihre Anwendungen mit einem otlphttp Exporter und einem OpenTelemetry Collector instrumentieren oder wenn Sie die OpenTelemetry SDKs verwenden.

OpenTelemetry ist ein Google Cloud-unterstütztes Open-Source-Projekt mit Google Cloud Entwicklern, die für den Support bei der Aufnahme und Visualisierung Ihrer Telemetriedaten zuständig sind.

Allgemeine Struktur von Logdaten im OTLP-Format

Wenn Logdaten mit der Telemetry API an Google Cloud gesendet werden, müssen diese Daten in einem Format vorliegen, das mit OTLP kompatibel ist. Die allgemeine Struktur dieser Daten sieht so aus:

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

OpenTelemetry batcht einzelne Logs, die jeweils durch eine logRecord-Struktur dargestellt werden, mit Informationen zur Quelle dieser Logs, die durch die resource-Struktur dargestellt wird.

Wenn Google Cloud Observability ein resourceLogs-Objekt empfängt, wird für jeden logRecord ein LogEntry erstellt. Im Gegensatz zu OTLP, das Quellinformationen mit einer Sammlung einzelner Logs batcht, enthält jede LogEntry-Struktur Informationen zur Quelle des Logs und zum Log selbst.

Weitere Informationen zur Struktur von Logdaten im OTLP-Format finden Sie unter siehe OpenTelemetry logs.proto.

Verarbeitung von Logdaten im OTLP-Format

Wenn Sie eine OTLP-resourceLogs-Struktur an die Telemetry API senden, führt Google Cloud Observability die folgenden Aktionen aus:

  1. Für jeden logRecord erstellt das System einen LogEntry.

    In den folgenden Dokumenten wird beschrieben, wie das System den LogEntry aus den OTLP-Logdaten füllt:

    Da jeder LogEntry Informationen zum entsprechenden Cloud Logging-Ressourcentyp enthält, ist jeder LogEntry möglicherweise größer als der entsprechende OTLP-logRecord.

    Die Konvertierung der OTLP-resourceLogs-Struktur in eine Reihe von LogEntry-Strukturen kann verlustbehaftet sein. Das heißt, Sie können möglicherweise nicht von der LogEntry-Struktur zu den ursprünglichen resource- und logRecord-Feldern konvertieren.

  2. Der LogEntry wird auf genau dieselbe Weise an aggregierte Senken in der Projekthierarchie und an Senken im Projekt weitergeleitet, als wäre der Logeintrag mit der Cloud Logging API an Ihr Projekt gesendet worden.

Best Practices

Wenn Sie Ihre Anwendungen so instrumentieren, dass Tracedaten an Ihr Google Cloud Projekt gesendet werden, empfehlen wir Ihnen, einen Exporter zu verwenden, der Daten im OTLP-Format in einen Collectorschreibt. Dieser sendet dann Ihre Tracedaten an die Telemetry API. Geben Sie in Ihrem Collector nur die Stamm-URL an:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry erkennt den Datentyp und fügt automatisch /v1/traces, /v1/metrics oder /v1/logs an. Weitere Informationen finden Sie unter OTLP/HTTP-Anfrage.

Beispiele für den Export von Trace- oder Messwertdaten an die Telemetry API finden Sie in den folgenden Dokumenten:

Wenn Sie keinen Collector verwenden können, können Sie eine OpenTelemetry-Bibliothek mit einem In-Process-OTLP-Exporter verwenden, um Telemetriedaten an die Telemetry API zu senden. Informationen zum direkten Exportieren von Tracedaten finden Sie unter Cloud Trace-Exporter zum OTLP-Endpunkt.

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

Ein Beispiel für die Authentifizierung bei der direkten Exportierung 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.

Cloud Logging und Datenstandort

Standardmäßig leitet Cloud Logging Logeinträge, die aus einem Projekt stammen, an vom System erstellte Log-Buckets weiter. Log-Buckets sind regionale Ressourcen. Sie können die Standardsenke für Logs aktualisieren, um Logeinträge an einen benutzerdefinierten Log-Bucket an einem Standort Ihrer Wahl zu senden. Weitere Informationen finden Sie unter Logs regionalisieren.

Cloud Logging bietet Einstellungen, die Sie für Organisationen und Ordner konfigurieren können. In diesen Einstellungen werden der Standort neuer vom System erstellter Log-Buckets, die Verwendung vom Kunden verwalteter Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) für diese Log-Buckets und die Konfiguration der Standardsenke für Logs festgelegt. Weitere Informationen finden Sie unter Unterstützung für Organisationen und Ordner.

Aufgenommene Daten ansehen

Sie können Ihre Logdaten auf den Seiten Log-Explorer und Observability Analytics ansehen. Weitere Informationen finden Sie unter:

Beschränkungen

In diesem Abschnitt werden Beschränkungen beschrieben. Außerdem wird beschrieben, wie Google Cloud Observability bestimmte Datentypen verarbeitet.

Limits

Beschreibung Wert Hinweise
Maximale Anzahl von Logs pro OTLP-Anfrage 8.192 Bezieht sich auf die maximale Anzahl von logRecords in einer OTLP resourceLogs Struktur. Limit.
Maximale Größe jeder Anfrage 5 MiB Limit.
Maximale Größe eines LogEntry
der aus einem OTLP-Logeintrag erstellt wurde		 256 KiB Cloud Logging kürzt oder verwirft bei Bedarf Daten aus einem OTLP-Logeintrag. Limit.
Maximale Länge eines Attributschlüssels 512 B Zu große Labelschlüssel werden gekürzt, wenn der OTLP-Logeintrag in einen LogEntry konvertiert wird. Limit.
Maximale Länge eines Attributwerts 64 KiB Zu große Labelwerte, wenn der OTLP-Logeintrag in einen LogEntry konvertiert wird. Limit.
Maximale Tiefe der Attributverschachtelung 5 Attribute, die dieses Limit überschreiten, werden gekürzt, wenn der OTLP-Logeintrag in ein LogEntry konvertiert wird.
Maximale Anzahl von Byte für die Logaufnahme pro Minute

2,4 GB für die folgenden Regionen: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1.

300 MB für alle anderen Regionen.

 Kontingent.

Verhalten

  • Wenn sowohl die OpenTelemetry-Schweregradnummer als auch der Schweregradtext festgelegt sind, verwendet das System die Schweregradnummer, um den Cloud Logging-Schweregrad zu bestimmen. Wenn der OTLP-Eintrag keine Schweregradinformationen enthält, wird der Cloud Logging-Schweregrad auf DEFAULT festgelegt.

  • Wenn ein OTLP-Eintrag doppelte Attributschlüssel enthält, behält das System den ersten Schlüssel bei und verwirft die Attribute mit doppelten Schlüsseln.

  • Das System konvertiert Attribute, die an einen Logeintrag angehängt sind, in einen String. Ein Beispiel finden Sie unter Feld „Labels“.

  • Log-Namen müssen URL-sicher sein oder werden bei der Aufnahme URL-codiert. Informationen zum Festlegen von Log-Namen finden Sie unter Festlegen von LogEntry Feldern.