v1.logs-Übersicht

In diesem Dokument wird beschrieben, wie Logdaten, die mit der Telemetry (OTLP) API an Ihr Google Cloud Projekt gesendet werden, einer Cloud Logging Struktur zugeordnet werden. Diese API implementiert das OpenTelemetry OTLP-Protokoll. 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 OTLP-formatierten Logdaten

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 fasst einzelne Logs zusammen, 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, bei dem Quellinformationen mit einer Sammlung einzelner Logs zusammengefasst werden, enthält jede LogEntry-Struktur Informationen zur Quelle des Logs und zum Log selbst.

Weitere Informationen zur Struktur von OTLP-formatierten Logdaten, siehe die OpenTelemetry logs.proto.

Verarbeitung von OTLP-formatierten Logdaten

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

Für jeden logRecord wird ein LogEntry erstellt.

In den folgenden Dokumenten wird beschrieben, wie das System LogEntry aus den OTLP-Logdaten füllt:
- Zuordnung von OTLP-Logeinträgen zu Logeinträgen.
- Zuordnung von OTLP-Attributen zu Cloud Logging-Ressourcentypen.
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 von der OTLP-resourceLogs-Struktur in eine Reihe von LogEntry-Strukturen kann mit Datenverlusten verbunden sein. Das heißt, Sie können möglicherweise nicht von der LogEntry-Struktur zu den ursprünglichen resource- und logRecord-Feldern konvertieren.
Der LogEntry wird an aggregierte Senken in der Projekthierarchie und an Senken im Projekt weitergeleitet, genau so, 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 OTLP-formatierte Daten in einen Collectorschreibt, der dann Ihre Tracedaten an die Telemetry API sendet. 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 beim direkten Export von Tracedaten finden Sie unter Authentifizierung konfigurieren. In diesem Beispiel wird gezeigt, 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 in einem Projekt erstellt wurden, 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. Mit diesen Einstellungen wird der Standort neuer vom System erstellter Log-Buckets festgelegt, ob diese Log-Buckets vom Kunden verwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) verwenden und wie die Standardsenke für Logs konfiguriert wird. 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 die 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 schneidet Daten aus einem OTLP-Logeintrag ab oder verwirft sie wenn dies erforderlich ist. Limit.
Maximale Länge eines Attributschlüssels	512 B	Zu lange Labelschlüssel werden abgeschnitten, wenn der OTLP-Logeintrag in einen `LogEntry` konvertiert wird. Limit.
Maximale Länge eines Attributwerts	64 KiB	Zu lange Labelwerte, wenn der OTLP-Logeintrag in einen `LogEntry` konvertiert wird. Limit.
Maximale Tiefe der Attributverschachtelung	5	Attribute, die dieses Limit überschreiten, werden abgeschnitten, wenn der OTLP-Logeintrag in einen `LogEntry` konvertiert wird.
Maximale Anzahl von Logaufnahmedaten in Byte 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 im Feld Labels field.
Log-Namen müssen URL-sicher sein oder sie werden während der Aufnahme URL-codiert. Informationen zum Festlegen von Log-Namen finden Sie unter So werden LogEntry Felder festgelegt.