Visualizza i log inviati a BigQuery

Questo documento spiega come trovare le voci di log instradate da Cloud Logging alle tabelle BigQuery. I sink di log caricano i dati di log in BigQuery in piccoli batch, il che ti consente di eseguire query sui dati senza eseguire un job di caricamento. Per aiutarti a creare query e comprendere il formato della tabella BigQuery, questo documento descrive anche lo schema BigQuery per i log instradati.

Cloud Logging utilizza l'API di streaming precedente per inviare le voci di log in streaming a BigQuery. In genere, le voci di log sono visibili in BigQuery entro un minuto. Tuttavia, quando viene creata una nuova tabella, potrebbero essere necessari diversi minuti prima che le prime voci di log siano disponibili.

Prima di iniziare

Per una discussione concettuale degli elementi di destinazione, consulta Panoramica dei modelli di routing e archiviazione: elementi di destinazione.

Per istruzioni su come instradare i log, consulta Instradare i log verso le destinazioni supportate.

Per scoprire come sono denominati i campi delle voce di log instradati, consulta Schema BigQuery per i log instradati.

Visualizza i log

Per visualizzare i log inviati a BigQuery:

  1. Nella console Google Cloud, vai alla pagina BigQuery:

    Vai a BigQuery Studio

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.

    Le voci di log sono visibili nella scheda Dettagli oppure puoi eseguire una query sulla tabella per visualizzare i dati.

Query di esempio

Per informazioni sulla sintassi delle query BigQuery, consulta Riferimento alle query. Particolarmente utili sono le funzioni carattere jolly della tabella, che consentono di eseguire query su più tabelle, e l'operatore appiattimento, che consente di visualizzare i dati dei campi ripetuti.

Query di Compute Engine di esempio

La seguente query BigQuery recupera le voci di log di più giorni e di più tipi di log:

  • La query cerca negli ultimi tre giorni dei log syslog e apache-access. La query è stata eseguita il 23 febbraio 2020 e riguarda tutte le voci di log ricevute il 21 e il 22 febbraio, oltre alle voci di log ricevute il 23 febbraio fino al momento dell'emissione della query.

  • La query recupera i risultati per una singola istanza Compute Engine,1554300700000000000.

SELECT
  timestamp AS Time,
  logName as Log,
  textPayload AS Message
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.syslog_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())),
  (TABLE_DATE_RANGE(my_bq_dataset.apache_access_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP()))
WHERE
  resource.type == 'gce_instance'
  AND resource.labels.instance_id == '1554300700000000000'
ORDER BY time;

Ecco alcune righe di output di esempio:

Row | Time                    | Log                                         | Message
--- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------
 5  | 2020-02-21 03:40:14 UTC | projects/project-id/logs/syslog             | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269;
 6  | 2020-02-21 04:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 7  | 2020-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2020:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2020-02-21 05:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 9  | 2020-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2020:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

Query di App Engine di esempio

La seguente query BigQuery recupera le richieste App Engine non riuscite dell'ultimo mese:

SELECT
  timestamp AS Time,
  protoPayload.host AS Host,
  protoPayload.status AS Status,
  protoPayload.resource AS Path
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_,
    DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP()))
WHERE
  protoPayload.status != 200
ORDER BY time

Ecco alcuni risultati:

Row | Time                    | Host                                  | Status | Path
--- | ----------------------- | ------------------------------------- | ------ | ------
 6  | 2020-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2020-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2020-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2020-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

Schema BigQuery per i log instradati

Gli schemi delle tabelle BigQuery per i log instradati si basano sulla struttura del tipo LogEntry e sui contenuti dei payload dei log. Cloud Logging applica anche regole per abbreviare i nomi dei campi dello schema BigQuery per gli audit log e per determinati campi del payload strutturato. Puoi visualizzare lo schema della tabella selezionando una tabella con voci di log instradate nell'interfaccia BigQuery.

Convenzioni di denominazione dei campi

