v1.logs overview

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

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

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 elaborati i dati di log formattati in OTLP

Quando invii una struttura OTLP resourceLogs 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 compila LogEntry dai dati di log OTLP:
- Mappatura del record di log OTLP alla voce di 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 OTLP resourceLogs a una serie di strutture LogEntry potrebbe comportare una perdita di dati. ovvero potresti non essere in grado di convertire la struttura LogEntry nei campi originali resource e logRecord.
LogEntry viene indirizzato dai sink aggregati nella gerarchia del progetto e dai 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 progettoGoogle Cloud , ti consigliamo di utilizzare un esportatore che scriva dati in formato OTLP in un agente di raccolta, che poi invia i dati di traccia all'API Telemetry. Nell'agente di raccolta, 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 i dati al tuo progetto Google Cloud . 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 Configura l'autenticazione. Questo esempio mostra 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 residenza dei dati

Per impostazione predefinita, Cloud Logging instrada le voci di log provenienti da un progetto ai bucket di log creati dal sistema. I bucket di log sono risorse a livello di regione. Puoi aggiornare il sink di log predefinito per inviare le voci di log a un bucket di log personalizzato che si trova in una località a tua scelta. Per scoprire 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ù, vedi Supporto per organizzazioni e cartelle.

Dove visualizzare i dati importati

Puoi visualizzare i dati dei log utilizzando le pagine Esplora log e Observability Analytics. Per informazioni, consulta le seguenti risorse:

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.
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 sia il testo della 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.