Zuordnung von OTLP-Logdatensätzen zu Logeinträgen

In diesem Dokument wird beschrieben, wie Google Cloud Observability die Felder eines LogEntry aus dem OTLP-Logdatensatz ermittelt, wenn dieser Datensatz über die Telemetry API an Google Cloud gesendet wird.

Die Google Cloud -Exporter für Cloud Logging konvertieren OTLP-formatierte Logdaten in LogEntry-Objekte. Anschließend werden diese Daten über die Cloud Logging API an Ihr Google Cloud -Projekt gesendet. Die Standardregeln, die von Google Cloud Observability und den Exportern zum Erstellen von Logeinträgen verwendet werden, sind jedoch unterschiedlich. Weitere Informationen finden Sie unter Google Cloud Observability für die Verwendung der Exporterzuordnungen konfigurieren.

Allgemeine Struktur von OTLP-formatierten Logdaten

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

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

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

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

Weitere Informationen zur Struktur von OTLP-formatierten Logdaten finden Sie in der OpenTelemetry-logs.proto.

So werden LogEntry-Felder festgelegt

Google Cloud Observability verwendet die folgenden Regeln, um die Werte für LogEntry-Felder zu bestimmen:

LogEntry-Feld (Namen aus HTTP-Referenz)	So wird der Feldwert vom System ermittelt
logName	Das System verwendet den Wert des Felds event_name im OTLP-LogRecord. Wenn dieses Feld nicht vorhanden oder nicht festgelegt ist, verwendet das System die folgende priorisierte Liste von OpenTelemetry-Logdatensatzattributen, um den Log-Namen zu bestimmen: log.name gcp.log.name log_name gcp.log_name logging.googleapis.com/logName service.name gcp.service.name service_name gcp.service_name event.name gcp.event.name event_name gcp.event_name Lognamen müssen URL-sicher sein oder werden während der Aufnahme URL-codiert.
resource	Das System verwendet die im Feld resource festgelegten Informationen oder leitet die Ressource ab. Weitere Informationen finden Sie unter OTLP-Attribute für die Zuordnung zum Ressourcentyp.
timestamp	Das System verwendet die folgende priorisierte Liste von OpenTelemetry-Logdatensatzfeldern, um die timestamp zu bestimmen: time_unix_nano, wenn der Wert ungleich null ist. observed_time_unix_nano, wenn der Wert ungleich null ist. Der Zeitpunkt, zu dem der Logeintrag aufgenommen wurde. Der Aufbewahrungszeitraum für den Log-Bucket, in dem die Daten gespeichert werden, bestimmt den ältesten Zeitstempel, der aufgenommen werden kann. Weitere Informationen finden Sie unter Cloud Logging-Kontingente.
receiveTimestamp	Wird auf die Uhrzeit festgelegt, zu der LogEntry erfasst wird.
severity	Das System ordnet den OpenTelemetry-Schweregrad im Logdatensatz einem Cloud Logging-Schweregrad zu. Weitere Informationen finden Sie unter Feld „Schweregrad“.
httpRequest	Das System ordnet die gcp.http_request-Attribute im Logdatensatz den entsprechenden LogEntry-Feldern zu. Das System akzeptiert diese Attribute entweder als strukturierte Attribute oder als JSON-String. Weitere Informationen finden Sie unter HttpRequest-Feld.
labels	Das System legt dieses Feld anhand der Werte der Logdatensatzattribute fest. Weitere Informationen finden Sie unter Feld „Labels“.
trace	Das System legt dieses Feld auf den Wert aus dem Feld traceId des Logeintrags fest. Der Wert muss ein gültiger 32‑stelliger Hexadezimalstring sein. Andernfalls wird der Eintrag abgelehnt.
spanId	Das System legt dieses Feld auf den Wert aus dem Feld spanId des Logeintrags fest. Der Wert muss ein gültiger 16-stelliger Hexadezimalstring sein. Andernfalls wird der Eintrag abgelehnt.
traceSampled	Das System legt dieses Feld basierend auf dem niedrigstwertigen Bit des Felds flags des Logeintrags fest. Wenn das Bit mit der geringsten Wertigkeit gleich 1 ist, wird dieses Feld auf true gesetzt. Andernfalls bleibt es nicht festgelegt.
sourceLocation	Das System legt dieses Feld auf die Werte aus den Code-Attributen des Logeintrags fest. Weitere Informationen finden Sie unter Feld „SourceLocation“.
split	Nicht festgelegt.
apphub apphubDestination apphubSource	Nicht festgelegt.
otel	Für Felder in OTLP-Logdaten, die kein entsprechendes Feld in einem LogEntry haben, konvertiert das System Datentypen und fügt die konvertierten Daten dann dem Feld otel hinzu. Weitere Informationen finden Sie unter Otel-Feld.
operation	Das System ordnet die gcp.operation-Attribute im Logdatensatz den entsprechenden LogEntry-Feldern zu. Weitere Informationen finden Sie unter Operation field.
Nutzlast	Das System legt die Nutzlast fest, indem es den Text eines Logeintrags in einen geeigneten Nutzlasttyp konvertiert. Weitere Informationen finden Sie unter Nutzlastfeld.