Esistono alcune convenzioni di denominazione che si applicano ai campi voce di log quando si inviano i log a BigQuery:

  • I nomi dei campi delle voci di log non possono superare i 128 caratteri.

  • I nomi dei campi delle voci di log possono essere composti solo da caratteri alfanumerici. Eventuali caratteri non supportati vengono rimossi dai nomi dei campi e sostituiti con caratteri underscore. Ad esempio, jsonPayload.foo%% verrebbe trasformato in jsonPayload.foo__.

    I nomi dei campi delle voci di log devono iniziare con un carattere alfanumerico, anche dopo la trasformazione. Eventuali trattini bassi iniziali vengono rimossi.

  • Per i campi di voce di log che fanno parte del tipo LogEntry, i nomi dei campi BigQuery corrispondenti sono esattamente gli stessi dei campi di voce di log.

  • Per tutti i campi voce di log forniti dall'utente, i nomi dei campi BigQuery corrispondenti vengono normalizzati in minuscolo, ma la denominazione viene conservata.

  • Per i campi nei payload strutturati, a condizione che il parametro @type non sia presente, i nomi dei campi BigQuery corrispondenti vengono normalizzati alle lettere minuscole, ma la denominazione viene conservata.

    Per informazioni sui payload strutturati in cui è presente il parametro @type, consulta Campi del payload con @type in questa pagina.

I seguenti esempi mostrano come vengono applicate queste convenzioni di denominazione:

Campo della voce di log Mappatura del tipo LogEntry Nome del campo BigQuery
insertId insertId insertId
textPayload textPayload textPayload
httpRequest.status httpRequest.status httpRequest.status
httpRequest.requestMethod.GET httpRequest.requestMethod.[ABC] httpRequest.requestMethod.get
resource.labels.moduleid resource.labels.[ABC] resource.labels.moduleid
jsonPayload.MESSAGE jsonPayload.[ABC] jsonPayload.message
jsonPayload.myField.mySubfield jsonPayload.[ABC].[XYZ] jsonPayload.myfield.mysubfield

Campi del payload con @type

Questa sezione illustra i nomi dei campi dello schema BigQuery speciali per le voci di log i cui payload contengono lo specificatore @type. Sono incluse le voci del log di controllo indirizzate a BigQuery.

I payload nelle voci di log possono contenere dati strutturati. Qualsiasi campo strutturato può includere un'opzione facoltativa per specificare il tipo nel seguente formato:

@type: type.googleapis.com/[TYPE]

Le regole di denominazione spiegano perché il campo protoPayload di una voce di log di controllo potrebbe essere mappato al campo protopayload_auditlog dello schema BigQuery.

Regole di denominazione per @type

I campi strutturati con specificatori di tipo vengono solitamente assegnati ai nomi dei campi BigQuery a cui è stato aggiunto [TYPE]. Il valore di [TYPE] può essere una stringa qualsiasi.

Le regole di denominazione per @type si applicano solo al livello superiore di jsonPayload o protoPayload; i campi nidificati vengono ignorati. Quando vengono trattati i campi del payload strutturato di primo livello, la registrazione rimuove il prefisso type.googleapis.com.

Ad esempio, la tabella seguente mostra la mappatura dei campi del payload strutturato di primo livello ai nomi dei campi BigQuery:

Payload Payload @type Campo Payload Nome del campo BigQuery
jsonPayload (nessuno) statusCode jsonPayload.statusCode
jsonPayload type.googleapis.com/abc.Xyz statusCode jsonpayload_abc_xyz.statuscode
protoPayload (nessuno) statusCode protoPayload.statuscode
protoPayload type.googleapis.com/abc.Xyz statusCode protopayload_abc_xyz.statuscode

Alle regole precedenti per i campi con specificatori di tipo si applicano alcune eccezioni:

  • Nei log delle richieste di App Engine, il nome del payload nei log inviati a BigQuery è protoPayload, anche se il payload include un selettore di tipo.

  • Cloud Logging applica alcune regole speciali per abbreviare i nomi dei campi dello schema BigQuery per gli audit log. Questo argomento è trattato nella sezione Campi dei log di controllo di questa pagina.

Esempio

Questo esempio mostra come vengono denominati e utilizzati i campi del payload strutturato quando vengono ricevuti da BigQuery.

Supponiamo che il payload di una voce di log sia strutturato come segue:

jsonPayload: {
  @type: "type.googleapis.com/google.cloud.v1.CustomType"
    name_a: {
      sub_a: "A value"
    }
    name_b: {
      sub_b: 22
    }
  }

La mappatura ai campi BigQuery è la seguente:

  • Il campo strutturato di primo livello jsonPayload contiene uno specificatore @type. Il nome BigQuery è jsonpayload_v1_customtype.

  • I campi nidificati vengono trattati con le regole di denominazione standard di BigQuery, poiché le regole per gli specificatori di tipo non si applicano ai campi nidificati.

Pertanto, per il payload della voce del log sono definiti i seguenti nomi BigQuery:

  jsonpayload_v1_customtype
  jsonpayload_v1_customtype._type
  jsonpayload_v1_customtype.name_b
  jsonpayload_v1_customtype.name_b.sub_b
  jsonpayload_v1_customtype.name_a
  jsonpayload_v1_customtype.name_a.sub_a

