Mappatura del record di log OTLP alla voce di log

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento descrive in che modo Google Cloud Observability determina i campi di un LogEntry dal record di log OTLP, quando questo record viene inviato a Google Cloud utilizzando l'API Telemetry.

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 di questi log, che è rappresentata dalla struttura resource.

Quando Google Cloud Observability riceve un oggetto resourceLogs, crea 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 in formato OTLP, consulta la pagina 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)	Come il sistema determina il valore del campo
logName	Il sistema utilizza il seguente elenco prioritario di attributi dei record di log OpenTelemetry per determinare il nome del log: gcp.log_name log_name event_name I nomi dei log devono essere sicuri per URL o vengono codificati nell'URL durante l'importazione.
resource	Il sistema utilizza le informazioni impostate nel campo resource o deduce la risorsa. Per maggiori dettagli, vedi Mappatura degli attributi OTLP al tipo di risorsa.
timestamp	Il sistema utilizza il seguente elenco prioritario di campi dei record di log OpenTelemetry per determinare timestamp: time_unix_nano se diverso da zero. observed_time_unix_nano se diverso da zero. L'ora in cui è stata importata la voce di log. Il periodo di conservazione del bucket dei log che archivia i dati determina il timestamp meno recente che può essere importato. Per maggiori informazioni, 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à Cloud Logging. Per maggiori dettagli, vedi Campo Gravità.
httpRequest	Il sistema mappa gli attributi gcp.http_request nel record di log ai campi LogEntry equivalenti. Per saperne di più, consulta la sezione Campo HttpRequest. FIXME. Esistono altri campi mappati a questo campo.
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	Non impostato.
sourceLocation	Il sistema imposta questo campo sui valori degli attributi Code del record di log. Per ulteriori informazioni, vedi Campo SourceLocation.
split	Non impostato.
apphub apphubDestination apphubSource	Non impostato.
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ù, vedi Campo Otel.
Payload	Il sistema imposta il payload convertendo il corpo di un record di log in un tipo di payload appropriato. Per saperne di più, vedi Campo Payload.

Campo HttpRequest

Google Cloud Observability mappa gli attributi OTLP che si applicano alle richieste HTTP ai campi LogEntry. Le sezioni seguenti descrivono come il sistema mappa gli attributi semplici e nidificati.

Attributi flat

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:

OpenTelemetry LogRecord.attribute coppia chiave-valore.	Valore memorizzato nel seguente campo LogEntry (Nomi del riferimento HTTP)	Tipo accettato
http.request.method	httpRequest.requestMethod	string
url.full http.url	httpRequest.requestUrl	string
http.request.body.size	httpRequest.requestSize	stringa, int
http.response.status_code	httpRequest.status	stringa, intero
http.response.body.size	httpRequest.responseSize	stringa, 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	stringa, int
cacheLookup	httpRequest.cacheLookup	bool
cacheHit	httpRequest.cacheHit	bool
cacheValidatedWithOriginServer	httpRequest.cacheValidatedWithOriginServer	bool
cacheFillBytes	httpRequest.cacheFillBytes	stringa, int
network.protocol.version protocol	httpRequest.protocol	string

Attributi nidificati

Questa sezione descrive in che modo Google Cloud Observability mappa gli attributi OTLP nidificati che si applicano alle richieste HTTP ai campi di un LogEntry. L'esempio seguente mostra 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",
    }
  }
}

Nella tabella, gli attributi nidificati vengono mostrati utilizzando le 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:

OpenTelemetry LogRecord.attribute coppia chiave-valore.	Valore memorizzato nel seguente campo LogEntry (Nomi del 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	stringa, int
gcp.http_request {status} http_request {status}	httpRequest.status	stringa, intero
gcp.http_request {responseSize} http_request {responseSize}	httpRequest.responseSize	stringa, 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	stringa, 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	stringa, 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:

1. Rimuove dal record di log OTLP tutti gli attributi che sono stati mappati a campi LogEntry specifici.

   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 su campi LogEntry specifici, rimangono i seguenti campi:

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

2. Se un attributo contiene un array o elementi JSON, il sistema converte il valore in una stringa.

   Ad esempio, la seguente illustrazione mostra come LogEntry rappresenta gli attributi precedenti:

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

   La profondità massima di annidamento per gli attributi è cinque. Tutti i contenuti con un livello di nidificazione più profondo vengono troncati.

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 in tipi protobuf Value:

Tipo OpenTelemetry	tipo protobuf
string	string
boolean	bool
integer	double
float	double
Array	ListValues
KeyValueList	Struct

Per evitare errori di doppia precisione, trasmetti i numeri interi come stringhe.

campo Payload

Nota: la dimensione massima di un LogEntry è 256 KiB. Questo limite è approssimativo e si basa sulle dimensioni interne dei dati. Se necessario, il sistema tronca il campo payload.

Il tipo di dati del campo logRecord.body OTLP determina la struttura del payload LogEntry:

• string: Il sistema copia la stringa nel campo LogEntry.textPayload.

• Array: il sistema crea una stringa degli elementi dell'array mantenendo i nuovi elementi. e la copia nel campo LogEntry.textPayload.

• KeyValueList: il sistema converte queste coppie in JSON e poi compila il campo LogEntry.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à OpenTelemetry, se impostato. In caso contrario, utilizza il testo della gravità. Se non è impostato nessuno dei due, la gravità del logging è impostata 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" not set	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 Code OTLP direttamente ai campi LogEntry. Questa mappatura è possibile perché questi attributi OpenTelemetry sono semanticamente identici ai concetti di Cloud Logging.

OpenTelemetry LogRecord.attribute coppia chiave-valore.	Valore memorizzato nel seguente campo LogEntry (Nomi del riferimento HTTP)	Tipo accettato
code.file.path: Value	sourceLocation.file	string
code.function.name: Value	sourceLocation.function	string
code.function.number: Value	sourceLocation.line	stringa, intero

Limitazioni

Questa sezione descrive i limiti. Descrive inoltre come 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.
Dimensioni massime di ogni richiesta	5 MiB	Limite.
Dimensione massima di un LogEntry creato 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 dell'attributo	512 B	Le chiavi delle etichette sovradimensionate 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 sovradimensionati quando il record di log OTLP viene convertito in un LogEntry. Limite.
Profondità massima di annidamento degli attributi	5	Gli attributi che superano questo limite vengono troncati 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: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1. 300 MB per tutte le altre regioni.	Quota.

Comportamento

• Quando vengono impostati sia il numero di gravità OpenTelemetry che il testo di gravità, il sistema utilizza il numero di 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 è 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 collegati a un record di log in una stringa. Per un esempio, vedi Campo Etichette.

• I nomi dei log devono essere sicuri per URL o vengono codificati nell'URL durante l'importazione. Per informazioni su come vengono impostati i nomi dei log, vedi Come vengono impostati i campi LogEntry.