HttpRequest-Feld

Google Cloud Observability ordnet OTLP-Attribute, die für HTTP-Anfragen gelten, LogEntry-Feldern zu. In den folgenden Abschnitten wird beschrieben, wie das System flache und verschachtelte Attribute zuordnet.

Flache Attribute

In der folgenden Tabelle wird beschrieben, wie Google Cloud Observability flache Attribute, die für HTTP-Anfragen gelten, LogEntry-Feldern zuordnet. Beispiel: Der Wert des Attributs http.request.method: "GET", wird als Wert des Felds httpRequest.requestMethod in einem Logeintrag festgelegt:

OpenTelemetry LogRecord.attribute Schlüssel/Wert-Paar.	Wert, der im folgenden Feld LogEntry gespeichert ist (Namen aus HTTP-Referenz)	Akzeptierter Typ
http.request.method	httpRequest.requestMethod	String
url.full http.url	httpRequest.requestUrl	String
http.request.body.size	httpRequest.requestSize	String, Int
http.response.status_code	httpRequest.status	String, Int
http.response.body.size	httpRequest.responseSize	String, Int
user_agent.original http.user_agent	httpRequest.userAgent	String
client.address	remoteIp	String
server.address	serverIp	String
referrer	httpRequest.referer	String
latency	httpRequest.latency	String, Int
cacheLookup	httpRequest.cacheLookup	bool
cacheHit	httpRequest.cacheHit	bool
cacheValidatedWithOriginServer	httpRequest.cacheValidatedWithOriginServer	bool
cacheFillBytes	httpRequest.cacheFillBytes	String, Int
network.protocol.version protocol	httpRequest.protocol	String

Verschachtelte Attribute

In diesem Abschnitt wird beschrieben, wie Google Cloud Observability verschachtelte OTLP-Attribute, die für HTTP-Anfragen gelten, Feldern in einem LogEntry zuordnet. Im folgenden Beispiel sehen Sie einen Logeintrag mit zwei Attributen, die jeweils mindestens ein weiteres Attribut enthalten:

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

Das Format des Felds gcp.http_request kann entweder aus strukturierten, verschachtelten Attributen oder einem JSON-String mit strukturierten Attributen bestehen.

log_record {
  attributes: {
    gcp.http_request: "{\"requestMethod\": \"GET\", \"requestUrl\": \"some-URL\"}"
  }
}

In der Tabelle werden die verschachtelten Attribute mit geschweiften Klammern dargestellt. Beispiel: gcp.http_request {requestMethod} bedeutet, dass das Attribut gcp.http_request das Attribut requestMethod enthält. Der Wert des innersten Attributs wird dem Wert des Logeintragsfelds zugewiesen:

