Questo documento descrive come Google Cloud Observability determina i campi di una LogEntry dal record di log OTLP, quando questo record viene inviato a Google Cloud utilizzando l'API Telemetry.
Gli esportatori Google Cloud per Cloud Logging convertono i dati di log in formato OTLP in oggetti LogEntry. Quindi inviano questi dati al tuo progetto Google Cloud utilizzando l'API Cloud Logging. Tuttavia, le regole predefinite utilizzate da Google Cloud Observability e dagli esportatori per creare le voci di log sono diverse. Per saperne di più, consulta Configura Google Cloud Observability per utilizzare le mappature dell'esportatore.
Struttura generale dei dati di log formattati in OTLP
Quando i dati di log vengono inviati a Google Cloud utilizzando l'API Telemetry, questi dati devono essere in un formato coerente con OTLP. La struttura generale di questi dati è la seguente:
"resourceLogs": [
{
"resource": {
"attributes": [...]
},
"scopeLogs": [
{
"logRecords": [...]
}
]
}
]
Tieni presente che OpenTelemetry raggruppa i singoli log, ognuno dei quali è rappresentato da una struttura logRecord, con informazioni sull'origine dei log, rappresentata dalla struttura resource.
Quando Google Cloud Observability riceve un oggetto resourceLogs, costruisce un LogEntry per ogni logRecord. A differenza di OTLP, che raggruppa le informazioni sull'origine con una raccolta di singoli log, ogni struttura LogEntry contiene informazioni sull'origine del log e sul log stesso.
Per scoprire di più sulla struttura dei dati di log formattati in OTLP, consulta la logs.proto di OpenTelemetry.
Come vengono impostati i campi LogEntry
Google Cloud Observability utilizza le seguenti regole per determinare i valori dei campi LogEntry:
Campo LogEntry(Nomi dal riferimento HTTP) |
In che modo il sistema determina il valore del campo |
|---|---|
logName |
Il sistema utilizza il valore del campo
I nomi dei log devono essere sicuri per l'URL o vengono codificati come URL durante l'importazione. |
resource |
Il sistema utilizza le informazioni impostate nel campo resource o deduce la risorsa. Per maggiori dettagli, consulta
Mappatura degli attributi OTLP al tipo di risorsa. |
timestamp |
Il sistema utilizza il seguente elenco con priorità dei campi dei record di log OpenTelemetry per determinare
Il periodo di conservazione del bucket di log in cui sono archiviati i dati determina il timestamp più vecchio che può essere importato. Per saperne di più, consulta Quote di Cloud Logging. |
receiveTimestamp |
Impostato sull'ora di importazione di LogEntry. |
severity |
Il sistema mappa la gravità OpenTelemetry nel record di log a una gravità di Cloud Logging. Per maggiori dettagli, consulta il campo Gravità. |
httpRequest |
Il sistema mappa gli attributi |
labels |
Il sistema imposta questo campo utilizzando i valori degli attributi del record di log. Per saperne di più, consulta Campo Etichette. |
trace |
Il sistema imposta questo campo sul valore del campo traceId del record di log. Il valore deve essere una stringa esadecimale valida di 32 caratteri, altrimenti la voce viene rifiutata. |
spanId |
Il sistema imposta questo campo sul valore del campo spanId del record di log. Il valore deve essere una stringa esadecimale valida di 16 caratteri, altrimenti la voce viene rifiutata. |
traceSampled |
Il sistema imposta questo campo in base al bit meno significativo del campo flags del record di log. Se il bit meno significativo è uguale a 1, questo campo viene impostato su true; in caso contrario, rimane non impostato. |
sourceLocation |
Il sistema imposta questo campo sui valori degli attributi Codice del record di log. Per saperne di più, consulta il campo SourceLocation. |
split |
Non impostata. |
apphubapphubDestinationapphubSource |
Non impostata. |
otel |
Per i campi nei dati di log OTLP che non hanno un campo equivalente in un
LogEntry, il sistema converte i tipi di dati e poi aggiunge
i dati convertiti al campo otel. Per saperne di più, consulta Campo Otel. |
operation |
Il sistema mappa gli attributi |
| Payload | Il sistema imposta il payload convertendo il corpo di un record di log in un tipo di payload appropriato. Per saperne di più, consulta Campo payload. |
Campo HttpRequest
Google Cloud Observability mappa gli attributi OTLP che si applicano alle richieste HTTP ai campi LogEntry. Le sezioni seguenti descrivono in che modo il sistema mappa gli attributi semplici e nidificati.
Attributi piatti
La tabella seguente descrive in che modo Google Cloud Observability mappa gli attributi flat che si applicano alle richieste HTTP ai campi LogEntry.
Ad esempio, il valore dell'attributo http.request.method: "GET", viene impostato come valore del campo httpRequest.requestMethod in una voce di log:
Coppia chiave-valoreLogRecord.attributeOpenTelemetry. |
Valore memorizzato nel seguente campoLogEntry(Nomi dal riferimento HTTP) |
Tipo accettato |
|---|---|---|
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 |
Attributi nidificati
Questa sezione descrive come Google Cloud Observability mappa gli attributi OTLP nidificati che si applicano alle richieste HTTP ai campi di un LogEntry. L'esempio seguente illustra un record di log che contiene due attributi, ognuno dei quali contiene almeno un altro attributo:
log_record {
attributes: {
gcp.http_request {
"requestMethod": "GET",
"requestUrl": "some-URL",
}
http_request {
"requestMethod": "GET",
}
}
}
Il formato del campo gcp.http_request può essere costituito da attributi nidificati strutturati o da una stringa JSON di attributi strutturati.
log_record {
attributes: {
gcp.http_request: "{\"requestMethod\": \"GET\", \"requestUrl\": \"some-URL\"}"
}
}
Nella tabella, gli attributi nidificati sono mostrati tra parentesi graffe. Ad esempio, gcp.http_request {requestMethod} significa che l'attributo gcp.http_request contiene l'attributo requestMethod. Il valore dell'attributo più interno viene assegnato al valore del campo della voce di log:
Coppia chiave-valoreLogRecord.attributeOpenTelemetry. |
Valore memorizzato nel seguente campoLogEntry(Nomi dal riferimento HTTP) |
Tipo accettato |
|---|---|---|
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 |
Campo Etichette
Per determinare quali etichette allegare alla voce di log, il sistema esegue le seguenti azioni:
Rimuove dal record di log OTLP tutti gli attributi che sono stati mappati a campi
LogEntryspecifici.Ad esempio, supponiamo che a un record di log siano associati i seguenti attributi:
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", }, }Dopo aver rimosso i campi mappati a campi
LogEntryspecifici, rimangono i seguenti campi:attributes: { "log_array_attr: ["value1", "value2"], "log_json_attr": {"json_key": "json_value"} "log-string-attr": "string", }Se un attributo contiene un array o elementi JSON, il sistema converte il valore in una stringa.
Ad esempio, di seguito viene illustrato come
LogEntryrappresenta gli attributi precedenti:labels: { "log_array_attr": "[\"value1\",\"value2\"]", "log_json_attr": "{\"json_key\":\"json_value\"}", "log-string-attr": "string", }La profondità massima di nidificazione degli attributi è cinque. I contenuti con un nidificazione più profonda vengono troncati.
Campo dell'operazione
Google Cloud Observability mappa gli attributi OTLP che si applicano all'operazione al campo operation di un LogEntry. Le sezioni seguenti descrivono come il sistema mappa gli attributi nidificati.
L'attributo gcp.operation deve contenere tipi di coppie chiave-valore. I nomi degli attributi
appiattiti non sono supportati. L'esempio seguente mostra un record di log il cui attributo gcp.operation contiene quattro coppie chiave-valore:
log_record {
attributes: {
gcp.operation {
"id": "abc123",
"producer": "my_producer",
"first": "true",
"last": "false",
}
}
}
La tabella seguente descrive come Google Cloud Observability mappa gcp.operation a LogEntry:
Coppia chiave-valoreLogRecord.attribute.operationOpenTelemetry. |
Valore memorizzato nel seguente campo dell'operazioneLogEntry |
Tipo accettato |
|---|---|---|
id |
id |
string |
producer |
httpRequest.requestUrl |
string |
first |
first |
bool |
last |
last |
bool |
Campo Otel
Per i campi nei dati di log OTLP che non hanno un campo equivalente in un
LogEntry, il sistema converte i tipi di dati e poi aggiunge
i dati convertiti al campo otel. Ad esempio, il campo otel memorizza gli attributi dei campi resource, scope e entity.
Il sistema utilizza le seguenti regole per convertire i
tipi di dati OpenTelemetry
nei tipi protobuf Value:
| Tipo OpenTelemetry | tipo protobuf |
|---|---|
string |
string |
boolean |
bool |
integer |
double |
float |
double |
Array |
ListValues |
KeyValueList |
Struct |
Per evitare errori di precisione doppia, passa i numeri interi come stringhe.
campo Payload
Il tipo di dati del campo OTLP logRecord.body determina la struttura del payload LogEntry:
string: il sistema copia la stringa nel campoLogEntry.textPayload.Array: il sistema crea una stringa degli elementi dell'array preservando le nuove righe. Poi copia la stringa nel campoLogEntry.textPayload.KeyValueList: il sistema converte queste coppie in JSON e poi compila il campoLogEntry.jsonPayload, con le seguenti limitazioni:- Quando un record OTLP contiene chiavi di attributo duplicate, il sistema conserva la prima chiave ed elimina gli attributi con chiavi duplicate.
- Quando la profondità di nidificazione di una coppia JSON è superiore a cinque, il sistema tronca i contenuti a una profondità di cinque.
Campo Gravità
Questa sezione descrive come Google Cloud Observability mappa i campi di gravità di OpenTelemetry ai livelli di gravità di Cloud Logging.
OpenTelemetry definisce un numero e un testo di gravità. logs.proto definisce i numeri di gravità.
Google Cloud Observability determina la gravità di Logging dal numero di gravità di OpenTelemetry, se impostato. In caso contrario, utilizza il testo della gravità. Se non è impostato nessuno dei due, il livello di gravità di Logging è impostato su DEFAULT.
| Numero di gravità OpenTelemetry Enum (valore) |
Testo della gravità di OpenTelemetry (i test non fanno distinzione tra maiuscole e minuscole) |
Gravità di Cloud Logging Enum (valore) |
|---|---|---|
SEVERITY_NUMBER_UNSPECIFIED (0) |
"default" non impostato |
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) |
Campo SourceLocation
Google Cloud Observability mappa il seguente codice OTLP direttamente ai campi LogEntry. Questa mappatura è possibile perché questi attributi OpenTelemetry sono semanticamente identici ai concetti di Cloud Logging.
Coppia chiave-valoreLogRecord.attributeOpenTelemetry. |
Valore memorizzato nel seguente campoLogEntry(Nomi dal riferimento HTTP) |
Tipo accettato |
|---|---|---|
code.file.path: Value |
sourceLocation.file |
string |
code.function.name: Value |
sourceLocation.function |
string |
code.function.number: Value |
sourceLocation.line |
string, int |
Limitazioni
Questa sezione descrive i limiti. Descrive inoltre il modo in cui Google Cloud Observability gestisce determinati tipi di dati.
Limiti
| Descrizione | Valore | Note |
|---|---|---|
| Numero massimo di log per richiesta OTLP | 8192 | Si riferisce al numero massimo di logRecords in una struttura OTLP resourceLogs. Limite. |
| Dimensione massima di ogni richiesta | 5 MiB | Limite. |
Dimensione massima di una LogEntrycreata da un record di log OTLP |
256 KiB | Cloud Logging tronca o elimina i dati da un record di log OTLP quando necessario. Limite. |
| Lunghezza massima di una chiave di attributo | 512 B | Le chiavi delle etichette di dimensioni eccessive vengono troncate quando il record di log OTLP viene convertito in un LogEntry. Limite. |
| Lunghezza massima di un valore dell'attributo | 64 KiB | Valori delle etichette di dimensioni eccessive quando il record di log OTLP viene convertito in un
LogEntry. Limite. |
| Profondità massima di nidificazione degli attributi | 20 | Le richieste con attributi che superano questo limite vengono rifiutate quando il record di log OTLP viene convertito in un LogEntry. |
| Numero massimo di byte di importazione dei log al minuto | 2,4 GB per le seguenti regioni: 300 MB per tutte le altre regioni. |
Quota. |
Comportamento
Quando sono impostati sia il numero che il testo della gravità di OpenTelemetry, il sistema utilizza il numero della gravità per determinare il livello di gravità di Cloud Logging. Se il record OTLP non contiene informazioni sulla gravità, il livello di gravità di Cloud Logging viene impostato su
DEFAULT.Quando un record OTLP contiene chiavi di attributo duplicate, il sistema conserva la prima chiave ed elimina gli attributi con chiavi duplicate.
Il sistema converte gli attributi associati a un record di log in una stringa. Per un esempio, consulta il campo Etichette.
I nomi dei log devono essere sicuri per l'URL o vengono codificati come URL durante l'importazione. Per informazioni su come vengono impostati i nomi dei log, consulta Come vengono impostati i campi
LogEntry.
Configura Google Cloud Observability per utilizzare le mappature dell'esportatore
Google Cloud Observability e l'esportatore Google Cloud per Cloud Logging utilizzano regole diverse per creare oggetti LogEntry dai dati di log formattati in OTLP. Ad esempio, Google Cloud Observability compila il campo otel, ma gli esportatori no.
Se vuoi che Google Cloud Observability utilizzi le stesse regole di mappatura degli esportatori, apporta le seguenti modifiche alle tue applicazioni che inviano record di log OTLP all'API Telemetry:
Aggiungi l'attributo
gcp.use_legacy_mappingalla risorsa inclusa nella richiesta. Per saperne di più, consulta Aggiunta o eliminazione di attributi.Quando questo attributo è impostato, si verifica quanto segue:
- Il campo
otelnon è compilato. Gli attributi che iniziano con
gcpvengono ignorati con le seguenti eccezioni:gcp.log.namegcp.insert_id
I due attributi precedenti sono mappati ai campi
LogEntry.
La regola di mappatura precedente fa sì che Google Cloud Observability elimini alcuni contenuti. Tuttavia, le dimensioni degli oggetti
LogEntrysono inferiori.- Il campo
Aggiungi al raccoglitore HTTP OTLP i processori che impostano le seguenti etichette di log:
instrumentation_scope: impostato suinstrumentation_scope.name.instrumentation_version: impostato suinstrumentation_scope.version.service.name: impostato suresource.attributes["service.name"].service.namespace: impostato suresource.attributes["service.namespace"].service.instance.id: impostato suresource.attributes["service.instance.id"].
Per un esempio, consulta Esegui la migrazione all'esportatore OTLP: processori.