Zuordnung von OTLP-Logdatensätzen zu Logeinträgen

Vorschau

Dieses Produkt oder Feature unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und -Features sind "im Ist-Zustand" verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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.

Allgemeine Struktur von OTLP-formatierten Logdaten

Wenn Logdaten über die 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 jede 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-Spezifikation für logs.proto.

So werden LogEntry-Felder festgelegt

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

LogEntry-Feld (Namen aus HTTP-Referenz)	So wird der Feldwert vom System ermittelt
logName	Das System verwendet die folgende priorisierte Liste von OpenTelemetry-Logdatensatzattributen, um den Log-Namen zu bestimmen: gcp.log_name log_name event_name Lognamen müssen URL-sicher sein oder werden bei 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 zur Zuordnung von Ressourcentypen.
timestamp	Das System verwendet die folgende priorisierte Liste von OpenTelemetry-Logeintragfeldern, um die timestamp zu bestimmen: time_unix_nano, wenn ungleich null. observed_time_unix_nano, wenn ungleich null. Die Zeit, zu der 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 Zeit festgelegt, zu der LogEntry aufgenommen 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 Logeintrag den entsprechenden LogEntry-Feldern zu. Weitere Informationen finden Sie unter HttpRequest-Feld. FIXME. Es gibt andere Felder, die diesem Feld zugeordnet werden.
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 des Felds 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 des Felds spanId des Logeintrags fest. Der Wert muss ein gültiger 16-stelliger Hexadezimalstring sein. Andernfalls wird der Eintrag abgelehnt.
traceSampled	Nicht festgelegt.
sourceLocation	Das System legt dieses Feld auf die Werte der Code-Attribute 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.
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

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

Ebene Attribute

In der folgenden Tabelle wird beschrieben, wie Google Cloud Observability flache Attribute, die für HTTP-Anfragen gelten, LogEntry-Feldern zuordnet. Der Wert des Attributs http.request.method: "GET", wird beispielsweise 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. Das folgende Beispiel zeigt 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",
    }
  }
}

In der Tabelle werden die verschachtelten Attribute mit geschweiften Klammern dargestellt. gcp.http_request {requestMethod} bedeutet beispielsweise, dass das Attribut gcp.http_request das Attribut requestMethod enthält. Der Wert des innersten Attributs wird dem Wert des Logeintragfelds 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",
     },
   }
   

   Nach dem Entfernen von Feldern, 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 die vorherigen Attribute durch LogEntry dargestellt werden:

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

   Die maximale Verschachtelungstiefe für Attribute beträgt fünf. Alle Inhalte, die tiefer verschachtelt sind, werden gekürzt.

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-Typen Value zu konvertieren:

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

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

Nutzlastfeld

Hinweis :Die maximale Größe eines LogEntry beträgt 256 KiB. Dieses Limit ist eine ungefähre Angabe 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. Der String wird dann in das Feld LogEntry.textPayload kopiert.

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

  • 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 Verschachtelungstiefe 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 Logging-Schweregrad anhand der OpenTelemetry-Schweregradnummer, sofern diese festgelegt ist. Andernfalls wird der Schweregradtext verwendet. Wenn keine der beiden festgelegt ist, wird der Schweregrad des Loggings auf DEFAULT gesetzt.

OpenTelemetry-Schweregradnummer Enum (value)	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 Feldern LogEntry 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 Einschrä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 , das aus einem OTLP-Logdatensatz erstellt wird	256 KiB	Cloud Logging kürzt oder verwirft bei Bedarf Daten aus einem OTLP-Logdatensatz. Limit.
Maximale Länge eines Attributschlüssels	512 B	Zu große Labelschlüssel werden gekürzt, wenn der OTLP-Logdatensatz in ein LogEntry konvertiert wird. Limit.
Maximale Länge eines Attributwerts	64 KiB	Zu große Labelwerte, 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 an Log-Aufnahme-Bytes 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 von 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 bei der Aufnahme URL-codiert. Informationen zum Festlegen von Log-Namen finden Sie unter So werden LogEntry-Felder festgelegt.