OpenTelemetry LogRecord.attribute Schlüssel/Wert-Paar.	Wert, der im folgenden Feld LogEntry gespeichert ist (Namen aus HTTP-Referenz)	Akzeptierter Typ
gcp.http_request {requestMethod} http_request {requestMethod}	httpRequest.requestMethod	String
gcp.http_request {requestUrl} http_request {requestUrl}	httpRequest.requestUrl	String
gcp.http_request {requestSize} http_request {requestSize}	httpRequest.requestSize	String, Int
gcp.http_request {status} http_request {status}	httpRequest.status	String, Int
gcp.http_request {responseSize} http_request {responseSize}	httpRequest.responseSize	String, Int
gcp.http_request {userAgent} http_request {userAgent}	httpRequest.userAgent	String
gcp.http_request {remoteIp} http_request {remoteIp}	httpRequest.remoteIp	String
gcp.http_request {serverIp} http_request {serverIp}	httpRequest.serverIp	String
gcp.http_request {referer} http_request {referrer}	httpRequest.referer	String
gcp.http_request {latency} http_request {latency}	httpRequest.latency	String, Int
gcp.http_request {cacheLookup} http_request {cacheLookup}	httpRequest.cacheLookup	bool
gcp.http_request {cacheHit} http_request {cacheHit}	httpRequest.cacheHit	bool
gcp.http_request { cacheValidatedWithOriginServer} http_request { cacheValidatedWithOriginServer}	httpRequest.cacheValidatedWithOriginServer	bool
gcp.http_request {cacheFillBytes} http_request {cacheFillBytes}	httpRequest.cacheFillBytes	String, Int
gcp.http_request {protocol} http_request {protocol}	httpRequest.protocol	String

Feld „Labels“

Um zu ermitteln, welche Labels dem Logeintrag zugewiesen werden sollen, führt das System die folgenden Aktionen aus:

1. Dadurch werden alle Attribute aus dem OTLP-Logdatensatz entfernt, die bestimmten LogEntry-Feldern zugeordnet wurden.

   Angenommen, einem Logdatensatz sind die folgenden Attribute zugeordnet:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
       "code.file.path": "my-file.cc",
       "code.function.name: "my-func",
       "code.line.number": 123,
       "gcp.http_request": {
           "requestMethod": "GET",
           "requestUrl": "my-URL",
     },
   }
   

   Nachdem Sie Felder entfernt haben, die bestimmten LogEntry-Feldern zugeordnet sind, bleiben die folgenden Felder übrig:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
   }
   

2. Wenn ein Attribut ein Array oder JSON-Elemente enthält, wird der Wert in einen String konvertiert.

   Das folgende Beispiel zeigt, wie LogEntry die vorherigen Attribute darstellt:

   labels: {
       "log_array_attr": "[\"value1\",\"value2\"]",
       "log_json_attr": "{\"json_key\":\"json_value\"}",
       "log-string-attr": "string",
   }
   

   Die maximale Schachtelungstiefe für Attribute beträgt fünf. Inhalte mit einer tieferen Verschachtelung werden gekürzt.

Vorgangsfeld

Google Cloud Observability ordnet OTLP-Attribute, die für den Vorgang gelten, dem Feld operation eines LogEntry zu. In den folgenden Abschnitten wird beschrieben, wie das System die verschachtelten Attribute zuordnet.

Das Attribut gcp.operation muss Schlüssel/Wert-Typen enthalten. Vereinfachte Attributnamen werden nicht unterstützt. Das folgende Beispiel zeigt einen Logdatensatz, dessen Attribut gcp.operation vier Schlüssel/Wert-Paare enthält:

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

In der folgenden Tabelle wird beschrieben, wie gcp.operation in Google Cloud Observability LogEntry zugeordnet wird:

OpenTelemetry LogRecord.attribute.operation Schlüssel/Wert-Paar.	Wert, der im folgenden Feld des Vorgangs LogEntry gespeichert ist	Akzeptierter Typ
id	id	String
producer	httpRequest.requestUrl	String
first	first	bool
last	last	bool

Otel-Feld

Für Felder in OTLP-Logdaten, die kein entsprechendes Feld in einem LogEntry haben, konvertiert das System Datentypen und fügt die konvertierten Daten dann dem Feld otel hinzu. Im Feld otel werden beispielsweise Attribute aus den Feldern resource, scope und entity gespeichert.

Das System verwendet die folgenden Regeln, um die OpenTelemetry-Datentypen in Protobuf-ValueTypen zu konvertieren:

