Questo documento spiega come trovare le voci di log che hai instradato da Cloud Logging alle tabelle BigQuery. I sink di logging trasmettono i dati di logging 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 tua tabella BigQuery, questo documento descrive anche lo schema BigQuery per i log indirizzati.
Cloud Logging utilizza l'API di streaming legacy per trasmettere in streaming le voci di log 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 siano disponibili le prime voci di log.
Prima di iniziare
Per una discussione concettuale sui sink, vedi Panoramica dei modelli di routing e archiviazione: sink.
Per istruzioni su come instradare i log, consulta Instradare i log verso destinazioni supportate.
Per scoprire come vengono denominati i campi delle voce di log instradate, consulta Schema BigQuery per i log instradati.
Visualizza i log
Per visualizzare i log indirizzati a BigQuery:
-
Nella console Google Cloud , vai alla pagina BigQuery.
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
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 alle query. Particolarmente utili sono le funzioni jolly della tabella, che consentono di eseguire query su più tabelle, e l'operatore Flatten, che consente di visualizzare i dati dei campi ripetuti.
Query Compute Engine di esempio
La seguente query BigQuery recupera le voci di log di più giorni e più tipi di log:
La query esegue la ricerca negli ultimi tre giorni dei log
syslogeapache-access. La query è stata eseguita il 23 febbraio 2020 e copre 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 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 indirizzati
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
Quando invii i log a BigQuery, devi rispettare alcune convenzioni di denominazione per i campi delle voce di log:
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. I caratteri non supportati vengono rimossi dai nomi dei campi e sostituiti con caratteri di sottolineatura. Ad esempio,
jsonPayload.foo%%verrà trasformato injsonPayload.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 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 vengono normalizzati in minuscolo, ma la denominazione viene altrimenti conservata.
Per i campi nei payload strutturati, se lo specificatore
@typenon è presente, i nomi dei campi BigQuery corrispondenti vengono normalizzati in minuscolo, ma la denominazione viene altrimenti conservata.Per informazioni sui payload strutturati in cui è presente lo specificatore
@type, consulta la sezione Campi del payload con@typein questa pagina.
I seguenti esempi mostrano come vengono applicate queste convenzioni di denominazione:
| Campo della voce di log | Mappatura del tipo di 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 descrive i nomi speciali dei campi dello schema BigQuery per le voci di log i cui payload contengono lo specificatore @type. Per informazioni sulle regole di denominazione dei log di controllo, consulta la sezione Campi dei log di controllo di questa pagina.
I payload nelle voci di log possono contenere dati strutturati. Qualsiasi campo strutturato può includere uno specificatore di tipo facoltativo nel seguente formato:
@type: type.googleapis.com/[TYPE]
Regole di denominazione per @type
Ai campi strutturati con specificatori di tipo vengono assegnati
di solito nomi di campi BigQuery con [TYPE] aggiunto al nome
del campo. Il valore di [TYPE] può essere una qualsiasi stringa.
Il tipo di voce di log determina le regole di denominazione per i campi con lo specificatore
@type. Per le voci di log che non sono log di controllo, queste regole
si applicano solo al livello superiore di jsonPayload o protoPayload; i campi nidificati
vengono ignorati. Per informazioni sulle regole di denominazione dei log di controllo,
vedi la sezione Campi dei log di controllo in questa pagina.
Quando tratta i campi del payload strutturato di primo livello, Logging rimuove il prefisso type.googleapis.com.
Ad esempio, la seguente tabella mostra il mapping dei campi del payload strutturato di primo livello ai nomi dei campi BigQuery per le voci di log che non sono audit log:
| 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 |
Per i campi con identificatori di tipo, si applicano alcune eccezioni alle regole precedenti:
Nei log di richiesta App Engine, il nome del payload nei log indirizzati a BigQuery è
protoPayload, anche se il payload include un identificatore di tipo.La tabella precedente non si applica agli audit log. 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
}
}
Il mapping ai campi BigQuery è il seguente:
Il campo strutturato di primo livello
jsonPayloadcontiene uno 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 di specifica del 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 log di controllo instradati a BigQuery, puoi saltare questa sezione.
Questa sezione si applica ai campi strutturati che possono includere uno specificatore di tipo facoltativo nel seguente formato:
@type: type.googleapis.com/[TYPE]
Modifiche ai nomi dei campi
Quando un audit log contiene un payload con uno specificatore @type, Cloud Logging
potrebbe modificare il valore [TYPE] aggiunto allo specificatore prima
che venga generato il nome del campo BigQuery. Queste modifiche
comportano nomi dei campi BigQuery più brevi.
La registrazione rimuove sempre il prefisso type.googleapis.com dal valore [TYPE]. La tabella seguente descrive quando Logging
abbrevia i nomi dei campi:
Valore [TYPE] originale |
Valore [TYPE] modificato |
|---|---|
google.cloud.audit.AuditLog |
AuditLog |
google.appengine.legacy.AuditData |
legacy.appengine |
google.appengine.v1alpha.AuditData |
v1alpha.appengine |
google.appengine.v1beta.AuditData |
v1beta.appengine |
google.appengine.v1beta4.AuditData |
v1beta4.appengine |
google.appengine.v1beta5.AuditData |
v1beta5.appengine |
google.appengine.v1.AuditData |
v1.appengine |
google.cloud.bigquery.logging.v1.AuditData |
v1.bigquery |
google.iam.v1.logging.AuditData |
v1.iam |
google.iam.admin.v1.AuditData |
v1.iam.admin |
google.type.Money |
money |
google.appengine.logging.v1.RequestLog |
Ad esempio, supponiamo che una voce dell'audit log contenga i seguenti contenuti:
{
logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "type.googleapis.com/google.cloud.audit.AuditLog"
serviceData: {
@type: "type.googleapis.com/google.appengine.legacy.AuditData"
eventData: {
timezone: "UTC"
}
}
}
}
I nomi dei campi BigQuery derivano dalla voce di log modificata, che è la seguente:
{
logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "AuditLog"
serviceData: {
@type: "legacy.appengine"
eventData: {
timezone: "UTC"
}
}
}
}
Regole di denominazione per @type
Nei log di controllo, diversi campi possono avere uno specificatore @type:
protoPayloadprotoPayload.serviceDataprotoPayload.requestprotoPayload.responseprotoPayload.metadata
I campi request, response e metadata vengono trattati come dati JSON.
ovvero i nomi dello schema BigQuery sono i nomi dei campi con
Json aggiunto e contengono dati stringa in formato JSON.
I due set di nomi dei 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.request |
protopayload_auditlog.requestJson |
protoPayload.response |
protopayload_auditlog.responseJson |
protoPayload.serviceData |
protopayload_auditlog.servicedata_v1_bigquery Esempio: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest |
protoPayload.status.code |
protoPayload_auditlog.statuscode |
Tieni presente che la convenzione di denominazione serviceData è specifica per i log di controllo generati da BigQuery e poi indirizzati da Cloud Logging a BigQuery. Queste voci dell'audit log contengono un campo
serviceData con uno specificatore @type di
type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.
Esempio
Una voce di audit log generata da BigQuery ha un campo con il seguente nome:
protoPayload.serviceData.tableInsertRequest
Se questa voce di log venisse poi indirizzata a BigQuery, come verrebbe fatto riferimento al campo tableInsertRequest? Prima dell'abbreviazione del nome, il
nome del campo corrispondente in BigQuery era:
protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest
Dopo l'abbreviazione del nome, lo stesso campo viene fatto riferimento nelle tabelle BigQuery nel seguente modo:
protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
Organizzazione della tabella
Questa sezione fornisce una panoramica delle tabelle partizionate per i log indirizzati a BigQuery.
Quando indirizzi i log a 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 sui relativi tipi. Le voci di log successive potrebbero causare una mancata corrispondenza dello schema. Per informazioni su quando si verificano e su come vengono gestite, vedi Mancata corrispondenza nello schema.
Esistono due tipi di tabelle in base ai quali
Logging organizza i dati che instrada: tabelle suddivise per 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 tabelle:
Prestazioni: una tabella partizionata divide una tabella grande in partizioni più piccole, in modo da 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 descritto nella sezione seguente.
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 hanno come suffisso la data del 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 voce di log sono espressi in UTC (Coordinated Universal Time).
Creazione delle tabelle partizionate
Quando crei un sink per indirizzare i log a BigQuery, puoi utilizzare tabelle suddivise per data o tabelle partizionate. La selezione predefinita è una tabella partizionata per data:
Per istruzioni su come creare sink, consulta le seguenti risorse:
ConsoleGoogle Cloud : Esegui il routing dei log verso le destinazioni supportate.
Google Cloud CLI:
gcloud logging sinks create.
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 sui relativi tipi.
Si verifica una mancata corrispondenza dello schema 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_iddella voce di log iniziale è unstring, questa voce di log genera una tabella con un tipo di stringa per questo campo. Se in un secondo momento inizi a registrarejsonPayload.user_idcomearray, 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 di BigQuery.
La tabella di destinazione può accettare il nuovo campo se non causa 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 partizionate per data, il formato di denominazione è
export_errors_YYYYMMDD. Per le tabelle partizionate, il formato di denominazione è
export_errors. Per ulteriori informazioni, vedi Organizzazione delle tabelle.
Quando esegue il routing delle voci di log, Logging invia i messaggi in 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 scritte 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 viene superato il limite di colonne, 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, ma la voce di log 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 daLogEntry.timestamp: estratto daLogEntry.receiveTimestamp: estratto daLogEntry.severity: estratto daLogEntry.insertId: estratto daLogEntry.trace: estratto daLogEntry.resourceType: estratto daLogEntry.
La registrazione comunica le mancate corrispondenze dello schema al progettoGoogle Cloud che contiene il sink di routing nei seguenti modi:
- I proprietari del progetto ricevono un'email. I dettagli includono: Google Cloud ID progetto, 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 futuri mancati corrispondenze dei tipi 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 attuale. 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 istruzioni, vedi Gestire i sink.
Risoluzione dei problemi
Se i log sembrano mancare dalla destinazione del sink o se sospetti che il sink non stia instradando correttamente i log, consulta l'articolo Risolvere i problemi relativi all'instradamento dei log.
Prezzi
Cloud Logging non addebita costi per il routing dei log a una destinazione supportata, ma la destinazione potrebbe applicare costi.
Ad eccezione del bucket di log _Required,
Cloud Logging addebita lo streaming dei log nei bucket di log e
l'archiviazione per un periodo più lungo del periodo di conservazione predefinito del bucket di log.
Cloud Logging non addebita costi per la copia dei log, per la creazione di ambiti dei log o visualizzazioni di analisi o per le query emesse tramite le pagine Esplora log o Analisi dei log.
Per saperne di più, consulta i seguenti documenti:
- Le sezioni di Cloud Logging della pagina Prezzi di Google Cloud Observability.
Costi per il routing dei dati di log ad altri servizi: Google Cloud
- I costi di generazione dei log di flusso VPC si applicano quando invii ed escludi i log di flusso Virtual Private Cloud da Cloud Logging.