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
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
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 |
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. |
apphubapphubDestinationapphubSource |
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 |
| 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:
OpenTelemetryLogRecord.attributeSchlüssel/Wert-Paar. |
Wert, der im folgendenLogEntry-Feldgespeichert ist (Namen aus der HTTP-Referenz) |
Akzeptierter Typ |
|---|---|---|
http.request.method
|
httpRequest.requestMethod |
String |
url.fullhttp.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.originalhttp.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.versionprotocol
|
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:
OpenTelemetryLogRecord.attributeSchlüssel/Wert-Paar. |
Wert, der im folgendenLogEntry-Feldgespeichert 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 {http_request {
|
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:
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", }Wenn ein Attribut ein Array oder JSON-Elemente enthält, konvertiert das System den Wert in einen String.
Im Folgenden wird beispielsweise veranschaulicht, wie
LogEntrydie 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:
OpenTelemetryLogRecord.attribute.operationSchlüssel/Wert-Paar. |
Wert, der im folgendenLogEntry-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 FeldLogEntry.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 FeldLogEntry.textPayloadkopiert.KeyValueList: Das System wandelt diese Paare in JSON um und füllt dann das FeldLogEntry.jsonPayloadmit 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.
OpenTelemetryLogRecord.attributeSchlüssel/Wert-Paar. |
Wert, der im folgendenLogEntry-Feldgespeichert 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: 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
DEFAULTgesetzt.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:
Fügen Sie das Attribut
gcp.use_legacy_mappingder 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:
- Das Feld
otelist nicht ausgefüllt. Attribute, die mit
gcpbeginnen, werden mit den folgenden Ausnahmen verworfen:gcp.log.namegcp.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.- Das Feld
Fügen Sie Ihrem OTLP-HTTP-Collector Prozessoren hinzu, die die folgenden Loglabels festlegen:
instrumentation_scope: Legen Sieinstrumentation_scope.namefest.instrumentation_version: Legen Sieinstrumentation_scope.versionfest.service.name: Legen Sieresource.attributes["service.name"]fest.service.namespace: Legen Sieresource.attributes["service.namespace"]fest.service.instance.id: Legen Sieresource.attributes["service.instance.id"]fest.
Ein Beispiel finden Sie unter Zum OTLP-Exporter migrieren: Prozessoren.