Neste documento, explicamos como encontrar entradas de registro roteadas do Cloud Logging para tabelas do BigQuery. Os coletores de registro transmitem os dados de geração de registros para o BigQuery em pequenos lotes, o que permite consultar dados sem executar um job de carregamento. Para ajudar você a criar consultas e entender o formato da sua tabela do BigQuery, este documento também descreve o esquema do BigQuery para logs roteados.
O Cloud Logging usa a API de streaming legada para transmitir as entradas de registro para o BigQuery. Normalmente, as entradas de registro ficam visíveis no BigQuery em um minuto. No entanto, quando uma nova tabela é criada, pode levar vários minutos até que as primeiras entradas de registro estejam disponíveis.
Antes de começar
Para uma discussão conceitual sobre coletores, consulte Visão geral dos modelos de roteamento e armazenamento: coletores.
Para instruções sobre como rotear seus registros, consulte Rotear registros para destinos compatíveis.
Para saber como os campos de entrada de registro roteados são nomeados, consulte o Esquema do BigQuery para registros roteados.
Ver registros
Para conferir os registros roteados para o BigQuery, faça o seguinte:
-
No console do Google Cloud, acesse a página do BigQuery:
Também é possível encontrar essa página usando a barra de pesquisa.
No painel Explorer, expanda o projeto e selecione um conjunto de dados.
Você encontra as entradas de registro na guia Detalhes. Também é possível consultar a tabela para retornar os dados.
Amostras de consultas
Para informações sobre a sintaxe de consulta do BigQuery, consulte a Referência de consulta. São especialmente úteis as funções de caractere curinga de tabela, que permitem fazer consultas em várias tabelas, e o operador de nivelamento, que exibe dados de campos repetidos.
Exemplo de consulta do Compute Engine
A seguinte consulta do BigQuery recupera entradas de registro de vários dias e tipos:
A consulta pesquisa os últimos três dias dos registros
syslog
eapache-access
. Ela foi feita em 23 de fevereiro de 2020 e abrange todas as entradas de registro recebidas entre os dias 21 e 22, além daquelas recebidas no dia 23, até o momento em que a consulta foi emitida.A consulta recupera resultados de uma única instância do 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;
Veja alguns exemplos de linhas de saída:
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 "-" "-"
Exemplo de consulta do App Engine
A seguinte consulta do BigQuery recupera solicitações do App Engine que não foram bem-sucedidas no último mês:
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
Veja alguns dos resultados:
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
Esquema do BigQuery para registros roteados
Os esquemas de tabela do BigQuery para registros encaminhados são baseados na
estrutura do tipo LogEntry
e no conteúdo dos payloads
de registro. O Cloud Logging também aplica regras para encurtar
nomes de campo do esquema do BigQuery para registros de auditoria e
para determinados campos de payload estruturados. Para conferir o esquema da tabela,
selecione uma tabela com entradas de registro encaminhadas na
interface do BigQuery.
Convenções de nomenclatura de campo
Há algumas convenções de nomenclatura que se aplicam aos campos de entrada de registro ao enviar registros para o BigQuery:
Os nomes de campos de entrada de registro não podem ter mais de 128 caracteres.
Os nomes dos campos de entrada de registro podem ser compostos apenas por caracteres alfanuméricos. Todos os caracteres incompatíveis são removidos dos nomes dos campos e substituídos por caracteres sublinhados. Por exemplo,
jsonPayload.foo%%
seria transformado emjsonPayload.foo__
.Os nomes dos campos de entrada de registro precisam começar com um caractere alfanumérico, mesmo após a transformação. Os sublinhados iniciais são removidos.
Para os campos de entrada de registro que fazem parte do tipo
LogEntry
, os nomes de campo correspondentes do BigQuery são iguais a eles.Para qualquer campo de entrada de registro fornecido pelo usuário, os nomes de campo correspondentes do BigQuery são normalizados para letras minúsculas, mas a nomenclatura é preservada.
Para campos em payloads estruturados, contanto que o especificador
@type
não esteja presente, os nomes de campo correspondentes do BigQuery são normalizados para letras minúsculas, mas a nomenclatura é preservada.Para informações sobre payloads estruturados em que o especificador
@type
está presente, consulte Campos de payload com@type
nesta página.
Os exemplos a seguir mostram como essas convenções de nomenclatura são aplicadas:
Campo de entrada de registro | Mapeamento do tipo LogEntry |
Nome do campo do 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 |
Campos de payload com @type
Nesta seção, discutimos nomes de campo especiais de esquema do BigQuery para entradas de registro com payloads que contêm o especificador @type
. Isso inclui entradas de registro de auditoria roteadas para o BigQuery.
Os payloads nas entradas de registro podem conter dados estruturados. Qualquer um desses campos pode incluir um especificador de tipo opcional no seguinte formato:
@type: type.googleapis.com/[TYPE]
As regras de nomenclatura explicam por que o campo protoPayload
de uma entrada de registro de auditoria pode ser mapeado para o campo do esquema do BigQuery protopayload_auditlog
.
Regras de nomenclatura para @type
Os campos estruturados que têm especificadores de tipo recebem nomes de campo do BigQuery com [TYPE]
anexado a eles. O valor de [TYPE]
pode ser qualquer string.
As regras de nomenclatura para @type
se aplicam somente ao nível superior de jsonPayload
ou protoPayload
. Campos aninhados são ignorados. Ao tratar campos de payload estruturados de nível superior, o Logging remove o prefixo type.googleapis.com
.
Por exemplo, na tabela a seguir você verá o mapeamento de campos de payload estruturados em nível superior em nomes de campo do BigQuery:
Payload | @type do payload | Campo de payload | Nome do campo do BigQuery |
---|---|---|---|
jsonPayload |
(nenhum) | statusCode |
jsonPayload.statusCode |
jsonPayload |
type.googleapis.com/abc.Xyz |
statusCode |
jsonpayload_abc_xyz.statuscode |
protoPayload |
(nenhum) | statusCode |
protoPayload.statuscode |
protoPayload |
type.googleapis.com/abc.Xyz |
statusCode |
protopayload_abc_xyz.statuscode |
Algumas exceções se aplicam às regras anteriores para campos com especificadores de tipo:
Nos registros de solicitação do App Engine, o nome do payload nos registros roteados para o BigQuery é
protoPayload
, embora o payload inclua um especificador de tipo.O Cloud Logging aplica algumas regras especiais para encurtar os nomes de campo do esquema do BigQuery para registros de auditoria. Isso é discutido na seção Campos de registros de auditoria nesta página.
Exemplo
Este exemplo mostra como os campos de payload estruturados são nomeados e usados quando recebidos pelo BigQuery.
Suponha que o payload de uma entrada de registro esteja estruturado assim:
jsonPayload: {
@type: "type.googleapis.com/google.cloud.v1.CustomType"
name_a: {
sub_a: "A value"
}
name_b: {
sub_b: 22
}
}
O mapeamento nos campos do BigQuery será o seguinte:
O campo estruturado de nível superior
jsonPayload
contém um especificador@type
. O nome do BigQuery éjsonpayload_v1_customtype
.Os campos aninhados são tratados com as regras de nomenclatura padrão do BigQuery, já que as regras de especificador de tipo não se aplicam a campos aninhados.
Assim, são definidos os seguintes nomes do BigQuery para o payload da entrada de registro:
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
Campos de registros de auditoria
Se você não estiver trabalhando com registros de auditoria que foram roteados para o BigQuery, ignore esta seção.
Os campos de payload protoPayload.request
, protoPayload.response
e protoPayload.metadata
do registro de auditoria têm especificadores @type
, mas são tratados como dados JSON. Ou seja, seus nomes de esquema do BigQuery são os nomes dos campos com Json
anexados a eles, contendo dados de string no formato JSON.
Os dois conjuntos de nomes de campo do payload do registro de auditoria estão listados na tabela a seguir:
Campo de entrada de registro | Nome do campo do BigQuery |
---|---|
protoPayload |
protopayload_auditlog |
protopayload.metadata |
protopayload_auditlog.metadataJson |
protoPayload.serviceData |
protopayload_auditlog.servicedata_v1_bigquery Exemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest |
protoPayload.request |
protopayload_auditlog.requestJson |
protoPayload.response |
protopayload_auditlog.responseJson |
Observe que a convenção de nomenclatura serviceData
é específica para registros de auditoria gerados pelo BigQuery e roteados do Cloud Logging para o BigQuery. Essas entradas de registro de auditoria contêm um campo serviceData
que tem um especificador @type de type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
.
Exemplo
Uma entrada de registro de auditoria gerada pelo BigQuery tem um campo com o seguinte nome:
protoPayload.serviceData.tableInsertRequest
Se essa entrada de registro fosse roteada para o BigQuery, como seria o campo tableInsertRequest
? Antes do encurtamento do nome, o nome do campo correspondente no BigQuery seria:
protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest
Depois de encurtá-lo, o mesmo campo aparece nas tabelas do BigQuery assim:
protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
Organização da tabela
Nesta seção, você tem uma visão geral das tabelas particionadas para registros roteados para o BigQuery.
Quando você encaminha registros para um conjunto de dados do BigQuery, o Logging cria tabelas para armazenar as entradas de registro. A primeira entrada de registro recebida pelo BigQuery determina o esquema da tabela de destino do BigQuery. O BigQuery cria uma tabela com colunas baseadas nos campos da primeira entrada de registro e seus tipos. As entradas de registro subsequentes podem causar uma incompatibilidade de esquema. Para informações sobre quando elas ocorrem e como são processadas, consulte Incompatibilidades de esquema.
Há dois tipos de tabelas pelas quais o Logging organiza os dados que roteia: tabelas fragmentadas por datas e tabelas particionadas. Os dois tipos de tabela particionam os dados de registros com base nos campos timestamp
de entradas de registro. No entanto, há duas diferenças principais entre os
tipos de tabela, da seguinte maneira:
Desempenho: uma tabela particionada divide uma tabela grande em partições menores para melhorar o desempenho da consulta e, assim, controlar melhor os custos do BigQuery, reduzindo o número de bytes lidos por uma consulta.
Nomenclatura de tabela: os tipos de tabela usam diferentes convenções de nomenclatura, conforme discutido na seção abaixo.
Organização da tabela
As entradas de registro são fragmentadas em tabelas do BigQuery com organização e nomes baseados nos nomes de registro e carimbos de data/hora das entradas.
Os nomes das tabelas são sufixados com a data do calendário do carimbo de data/hora UTC da entrada de registro, usando o formato básico ISO 8601 (AAAAMMDD).
Na tabela a seguir, você verá exemplos de como nomes de registro e amostras de carimbos de data/hora são mapeados para nomes de tabela no BigQuery:
Nome do registro | Entrada de registro timestamp 1 |
Nome da tabela do BigQuery (organizado por data) |
Nome da tabela do BigQuery (particionado) |
---|---|---|---|
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 Os carimbos de data/hora da entrada de registro são mostrados em UTC (Tempo Universal Coordenado).
Como criar tabelas particionadas
Ao criar um coletor para rotear seus registros para o BigQuery, é possível usar tabelas fragmentadas por datas ou tabelas particionadas. A seleção padrão é uma tabela fragmentada por datas:
Para instruções sobre como criar sinks, consulte os seguintes recursos:
Console do Google Cloud: Encaminhar registros para destinos compatíveis.
Google Cloud CLI:
gcloud logging sinks create
.
Incompatibilidades no esquema
A primeira entrada de registro recebida pelo BigQuery determina o esquema da tabela de destino do BigQuery. O BigQuery cria uma tabela com colunas baseadas nos campos da primeira entrada de registro e seus tipos.
Uma incompatibilidade de esquema ocorre quando as entradas de registro são gravadas na tabela de destino e um dos seguintes erros ocorre:
Uma entrada de registro posterior altera o tipo de campo de um campo existente na tabela.
Por exemplo, se o campo
jsonPayload.user_id
da entrada de registro inicial forstring
, essa entrada de registro gerará uma tabela com um tipo de string para esse campo. Se, posteriormente, você começar a registrarjsonPayload.user_id
como umarray
, isso causará uma incompatibilidade de esquema.Uma nova entrada de registro contém um campo que não está no esquema atual e a inserção desse campo na tabela de destino excederia o limite de colunas do BigQuery.
A tabela de destino pode aceitar o novo campo se ele não causar o limite da coluna.
Quando o BigQuery identifica uma incompatibilidade de esquema, ele cria uma tabela no conjunto de dados correspondente para armazenar as informações de erro. O tipo de uma tabela determina o nome dela. Para tabelas fragmentadas por data, o formato de nomenclatura é
export_errors_YYYYMMDD
. Para tabelas particionadas, o formato de nomenclatura é
export_errors
. Para mais informações, consulte
Organização da tabela.
Ao encaminhar entradas de registro, o Logging envia mensagens como um lote para o BigQuery. O BigQuery usa as seguintes regras para determinar em qual tabela as entradas de registro no lote atual de mensagens são gravadas:
Quando ocorre uma alteração de tipo de campo, apenas as entradas de registro que causaram uma incompatibilidade de esquema são gravadas na tabela de erros. As entradas de registro no lote atual de mensagens que não causam uma incompatibilidade de esquema são gravadas na tabela de destino original.
Quando o limite de colunas é excedido, todas as entradas de registro no lote atual de mensagens são gravadas na tabela de erros.
Esquema da tabela de erro
A tabela de erros contém dados de LogEntry
e informações
sobre a incompatibilidade:
logEntry
: contém a entrada de registro completa. No entanto, a entrada de registro é convertida de JSON em uma string.schemaErrorDetail
: contém a mensagem de erro completa retornada pelo BigQuery.sink
: contém o caminho completo do recurso para o coletor de registros.logName
: extraído doLogEntry
.timestamp
: extraído doLogEntry
.receiveTimestamp
: extraído doLogEntry
.severity
: extraído doLogEntry
.insertId
: extraído doLogEntry
.trace
: extraído doLogEntry
.resourceType
: extraído doLogEntry
.
O Logging comunica incompatibilidades de esquema ao projeto do Google Cloud que contém o coletor de roteamento das seguintes maneiras:
- Os proprietários do projeto recebem um e-mail. Os detalhes incluem: ID do projeto do Google Cloud, nome do coletor e destino.
- A página "Atividade" do console do Google Cloud mostra um erro,
Stackdriver Config error
. Os detalhes incluem o nome do coletor e o destino e um link com um exemplo de uma entrada de registro que causou o erro.
Evitar incompatibilidades futuras de tipo de campo
Para corrigir inconsistências de tipo de campo em entradas de registro posteriores, corrija o tipo de campo para que ele corresponda ao esquema atual. Para saber como corrigir um tipo de campo, consulte Alterar o tipo de dados de uma coluna.
Às vezes, o tipo de campo não pode ser alterado. Por exemplo, não é possível mudar um tipo de campo para registros gerados automaticamente pelos serviços do Google Cloud. Para evitar incompatibilidades de esquema quando não é possível mudar um tipo de campo, renomeie a tabela ou mude os parâmetros do coletor para que o Logging recrie a tabela em um conjunto de dados diferente. Para instruções, consulte Gerenciar coletores.
Solução de problemas
Se os registros parecerem estar ausentes no destino do coletor ou se você suspeitar que o coletor não está roteando registros corretamente, consulte Resolver problemas de roteamento de registros.
Preços
O Cloud Logging não cobra pelo encaminhamento de registros para um destino compatível. No entanto, o destino pode aplicar cobranças.
Com exceção do bucket de registros _Required
,
o Cloud Logging cobra para transmitir registros em buckets de registro e
para armazenamento por mais tempo do que o período de armazenamento padrão do bucket de registros.
O Cloud Logging não cobra pela cópia de registros, pela definição de escopos de registro ou por consultas emitidas nas páginas Explorer de registros ou Análise de dados de registros.
Para mais informações, consulte estes documentos:
- Resumo dos preços do Cloud Logging
Custos de destino:
- Cobranças de geração de registros de fluxo da VPC são aplicadas quando você envia e exclui seus registros de fluxo da nuvem privada virtual do Cloud Logging.