OpenTelemetry-Typ	Protobuf-Typ
string	string
boolean	bool
integer	double
float	double
Array	ListValues
KeyValueList	Struct

Um Fehler aufgrund doppelter Genauigkeit zu vermeiden, sollten Sie Ganzzahlen als Strings übergeben.

Nutzlastfeld

Hinweis: Die maximale Größe eines LogEntry beträgt 256 KiB. Dieses Limit ist ein Näherungswert und basiert auf internen Datengrößen. Bei Bedarf kürzt das System das Nutzlastfeld.

Der Datentyp des OTLP-Felds logRecord.body bestimmt die Struktur der LogEntry-Nutzlast:

• string: Das System kopiert den String in das Feld LogEntry.textPayload.

• Array: Das System erstellt einen String aus den Array-Elementen und behält dabei Zeilenumbrüche bei. Anschließend wird der String in das Feld LogEntry.textPayload kopiert.

• KeyValueList: Das System konvertiert diese Paare in JSON und füllt dann das Feld LogEntry.jsonPayload aus. Dabei gelten die folgenden Einschränkungen:

  • Wenn ein OTLP-Datensatz doppelte Attributschlüssel enthält, behält das System den ersten Schlüssel bei und verwirft Attribute mit doppelten Schlüsseln.
  • Wenn die Schachtelungstiefe für ein JSON-Paar größer als fünf ist, wird der Inhalt auf eine Tiefe von fünf gekürzt.

Feld „Schweregrad“

In diesem Abschnitt wird beschrieben, wie Google Cloud Observability die OpenTelemetry-Schweregradfelder den Cloud Logging-Schweregradstufen zuordnet. OpenTelemetry definiert eine Schweregradnummer und einen Schweregradtext. Die logs.proto definiert die Schweregradnummern.

Google Cloud Observability bestimmt den Schweregrad für Logging anhand der OpenTelemetry-Schweregradnummer, sofern diese festgelegt ist. Andernfalls wird der Schweregradtext verwendet. Wenn keine der beiden Optionen festgelegt ist, wird der Schweregrad für das Logging auf DEFAULT gesetzt.

OpenTelemetry-Schweregradnummer Enum (Wert)	OpenTelemetry-Schweregradtext (bei Tests wird die Groß-/Kleinschreibung nicht berücksichtigt)	Cloud Logging-Schweregrad Enum (value)
SEVERITY_NUMBER_UNSPECIFIED (0)	„default“ nicht festgelegt	DEFAULT (0)
SEVERITY_NUMBER_TRACE (1) SEVERITY_NUMBER_TRACE2 (2) SEVERITY_NUMBER_TRACE3 (3) SEVERITY_NUMBER_TRACE4 (4)	„trace“ „trace2“ „trace3“ „trace4“	DEBUG (100)
SEVERITY_NUMBER_DEBUG (5) SEVERITY_NUMBER_DEBUG2 (6) SEVERITY_NUMBER_DEBUG3 (7) SEVERITY_NUMBER_DEBUG4 (8)	„debug“ „debug2“ „debug3“ „debug4“	DEBUG (100)
SEVERITY_NUMBER_INFO (9) SEVERITY_NUMBER_INFO2 (10)	„info“ “info2“	INFO (200)
SEVERITY_NUMBER_INFO3 (11) SEVERITY_NUMBER_INFO4 (12)	„notice“ „info3“ „info4“	NOTICE (300)
SEVERITY_NUMBER_WARN (13) SEVERITY_NUMBER_WARN2 (14) SEVERITY_NUMBER_WARN3 (15) SEVERITY_NUMBER_WARN4 (16)	„warning“ „warn“ „warn2“ „warn3“ „warn4“	WARNING (400)
SEVERITY_NUMBER_ERROR (17) SEVERITY_NUMBER_ERROR2 (18) SEVERITY_NUMBER_ERROR3 (19) SEVERITY_NUMBER_ERROR4 (20)	„error“ „error2“ „error3“ „error4“	ERROR (500)
SEVERITY_NUMBER_FATAL (21) SEVERITY_NUMBER_FATAL2 (22)	„critical“ „fatal“ „fatal2“	CRITICAL (600)
SEVERITY_NUMBER_FATAL3 (23)	„alert“ „fatal3“	ALERT (700)
SEVERITY_NUMBER_FATAL4 (24)	„emergency“ „fatal4“	EMERGENCY (800)