Campi degli audit log

Se non utilizzi i log di controllo inviati a BigQuery, puoi saltare questa sezione.

I campi del payload del log di controllo protoPayload.request, protoPayload.response e protoPayload.metadata hanno specificatori @type, ma vengono trattati come dati JSON. In altre parole, i nomi degli schemi BigQuery sono i nomi dei campi con Json aggiunto e contengono dati di stringa in formato JSON.

I due insiemi di nomi di campi del payload del log di controllo sono elencati nella tabella seguente:

Campo della voce di log Nome del campo BigQuery
protoPayload protopayload_auditlog
protopayload.metadata protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
Esempio: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.responseJson

Tieni presente che la convenzione di denominazione serviceData è specifica per i log di controllo generati da BigQuery e poi inoltrati da Cloud Logging a BigQuery. Queste voci del log di controllo contengono un campo serviceData con un parametro @type di type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Esempio

Una voce di log di controllo generata da BigQuery ha un campo con il seguente nome:

protoPayload.serviceData.tableInsertRequest

Se questa voce di log venisse inoltrata a BigQuery, come verrebbe fatto riferimento al campo tableInsertRequest? Prima dell'abbreviazione del nome, il nome del campo corrispondente in BigQuery sarebbe:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Dopo l'abbreviazione del nome, viene fatto riferimento allo stesso campo nelle tabelle BigQuery come segue:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Organizzazione della tabella

Questa sezione fornisce una panoramica delle tabelle partizionate per i log inviati a BigQuery.

Quando inoltri i log a un set di dati BigQuery, la funzionalità Logging crea tabelle per contenere le voci dei log. La prima voce di log ricevuta da BigQuery determina lo schema per la tabella BigQuery di destinazione. BigQuery crea una tabella le cui colonne si basano sui campi della prima voce di log e suoi tipi. Le voci di log successive potrebbero causare una mancata corrispondenza dello schema. Per informazioni su quando si verificano e su come vengono gestiti, consulta Mancata corrispondenza nello schema.

Esistono due tipi di tabelle con cui logging organizza i dati che instrada: tabelle con suddivisione in base alla data e tabelle partizionate. Entrambi i tipi di tabelle partizionano i dati dei log in base ai campi timestamp delle voci di log. Tuttavia, esistono due differenze fondamentali tra i tipi di tabella, come segue:

  • Prestazioni: una tabella partizionata suddivide una tabella di grandi dimensioni in partizioni più piccole, in modo da poter migliorare le prestazioni delle query e, di conseguenza, controllare meglio i costi di BigQuery riducendo il numero di byte letti da una query.

  • Nomenclatura delle tabelle: i tipi di tabelle utilizzano convenzioni di denominazione diverse, come discusso nella sezione di seguito.

Organizzazione della tabella

Le voci di log vengono suddivise in tabelle BigQuery la cui organizzazione e i cui nomi si basano sui nomi e sui timestamp dei log delle voci.

I nomi delle tabelle sono preceduti dal suffisso della data di calendario del timestamp UTC della voce di log, utilizzando il formato di base ISO 8601 (AAAAMMGG).

La tabella seguente mostra esempi di come i nomi dei log e i timestamp dei sample vengono mappati ai nomi delle tabelle in BigQuery:

Nome log Voce del log timestamp1 Nome della tabella BigQuery
(con sharding per data)		 Nome tabella BigQuery
(partizionata)
syslog 2017-05-23T18:19:22.135Z syslog_20170523 syslog
apache-access 2017-01-01T00:00:00.000Z apache_access_20170101 apache_access
compute.googleapis.com/activity_log 2017-12-31T23:59:59.999Z compute_googleapis_com_activity_log_20171231 compute_googleapis_com_activity_log

1 I timestamp voce di log sono espressi in UTC (Tempo coordinato universale).

Creazione delle tabelle partizionate

Quando crei un sink per instradare i log a BigQuery, puoi utilizzare tabelle con suddivisione in partizioni per data o tabelle partizionate. La selezione predefinita è una tabella con suddivisione in blocchi in base alla data:

Per istruzioni su come creare i canali, consulta le seguenti risorse:

Mancate corrispondenze nello schema

La prima voce di log ricevuta da BigQuery determina lo schema per la tabella BigQuery di destinazione. BigQuery crea una tabella le cui colonne si basano sui campi della prima voce di log e suoi tipi.

