v1.logs overview

Questo documento descrive come i dati di log inviati a your Google Cloud project utilizzando l'API Telemetry (OTLP) vengono mappati a una struttura di Cloud Logging. Questa API implementa il protocollo OTLP OpenTelemetry. Puoi inviare dati a questa API quando instrumenti le tue applicazioni con un otlphttp esportatore e un agente di raccolta OpenTelemetry o quando utilizzi gli SDK OpenTelemetry.

OpenTelemetry è un progetto open source supportato Google Cloudcon Google Cloud ingegneri che garantiscono il supporto per l'importazione e la visualizzazione della telemetria.

Struttura generale dei dati di log in formato 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, 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 logs.proto di OpenTelemetry.

Come vengono elaborati i dati di log in formato OTLP

Quando invii una struttura resourceLogs OTLP all'API Telemetry, Google Cloud Observability esegue le seguenti azioni:

Per ogni logRecord, il sistema crea un LogEntry.

I seguenti documenti descrivono come il sistema popola LogEntry dai dati di log OTLP:
- Mappatura dei record di log OTLP alle voce di log log.
- Mappatura degli attributi OTLP al tipo di risorsa Cloud Logging.
Poiché ogni LogEntry contiene informazioni sul tipo di risorsa Cloud Logging corrispondente, ogni LogEntry potrebbe essere più grande del logRecord OTLP corrispondente.

La conversione dalla struttura resourceLogs OTLP a una serie di strutture LogEntry potrebbe essere con perdita di dati. Ciò significa che potresti non essere in grado di convertire dalla struttura LogEntry ai campi resource e logRecord originali.
LogEntry viene indirizzato da sink aggregati nella gerarchia dei progetti e da sink nel progetto, esattamente come se la voce di log fosse stata inviata al tuo progetto utilizzando l'API Cloud Logging.

Best practice

Quando instrumenti le tue applicazioni per inviare dati di traccia al tuo Google Cloud progetto, ti consigliamo di utilizzare un esportatore che scrive i dati in formato OTLP in un agente di raccolta, che poi invia i dati di traccia all'API Telemetry. Nel raccoglitore, specifica solo l'URL di base:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry rileva il tipo di dati e aggiunge automaticamente /v1/traces, /v1/metrics o /v1/logs, a seconda dei casi. Per saperne di più, consulta Richiesta OTLP/HTTP.

Per esempi di esportazione di dati di traccia o metriche nell'API Telemetry, consulta i seguenti documenti:

Quando non puoi utilizzare un agente di raccolta, puoi utilizzare una libreria OpenTelemetry che contiene un esportatore OTLP in-process per inviare la telemetria all'API Telemetry. Per scoprire come esportare direttamente i dati di traccia, consulta Esportatore Cloud Trace all'endpoint OTLP.

Autenticazione

Devi configurare gli esportatori con le credenziali necessarie per inviare dati a your Google Cloud project. Ad esempio, quando utilizzi i raccoglitori, in genere utilizzi anche l'estensione googleclientauth per l'autenticazione con le credenziali Google.

Per un esempio di autenticazione quando utilizzi l'esportazione diretta dei dati di traccia, consulta Configurare l'autenticazione. Questo esempio illustra come configurare l'esportatore con le tue Google Cloud credenziali predefinite dell'applicazione (ADC) e aggiungere una libreria di autenticazione Google specifica per la lingua alla tua applicazione.

Cloud Logging e localizzazione dei dati

Per impostazione predefinita, Cloud Logging indirizza le voci di log provenienti da un progetto ai bucket di log creati dal sistema. I bucket di log sono risorse regionali. Puoi aggiornare il sink di log predefinito per inviare le voci di log a un bucket di log personalizzato in una località di tua scelta. Per saperne di più, consulta Regionalizzare i log.

Cloud Logging fornisce impostazioni che puoi configurare per organizzazioni e cartelle. Queste impostazioni specificano la posizione dei nuovi bucket di log creati dal sistema, se questi bucket di log utilizzano chiavi di crittografia gestite dal cliente (CMEK) e la configurazione del sink di log predefinito. Per saperne di più, consulta Supporto per organizzazioni e cartelle.

Dove visualizzare i dati importati

Puoi visualizzare i dati di log utilizzando le pagine Esplora log e Analisi di osservabilità. Per informazioni, consulta le seguenti pagine:

Limitazioni

Questa sezione descrive i limiti. Descrive anche 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.
Dimensione massima 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 se 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	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 di 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 sia 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 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 collegati a un record di log in una stringa. Per un esempio, vedi Campo Etichette.
I nomi dei log devono essere sicuri per gli 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.