Ajude a moldar o futuro das operações de software e manifeste-se na pesquisa de estado de DevOps 1202.

Esquema do BigQuery para registros

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

Visão geral

Direcione as entradas de registro do Cloud Logging para o BigQuery usando coletores. Ao criar um coletor, você define um conjunto de dados do BigQuery como destino. O Logging envia entradas de registro que correspondem às regras do coletor para tabelas particionadas criadas para você nesse conjunto de dados do BigQuery.

Os esquemas de tabela do BigQuery para dados recebidos do Cloud Logging são baseados na estrutura do tipo LogEntry e no conteúdo dos payloads de entrada de registro. O Cloud Logging também aplica regras para reduzir os nomes de campo do esquema do BigQuery para registros de auditoria e para determinados campos de payload estruturados.

Os coletores do Logging transmitem dados de registro para o BigQuery em lotes pequenos, o que permite consultar dados sem executar um job de carregamento. Para mais detalhes, consulte Como fazer streaming de dados para o 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 dos campos de entrada de registro não podem ter mais de 128 caracteres.

  • Nomes de campos de entrada de registro podem ser compostos apenas por caracteres alfanuméricos. Todos os caracteres incompatíveis são removidos dos nomes de campo e substituídos por caracteres de sublinhado. Por exemplo, jsonPayload.foo%% seria transformado em jsonPayload.foo__.

    Os nomes de campos de entrada de registro precisam começar com um caractere alfanumérico, mesmo após a transformação; os sublinhados à esquerda 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 fornecida pelo usuário, os nomes de campos 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 em letras minúsculas, mas a nomenclatura é preservada.

    Para informações sobre payloads estruturados em que o especificador @type está presente, consulte os campos 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, você verá os nomes de campos especiais do esquema do BigQuery para entradas de registro com payloads que contêm o especificador @type. Isso inclui entradas de registro de auditoria encaminhadas para o BigQuery.

Os payloads em 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 um campo protoPayload de uma entrada de registro de auditoria pode ser mapeado no 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 de @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 do esquema de registro de auditoria nesta página.

Exemplo

Este exemplo mostra como os campos de payloads 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 regras de nomenclatura padrão do BigQuery, já que as regras de especificador de tipo não se aplicam a campos aninhados.

Assim, os seguintes nomes do BigQuery são definidos 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 nos registros de auditoria exportados

Se você não trabalhar 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 encaminhados 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 encaminhada para o BigQuery, como seria o campo tableInsertRequest? Antes de encurtá-lo, o nome de 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

Tabelas particionadas

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

Ao rotear registros para um conjunto de dados do BigQuery, o Logging cria tabelas para manter as entradas de registro. Há dois tipos de tabelas pelas quais o Logging organiza os dados que ele encaminha: 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 são fragmentadas nas 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 rotear 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 usando o Console do Google Cloud, consulte Como exportar com o Logs Explorer.

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

Incompatibilidades no esquema

A primeira entrada de registro recebida pelo BigQuery 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 para incluir novas colunas. No entanto, se o tipo de campo for alterado para um campo atual, as entradas de registro mais recentes que não corresponderem ao esquema serão descartadas.

Por exemplo, se o campo jsonPayload.user_id da entrada de registro inicial for string, essa entrada de registro gerará uma tabela com um tipo de string para esse campo. Se você iniciar o registro de 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 ao projeto do 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" exibe um erro, Stackdriver Config error. Os detalhes incluem o nome e o destino do coletor e um link para 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 roteadas 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 ver instruções, consulte Como atualizar coletores.

Como ver os registros

Para ver os registros e o esquema do BigQuery, selecione uma tabela na IU da Web do BigQuery que tenha recebido entradas de registro do Cloud Logging.