Una mancata corrispondenza dello schema si verifica quando le voci di log vengono scritte nella tabella di destinazione e si verifica uno dei seguenti errori:

  • Una voce di log successiva modifica il tipo di campo per un campo esistente nella tabella.

    Ad esempio, se il campo jsonPayload.user_id della voce di log iniziale è un string, questa voce di log genera una tabella con un tipo di stringa per quel campo. Se in un secondo momento inizi a registrare jsonPayload.user_id come array, si verifica una mancata corrispondenza dello schema.

  • Una nuova voce di log contiene un campo che non è nello schema attuale e l'inserimento di questo campo nella tabella di destinazione supererebbe il limite di colonne BigQuery.

    La tabella di destinazione può accettare il nuovo campo se non comporta il superamento del limite di colonne.

Quando BigQuery identifica una mancata corrispondenza dello schema, crea una tabella nel set di dati corrispondente per archiviare le informazioni sull'errore. Il tipo di tabella determina il nome della tabella. Per le tabelle con suddivisione in parti in base alla data, il formato dei nomi è export_errors_YYYYMMDD. Per le tabelle partizionate, il formato dei nomi è export_errors. Per ulteriori informazioni, consulta Organizzazione delle tabelle.

Quando inoltra le voci di log, Logging invia i messaggi come batch a BigQuery. BigQuery utilizza le seguenti regole per determinare in quale tabella vengono scritte le voci di log nel batch corrente di messaggi:

  • Quando si verifica una modifica del tipo di campo, nella tabella degli errori vengono registrate solo le voci di log che hanno causato una mancata corrispondenza dello schema. Le voci di log nel batch corrente di messaggi che non causano una mancata corrispondenza dello schema vengono scritte nella tabella di destinazione originale.

  • Quando il limite di colonne viene superato, tutte le voci di log nel batch corrente di messaggi vengono scritte nella tabella degli errori.

Schema della tabella degli errori

La tabella degli errori contiene i dati di LogEntry e informazioni sulla mancata corrispondenza:

  • logEntry: contiene la voce di log completa, che viene tuttavia convertita da JSON in una stringa.
  • schemaErrorDetail: contiene il messaggio di errore completo restituito da BigQuery.
  • sink: contiene il percorso completo della risorsa per lsink di log.
  • logName: estratto da LogEntry.
  • timestamp: estratto da LogEntry.
  • receiveTimestamp: estratto da LogEntry.
  • severity: estratto da LogEntry.
  • insertId: estratto da LogEntry.
  • trace: estratto da LogEntry.
  • resourceType: estratto da LogEntry.

La registrazione comunica le mancate corrispondenze dello schema al progetto Google Cloud che contiene l'obiettivo di routing nei seguenti modi:

  • I proprietari del progetto ricevono un'email. I dettagli includeranno: ID progetto Google Cloud, nome della destinazione e destinazione.
  • Nella pagina Attività della console Google Cloud viene visualizzato un errore, Stackdriver Config error. I dettagli includono il nome e la destinazione della destinazione e un link a un esempio di voce di log che ha causato l'errore.

Evitare future mancate corrispondenze del tipo di campo

Per correggere le mancate corrispondenze del tipo di campo per le voci di log successive, correggi il tipo di campo in modo che corrisponda allo schema corrente. Per informazioni su come correggere un tipo di campo, consulta Modificare il tipo di dati di una colonna.

A volte il tipo di campo non può essere modificato, ad esempio non puoi modificare un tipo di campo per i log generati automaticamente dai servizi Google Cloud. Per evitare mancate corrispondenze dello schema quando non puoi modificare un tipo di campo, rinomina la tabella o modifica i parametri del sink in modo che Logging ricrei la tabella in un set di dati diverso. Per le istruzioni, vedi Gestire i sink.

Risoluzione dei problemi

Se nella destinazione del sink sembrano mancare dei log o se sospetti che il sink non stia instradando correttamente i log, consulta Risolvere i problemi relativi all'instradamento dei log.

Prezzi

Cloud Logging non addebita alcun costo per il routing dei log a una destinazione supportata. Tuttavia, la destinazione potrebbe applicare dei costi. Ad eccezione del bucket di log _Required, Cloud Logging addebita lo streaming dei log nei bucket di log e per l'archiviazione per un periodo superiore al periodo di conservazione predefinito del bucket di log.

Cloud Logging non addebita alcun costo per la copia dei log, per la definizione degli ambiti dei log o per le query inviate tramite le pagine Esplora log o Analisi dei log.

Per ulteriori informazioni, consulta i seguenti documenti: