Zuordnung von OTLP-Logdatensätzen zu Logeinträgen

In diesem Dokument wird beschrieben, wie Google Cloud Observability die Felder eines LogEntry aus dem OTLP-Logeintrag bestimmt, wenn dieser Eintrag mithilfe der 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 Google Cloud Observability und die Exporter zum Erstellen von Logeinträgen verwenden, unterscheiden sich jedoch. Weitere Informationen finden Sie unter Google Cloud Observability für die Verwendung der Exporter-Zuordnungen konfigurieren.

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 für diese Daten sieht so aus:

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

Beachten Sie, dass OpenTelemetry 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 zusammenfasst.

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 Logdaten im OTLP-Format finden Sie in der logs.proto von OpenTelemetry.

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 der HTTP-Referenz)
So bestimmt das System den Feldwert
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-Logeintragsattributen, um den Lognamen 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 dem Ressourcentyp zuordnen.
timestamp

Das System verwendet die folgende priorisierte Liste von OpenTelemetry-Logeintragsfeldern, um den timestamp zu bestimmen:

  • time_unix_nano, wenn ungleich null.
  • observed_time_unix_nano, wenn ungleich null.
  • Der Zeitpunkt, zu dem der Logeintrag aufgenommen wurde.

Die Aufbewahrungsdauer 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 die LogEntry aufgenommen wird.
severity Das System ordnet den OpenTelemetry-Schweregrad im Logeintrag 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. 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 mithilfe der Attributwerte des Logeintrags fest. Weitere Informationen finden Sie unter Feld „Labels“.
trace Das System legt für dieses Feld den Wert aus dem Feld traceId des Logeintrags fest. Der Wert muss ein gültiger Hex-String mit 32 Zeichen sein, sonst wird der Eintrag abgelehnt.
spanId Das System legt für dieses Feld den Wert aus dem Feld spanId des Logeintrags fest. Der Wert muss ein gültiger Hexadezimalstring mit 16 Zeichen sein, sonst wird der Eintrag abgelehnt.
traceSampled Das System legt dieses Feld basierend auf dem niedrigstwertigen Bit aus dem Feld flags des Logeintrags fest. Wenn das geringste Bit gleich 1 ist, wird dieses Feld auf true gesetzt. Andernfalls bleibt es ungesetzt.
sourceLocation Das System legt für dieses Feld 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 die 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 Logeintrag den entsprechenden LogEntry-Feldern zu. Weitere Informationen finden Sie unter Feld „Operation“.

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
LogEntry-Feld
gespeichert ist (Namen aus der 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",
    }
  }
}

Das Format des Felds gcp.http_request kann entweder strukturierte verschachtelte Attribute oder ein JSON-String mit strukturierten Attributen sein.

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

In der Tabelle werden die verschachtelten Attribute in geschweiften Klammern angezeigt. 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
LogEntry-Feld
gespeichert ist (Namen aus der 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“

Das System führt die folgenden Aktionen aus, um zu bestimmen, welche Labels an den Logeintrag angehängt werden sollen:

  1. Alle Attribute, die bestimmten LogEntry-Feldern zugeordnet wurden, werden aus dem OTLP-Logeintrag entfernt.

    Angenommen, einem Logeintrag 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, konvertiert das System den Wert in einen String.

    Im Folgenden wird beispielsweise veranschaulicht, 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 Verschachtelungstiefe für Attribute beträgt fünf. Inhalte mit tieferer Verschachtelung werden abgeschnitten.

Feld „Operation“

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-Paare enthalten. Vereinfachte Attributnamen werden nicht unterstützt. Das folgende Beispiel zeigt einen Logeintrag, dessen gcp.operation-Attribut 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 Google Cloud Observability die gcp.operation dem LogEntry zuordnet:

OpenTelemetry
LogRecord.attribute.operation
Schlüssel/Wert-Paar.
Wert, der im folgenden
LogEntry-Vorgangsfeld 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 die 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-Value-Typen zu konvertieren:

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

Übergeben Sie Ganzzahlen als Strings, um Fehler bei der doppelten Genauigkeit zu vermeiden.

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 wandelt diese Paare in JSON um und füllt dann das Feld LogEntry.jsonPayload mit den folgenden Einschränkungen:

    • Wenn ein OTLP-Eintrag 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-Schweregraden zuordnet. OpenTelemetry definiert eine Schweregradnummer und einen Schweregradtext. In der logs.proto werden die Schweregrade definiert.

Google Cloud Observability bestimmt den Logging-Schweregrad anhand der OpenTelemetry-Schweregradnummer, sofern festgelegt. Andernfalls wird der Schweregradtext verwendet. Wenn keines von beiden festgelegt ist, wird der Logging-Schweregrad auf DEFAULT gesetzt.

OpenTelemetry-Schweregradnummer
Enum (Wert)
OpenTelemetry-Schweregradtext
(bei Tests wird die Groß-/Kleinschreibung nicht berücksichtigt)
Cloud Logging-Schweregrad
Enum (Wert)
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“

Google Cloud Observability ordnet den folgenden OTLP-Code direkt LogEntry-Feldern zu. Diese Zuordnung ist möglich, weil diese OpenTelemetry-Attribute semantisch mit Cloud Logging-Konzepten identisch sind.

OpenTelemetry
LogRecord.attribute
Schlüssel/Wert-Paar.
Wert, der im folgenden
LogEntry-Feld
gespeichert ist (Namen aus der 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
, der aus einem OTLP-Logeintrag 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 große Labelschlüssel werden abgeschnitten, 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 ein LogEntry konvertiert wird. Limit.
Maximale Tiefe der Attributverschachtelung 20 Anfragen mit Attributen, die dieses Limit überschreiten, werden abgelehnt, wenn der OTLP-Logeintrag in einen LogEntry konvertiert wird.
Maximale Anzahl von Logaufnahme-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, wird die Schweregradnummer verwendet, um den Cloud Logging-Schweregrad zu bestimmen. Wenn der OTLP-Eintrag keine Informationen zum Schweregrad enthält, wird der Cloud Logging-Schweregrad auf DEFAULT gesetzt.

  • 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 wandelt Attribute, die an einen Logeintrag 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 Lognamen finden Sie unter So werden LogEntry-Felder festgelegt.

Google Cloud Observability für die Verwendung der Exporter-Zuordnungen 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. Beispielsweise wird das Feld otel von Google Cloud Observability ausgefüllt, aber nicht von den Exportern.

Wenn Sie möchten, dass Google Cloud Observability dieselben Zuordnungsregeln wie Exporter verwendet, nehmen Sie die folgenden Änderungen an Ihren Anwendungen vor, die OTLP-Logeinträge an die Telemetry API senden:

  1. Fügen Sie das Attribut gcp.use_legacy_mapping der Ressource hinzu, die in der Anfrage enthalten ist. 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.

    Die Legacy-Zuordnungsregel führt dazu, dass Google Cloud Observability einige Inhalte verwirft. Die Größe der LogEntry-Objekte ist jedoch kleiner.

  2. Fügen Sie Ihrem OTLP-HTTP-Collector Prozessoren hinzu, die die folgenden Loglabels 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: Legen Sie resource.attributes["service.instance.id"] fest.

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