Visualizza i log con routing a BigQuery

Questo documento spiega come trovare le voci di log instradate da Cloud Logging alle tabelle BigQuery. Logging sink inserisce flussi di dati di logging in BigQuery in piccoli batch, in modo da poter eseguire query sui dati senza eseguire un job di caricamento. Per aiutarti a creare query e comprendere il formato della tua tabella BigQuery, in questo documento viene anche descritto lo schema BigQuery per i log con routing.

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 siano disponibili le prime voci di log.

Prima di iniziare

Per una discussione concettuale dei sink, consulta Panoramica dei modelli di routing e archiviazione: sink.

Per istruzioni su come eseguire il routing dei log, consulta Eseguire il routing dei log alle destinazioni supportate.

Per scoprire come vengono denominati i campi voce di log con routing, consulta Schema di BigQuery per i log con routing.

Visualizza i log

Per visualizzare i log con routing a BigQuery:

  1. Nel pannello di navigazione della console Google Cloud, seleziona BigQuery:

    Vai a BigQuery

  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 restituire i dati.

Query di esempio

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

Query Compute Engine di esempio

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

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

  • La query recupera i risultati per una singola istanza di 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 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 con routing

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

Convenzioni di denominazione dei campi

Esistono alcune convenzioni di denominazione che si applicano ai campi voce di log quando invii 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. Tutti i caratteri non supportati vengono rimossi dai nomi dei campi e sostituiti con il trattino basso. 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. Tutti i trattini bassi iniziali vengono rimossi.

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

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

  • Per i campi nei payload strutturati, a condizione che non sia presente l'identificatore @type, i nomi dei campi BigQuery corrispondenti sono normalizzati in minuscolo, ma per il resto la denominazione viene mantenuta.

    Per informazioni sui payload strutturati in cui è presente lo specificatore @type, consulta Campi payload con @type in questa pagina.

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

Campo di immissione del log Mappatura dei tipi LogEntry Nome 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 di payload con @type

Questa sezione illustra nomi speciali dei campi dello schema BigQuery per le voci di log i cui payload contengono l'identificatore @type. Sono incluse le voci degli audit log instradate a BigQuery.

I payload nelle voci di log possono contenere dati strutturati. Qualsiasi campo strutturato può includere un specificatore di tipo facoltativo nel seguente formato:

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

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

Regole di denominazione per @type

Ai campi strutturati con identificatori di tipo vengono assegnati abitualmente nomi dei campi BigQuery a cui viene aggiunto un [TYPE]. Il valore di [TYPE] può essere qualsiasi stringa.

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

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

Payload Payload @type campo Payload Nome 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 si applicano alcune eccezioni per i campi con identificatori di tipo:

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

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

Esempio

Questo esempio mostra come vengono denominati e utilizzati i campi payload strutturati 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 un specificatore @type. Il suo nome BigQuery è jsonpayload_v1_customtype.

  • I campi nidificati vengono trattati con le regole di denominazione standard di BigQuery, poiché le regole dell'identificatore di tipo non si applicano ai campi nidificati.

Pertanto, per il payload della voce di 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 gli audit log che sono stati instradati a BigQuery, puoi saltare questa sezione.

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

I due insiemi di nomi dei campi del payload dell'audit log sono elencati nella seguente tabella:

Campo di immissione del log Nome 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 gli audit log generati da BigQuery e che vengono quindi instradati da Cloud Logging a BigQuery. Queste voci dell'audit log contengono un campo serviceData con un specificatore @type pari a type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Esempio

Una voce di audit log generata da BigQuery include un campo con il seguente nome:

protoPayload.serviceData.tableInsertRequest

Se questa voce di log venisse instradata 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, nelle tabelle BigQuery viene fatto riferimento allo stesso campo, come segue:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Organizzazione della tabella

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

Quando esegui il routing dei log su un set di dati BigQuery, Logging crea tabelle per contenere le voci di 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 sul tipo di tabella corrispondente. 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.

Logging organizza i dati che instrada in due tipi di tabella: tabelle con sharding delle date e tabelle partizionate. Entrambi i tipi di tabella suddividono i dati dei log in base ai campi timestamp delle voci di log. Tuttavia, ci sono due differenze fondamentali tra i tipi di tabelle, come segue:

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

  • Nomenclatura della tabella: i tipi di tabella utilizzano convenzioni di denominazione diverse, come illustrato nella sezione di seguito.

Organizzazione della tabella

Le voci di log vengono segmentate in tabelle BigQuery le cui organizzazioni e nomi si basano sui timestamp e sui nomi di log delle voci.

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

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

Nome log Voce di log timestamp1 Nome tabella BigQuery
(con sharding in base alla 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 delle voci di log sono espressi nel fuso orario UTC (tempo universale coordinato).

Creazione delle tabelle partizionate

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

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

Mancata corrispondenza 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 sul tipo di tabella corrispondente.

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, quella voce di log genera una tabella con un tipo di stringa per il 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 non presente nello schema attuale e l'inserimento di questo campo nella tabella di destinazione supererebbe il limite di colonne di BigQuery.

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

Quando BigQuery identifica una mancata corrispondenza dello schema, crea una tabella all'interno del set di dati corrispondente per archiviare le informazioni sull'errore. Il tipo di tabella determina il nome della tabella. Per le tabelle con shard con data, il formato di denominazione è export_errors_YYYYMMDD. Per le tabelle partizionate, il formato di denominazione è export_errors. Per saperne di più, consulta Organizzazione della tabella.

Durante il routing delle 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 gruppo di messaggi attuale:

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

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

Schema della tabella degli errori

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

  • logEntry: contiene la voce di log completa, ma viene convertita da JSON in una stringa.
  • schemaErrorDetail: contiene il messaggio di errore completo restituito da BigQuery.
  • sink: contiene il percorso completo della risorsa per il sink 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.

Logging comunica le mancate corrispondenze dello schema al progetto Google Cloud che contiene il sink di routing nei seguenti modi:

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

Evitare future mancate corrispondenze dei tipi di campi

Per correggere la mancata corrispondenza 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 la mancata corrispondenza dello schema quando non puoi modificare un tipo di campo, rinomina la tabella o modifica i parametri del sink, in modo che Logging ricrea la tabella in un set di dati diverso. Per istruzioni, consulta Gestire i sink.

Risoluzione dei problemi

Se i log sembrano non essere presenti nella destinazione del sink o se sospetti che il sink non esegua correttamente il routing dei log, consulta Risolvere i problemi di routing dei log.

Prezzi

Cloud Logging non prevede addebiti per instradare i log a una destinazione supportata, ma per la destinazione potrebbero essere applicati dei costi. Ad eccezione del bucket di log _Required, Cloud Logging addebita un costo per trasmettere i log nei bucket di log e per un'archiviazione più lunga rispetto al periodo di conservazione predefinito del bucket di log.

Cloud Logging non addebita costi per la copia dei log o per le query eseguite tramite la pagina Esplora log o la pagina Analisi dei log.

Per ulteriori informazioni, consulta i seguenti documenti: