Esquema do BigQuery de registros exportados

Nesta página, detalhamos a formatação e as regras que se aplicam ao exportar entradas de registro do Cloud Logging para o BigQuery.

O Logging faz o streaming de dados da geração de registros para o BigQuery, um registro por vez, em vez de usar jobs de carregamento. Essa abordagem permite consultar dados no BigQuery sem o atraso da execução de um job de carregamento. Para mais detalhes, consulte Como fazer streaming de dados para o BigQuery.

Os esquemas de tabela do BigQuery para registros exportados são baseados na estrutura do tipo LogEntry e no conteúdo dos payloads de registro. O Cloud Logging também aplica algumas regras especiais para encurtar os nomes de campo do esquema do BigQuery para registros de auditoria. Veja a tabela de esquema ao selecionar uma tabela com as entradas de registro exportadas na IU da Web do BigQuery.

Convenções de nomenclatura de campo

Existem algumas convenções de nomenclatura que se aplicam aos campos de entrada de registro:

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 fornecido pelo usuário, a capitalização é normalizada em letras minúsculas, mas a nomenclatura é preservada.
- Para campos em payloads estruturados, contanto que o especificador @type não esteja presente, a capitalização é normalizada em letras minúsculas, mas a nomenclatura é preservada.
  
  Para informações sobre payloads estruturados em que o especificador @type está presente, acesse os campos Payload com @type.

Nos exemplos a seguir, você verá 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`

O mapeamento de campos de payload estruturados para nomes de campo do BigQuery é mais complicado quando o campo estruturado contém um especificador @type. Você verá isso na seção a seguir.

Campos de payload com @type

Nesta seção, você verá os nomes de campos especiais do esquema do BigQuery para entradas de registro com payloads que contêm especificadores de tipo (campos @type). Isso inclui as entradas de registro de auditoria exportadas realizadas no BigQuery. Por exemplo, nesta seção você verá por que um campo protoPayload de uma entrada de registro de auditoria pode ser mapeado no campo do esquema do BigQuery protopayload_auditlog.

Regras de nomenclatura do esquema

Os payloads nas entradas de registro podem conter dados estruturados, que podem ter campos estruturados e aninhados. Qualquer um desses campos pode incluir um especificador de tipo opcional no seguinte formato:

@type: type.googleapis.com/[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.

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`

Se jsonPayload ou protoPayload tiver outros campos estruturados, esses campos internos serão mapeados da seguinte maneira:

Se o campo estruturado aninhado não tiver um especificador @type, seu nome de campo do BigQuery será igual ao nome do campo original, exceto se estiver normalizado para letras minúsculas.
Se o campo estruturado aninhado tiver um especificador @type, seu nome de campo BigQuery terá [TYPE] (reescrito) anexado ao nome do campo e será normalizado em letras minúsculas.

Há algumas exceções às regras anteriores para campos com especificadores de tipo:

Nos registros de solicitação do App Engine, o nome do payload nos registros exportados para o BigQuery é protoPayload, embora o payload tenha 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 do esquema de registro de auditoria exportados nesta página.

Exemplo

Veja como os campos de payloads estruturados são nomeados e utilizados quando você os exporta para o BigQuery.

Suponha que o payload de uma entrada de registro esteja estruturado assim:

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

O mapeamento nos campos do BigQuery será o seguinte:

Os campos jsonPayload e name_a são estruturados, mas não têm especificadores @type. Os nomes do BigQuery são jsonPayload e name_a, respectivamente.
Os campos sub_a e sub_b não estão estruturados, de modo que seus nomes do BigQuery são sub_a e sub_b, respectivamente.
O campo name_b tem um especificador @type, em que o [TYPE] é google.cloud.v1.SubType. Portanto, o nome do BigQuery é name_b_google_cloud_v1_subtype.

Em resumo, estes são os cinco nomes do payload de entrada de registro no BigQuery:

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

Campos nos registros de auditoria exportados

Se você não trabalhar com registros de auditoria que foram exportados 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 exportados 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 exportada para o BigQuery, como seria o campo tableInsertRequest? Antes de encurtá-lo, o nome de campo exportado correspondente 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

Tabelas particionadas

Nesta seção, você terá uma visão geral de tabelas particionadas para exportações de registros para o BigQuery.

Ao exportar registros para um conjunto de dados do BigQuery, o Logging cria tabelas para manter as entradas de registro exportadas. Há dois tipos de tabelas pelas quais o Logging organiza os dados que exporta: 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:

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 exportadas são fragmentadas em tabelas do BigQuery em que a organização e os nomes são baseados nos nomes de registro e nos carimbos de data/hora das entradas.

Os nomes das tabelas recebem o sufixo da data 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`	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`

Como criar tabelas particionadas

Ao criar um coletor para exportar seus registros para o BigQuery, é possível usar tabelas particionadas por datas ou tabelas particionadas. A seleção padrão é uma tabela fragmentada por datas.

Para instruções sobre como usar o Console do Google Cloud, acesse Como exportar com o Explorador de registros.

Para usar o SDK do Cloud, a interface de linha de comando, acesse gcloud logging sinks create.

Incompatibilidades no esquema

A primeira entrada de registro exportada determina o esquema da tabela de destino do BigQuery. A entrada de registro gera uma tabela em que as colunas são baseadas nos campos da entrada de registro e seus tipos. Se novos campos aparecerem em entradas de registro subsequentes, o esquema da tabela é atualizado. No entanto, se o tipo de valor for alterado para um campo atual, as entradas de registro mais recentes que não corresponderem ao esquema serão descartadas.

Por exemplo, se sua exportação inicial contém uma entrada de registro em que jsonPayload.user_id é um string, essa entrada de registro gera uma tabela com um tipo de string para esse campo. Se você começar a gerar registrar jsonPayload.user_id como array, essas entradas de registro não serão inseridas na tabela e serão perdidas.

O Logging comunica a perda de dados do projeto do Google Cloud que contém a exportação 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 da exportação.
A página "Atividade do Console do Google Cloud" exibe um erro, Stackdriver Config error. Os detalhes incluem o nome do coletor e o destino da exportação e um link com um exemplo de uma entrada de registro que causou o erro.
A métrica com base em registros do sistema exports/error_count informa o número total de entradas de registro que não foram exportadas devido a erros.

Para corrigir o problema em entradas de registro subsequentes, para que você não incorra em perda adicional de dados, corrija o tipo de campo para que ele corresponda ao esquema atual. Também é possível renomear a tabela ou alterar os parâmetros do coletor, para que o Logging recrie a tabela em um conjunto de dados diferente. Para instruções, acesse Como atualizar coletores.

Como ver os registros

Para visualizar seus registros usando a IU da Web do BigQuery, selecione uma tabela com suas entradas de registro exportadas.