Mappatura del record di log OTLP alla voce di log

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 event_name nell'LogRecord OTLP. Se questo campo non esiste o non è impostato, il sistema utilizza il seguente elenco con priorità degli attributi dei record di log OpenTelemetry per determinare il nome del log:

  • 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

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 timestamp:

  • time_unix_nano quando non è zero.
  • observed_time_unix_nano quando non è zero.
  • L'ora in cui è stata importata la voce di log.

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 gcp.http_request nel record di log ai campi LogEntry equivalenti. Il sistema accetta questi attributi come attributi strutturati o come stringa JSON. Per saperne di più, consulta il campo HttpRequest.

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.
apphub
apphubDestination
apphubSource
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 gcp.operation nel record di log ai campi LogEntry equivalenti. Per saperne di più, consulta Campo Operation.

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-valore
LogRecord.attribute
OpenTelemetry.
Valore memorizzato nel seguente campo
LogEntry
(Nomi dal riferimento HTTP)
Tipo accettato
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

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-valore
LogRecord.attribute
OpenTelemetry.
Valore memorizzato nel seguente campo
LogEntry
(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 {
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

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 a 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, di seguito viene illustrato 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 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-valore
LogRecord.attribute.operation
OpenTelemetry.
Valore memorizzato nel seguente campo dell'operazione
LogEntry
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 campo LogEntry.textPayload.

  • Array: il sistema crea una stringa degli elementi dell'array preservando le nuove righe. Poi copia la stringa 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à 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-valore
LogRecord.attribute
OpenTelemetry.
Valore memorizzato nel seguente campo
LogEntry
(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 LogEntry
creata 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: 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 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:

  1. Aggiungi l'attributo gcp.use_legacy_mapping alla risorsa inclusa nella richiesta. Per saperne di più, consulta Aggiunta o eliminazione di attributi.

    Quando questo attributo è impostato, si verifica quanto segue:

    1. Il campo otel non è compilato.
    2. Gli attributi che iniziano con gcp vengono ignorati con le seguenti eccezioni:

      • gcp.log.name
      • gcp.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 LogEntry sono inferiori.

  2. Aggiungi al raccoglitore HTTP OTLP i processori che impostano le seguenti etichette di log:

    • instrumentation_scope: impostato su instrumentation_scope.name.
    • instrumentation_version: impostato su instrumentation_scope.version.
    • service.name: impostato su resource.attributes["service.name"].
    • service.namespace: impostato su resource.attributes["service.namespace"].
    • service.instance.id: impostato su resource.attributes["service.instance.id"].

    Per un esempio, consulta Esegui la migrazione all'esportatore OTLP: processori.