Feld „SourceLocation“

In Google Cloud Observability wird der folgende OTLP-Code direkt den LogEntry-Feldern zugeordnet. Diese Zuordnung ist möglich, da diese OpenTelemetry-Attribute semantisch mit Cloud Logging-Konzepten identisch sind.

OpenTelemetry LogRecord.attribute Schlüssel/Wert-Paar.	Wert, der im folgenden Feld LogEntry gespeichert ist (Namen aus HTTP-Referenz)	Akzeptierter Typ
code.file.path: Value	sourceLocation.file	String
code.function.name: Value	sourceLocation.function	String
code.function.number: Value	sourceLocation.line	String, Int

Beschränkungen

In diesem Abschnitt werden die Limits 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 , das aus einem OTLP-Logdatensatz erstellt wird	256 KiB	Cloud Logging kürzt oder verwirft Daten aus einem OTLP-Logeintrag, wenn dies erforderlich ist. Limit
Maximale Länge eines Attributschlüssels	512 B	Zu lange Label-Schlüssel werden abgeschnitten, wenn der OTLP-Logdatensatz in ein LogEntry konvertiert wird. Limit
Maximale Länge eines Attributwerts	64 KiB	Zu große Label-Werte, wenn der OTLP-Logdatensatz in ein LogEntry konvertiert wird. Limit
Maximale Tiefe der Attributverschachtelung	5	Attribute, die dieses Limit überschreiten, werden abgeschnitten, wenn der OTLP-Logdatensatz in ein LogEntry konvertiert wird.
Maximale Anzahl von Log-Aufnahmebytes 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-Datensatz keine Informationen zum Schweregrad enthält, wird der Schweregrad in Cloud Logging auf DEFAULT festgelegt.

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

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

• Lognamen müssen URL-sicher sein oder werden während der Aufnahme URL-codiert. Informationen zum Festlegen von Log-Namen finden Sie unter So werden LogEntry-Felder festgelegt.

Google Cloud Observability für die Verwendung der Exportzuordnungen konfigurieren

Google Cloud Observability und der Google Cloud -Exporter für Cloud Logging verwenden unterschiedliche Regeln, um LogEntry-Objekte aus OTLP-formatierten Logdaten zu erstellen. Beispiel: Google Cloud Observability füllt das Feld otel aus, die Exporter jedoch nicht.

Wenn Google Cloud Observability dieselben Zuordnungsregeln wie Exporter verwenden soll, nehmen Sie die folgenden Änderungen an Ihren Anwendungen vor, die OTLP-Logdatensätze an die Telemetry API senden:

1. Fügen Sie der im Antrag enthaltenen Ressource das Attribut gcp.use_legacy_mapping hinzu. Weitere Informationen finden Sie unter Attribute hinzufügen oder löschen.

   Wenn dieses Attribut festgelegt ist, geschieht Folgendes:

   1. Das Feld otel ist nicht ausgefüllt.

   2. Attribute, die mit gcp beginnen, werden mit den folgenden Ausnahmen verworfen:

      • gcp.log.name
      • gcp.insert_id

      Die beiden vorherigen Attribute werden LogEntry-Feldern zugeordnet.

   Durch die Legacy-Zuordnungsregel werden in Google Cloud Observability einige Inhalte verworfen. Die Größe der LogEntry-Objekte ist jedoch geringer.

2. Fügen Sie Ihrem OTLP-HTTP-Collector Prozessoren hinzu, die die folgenden Log-Labels festlegen:

   • instrumentation_scope: Legen Sie instrumentation_scope.name fest.
   • instrumentation_version: Legen Sie instrumentation_scope.version fest.
   • service.name: Legen Sie resource.attributes["service.name"] fest.
   • service.namespace: Legen Sie resource.attributes["service.namespace"] fest.
   • service.instance.id: Auf resource.attributes["service.instance.id"] festlegen.

   Ein Beispiel finden Sie unter Zum OTLP-Exporter migrieren: Prozessoren.