Veja os registos encaminhados para o BigQuery

Este documento explica como pode encontrar entradas de registo que encaminhou do Cloud Logging para tabelas do BigQuery. Os destinos de registo transmitem dados de registo para o BigQuery em pequenos lotes, o que lhe permite consultar dados sem executar uma tarefa de carregamento. Para ajudar a criar consultas e compreender o formato da sua tabela do BigQuery, este documento também descreve o esquema do BigQuery para registos encaminhados.

O Cloud Logging usa a API Legacy Streaming para fazer stream das suas entradas de registo para o BigQuery. Normalmente, as entradas de registo ficam visíveis no BigQuery no prazo de um minuto. No entanto, quando é criada uma nova tabela, podem demorar vários minutos até que as primeiras entradas do registo estejam disponíveis.

Antes de começar

Para uma discussão conceptual sobre os destinos, consulte o artigo Vista geral dos modelos de encaminhamento e armazenamento: destinos.

Para ver instruções sobre como encaminhar os registos, consulte o artigo Encaminhe registos para destinos suportados.

Para saber como os campos de entrada de registo encaminhados são denominados, consulte o artigo Esquema do BigQuery para registos encaminhados.

Ver registos

Para ver os registos encaminhados para o BigQuery, faça o seguinte:

  1. Na Google Cloud consola, aceda à página BigQuery:

    Aceda ao BigQuery Studio

    Também pode encontrar esta página através da barra de pesquisa.

  2. No painel Explorador, expanda o projeto e selecione um conjunto de dados.

    As entradas do registo estão visíveis no separador Detalhes ou pode consultar a tabela para devolver os seus dados.

Consultas de exemplo

Para informações sobre a sintaxe de consultas do BigQuery, consulte o artigo Referência de consultas. As funções de caráter universal da tabela são particularmente úteis, pois permitem consultar várias tabelas, e o operador de nivelamento, que permite apresentar dados de campos repetidos.

Exemplo de consulta do Compute Engine

A consulta do BigQuery seguinte obtém entradas de registo de vários dias e vários tipos de registo:

  • A consulta pesquisa os últimos três dias dos registos syslog e apache-access. A consulta foi feita a 23-02-2020 e abrange todas as entradas de registo recebidas a 21-02 e 22-02, além das entradas de registo recebidas a 23-02 até ao momento em que a consulta foi emitida.

  • A consulta obtém resultados para 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;

Seguem-se algumas linhas de saída de exemplo:

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 obtém pedidos do App Engine sem êxito do ú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

Seguem-se 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 registos encaminhados

Os esquemas de tabelas do BigQuery para registos encaminhados baseiam-se na estrutura do tipo LogEntry e nos conteúdos dos payloads dos registos. O Cloud Logging também aplica regras para abreviar os nomes dos campos do esquema do BigQuery para registos de auditoria e para determinados campos de payload estruturados. Pode ver o esquema da tabela selecionando uma tabela com entradas de registo encaminhadas na interface do BigQuery.

Convenções de nomenclatura de campos

Existem algumas convenções de nomenclatura que se aplicam aos campos de entradas de registo quando envia registos para o BigQuery:

  • Os nomes dos campos de entradas de registo não podem exceder 128 carateres.

  • Os nomes dos campos de entradas de registo só podem ser compostos por carateres alfanuméricos. Todos os carateres não suportados são removidos dos nomes dos campos e substituídos por carateres de sublinhado. Por exemplo, jsonPayload.foo%% seria transformado em jsonPayload.foo__.

    Os nomes dos campos de entradas de registo têm de começar por um caráter alfanumérico, mesmo após a transformação. Os carateres de sublinhado iniciais são removidos.

  • Para os campos de entrada do registo que fazem parte do tipo LogEntry, os nomes dos campos do BigQuery correspondentes são exatamente iguais aos campos de entrada do registo.

  • Para todos os campos de entrada de registo fornecidos pelo utilizador, os nomes dos campos do BigQuery correspondentes são normalizados para letras minúsculas, mas a nomenclatura é preservada de outra forma.

  • Para campos em payloads estruturados, desde que o especificador @type não esteja presente, os nomes dos campos do BigQuery correspondentes são normalizados para letras minúsculas, mas a nomenclatura é preservada de outra forma.

    Para informações sobre payloads estruturados onde o especificador @type está presente, consulte Campos de payload com @type nesta página.

Os exemplos seguintes mostram como estas convenções de nomenclatura são aplicadas:

Campo de entrada do registo LogEntry mapeamento de tipos 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

Esta secção aborda nomes de campos de esquema do BigQuery especiais para entradas de registo cujos payloads contêm o especificador @type. Para obter informações sobre as regras de nomenclatura dos registos de auditoria, consulte a secção Campos dos registos de auditoria nesta página.

As cargas úteis nas entradas de registo podem conter dados estruturados. Qualquer campo estruturado pode incluir um especificador de tipo opcional no seguinte formato:

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

Regras de nomenclatura para @type

Os campos estruturados que têm especificadores de tipo recebem habitualmente nomes de campos do BigQuery com [TYPE] anexado ao nome do campo. O valor de [TYPE] pode ser qualquer string.

O tipo de entrada de registo determina as regras de nomenclatura para campos com o especificador @type. Para entradas de registo que não sejam registos de auditoria, estas regras aplicam-se apenas ao nível superior de jsonPayload ou protoPayload; os campos aninhados são ignorados. Para obter informações sobre as regras de nomenclatura dos registos de auditoria, consulte a secção Campos dos registos de auditoria nesta página.

Quando processa campos de payload estruturados de nível superior, o Logging remove o prefixo type.googleapis.com.

Por exemplo, a tabela seguinte mostra o mapeamento dos campos de payload estruturados de nível superior para os nomes dos campos do BigQuery para entradas de registo que não são registos de auditoria:

Payload Payload @type 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

Aplicam-se algumas exceções às regras anteriores para campos com especificadores de tipo:

  • Nos registos de pedidos do App Engine, o nome do payload nos registos encaminhados para o BigQuery é protoPayload, mesmo que o payload inclua um especificador de tipo.

  • A tabela anterior não se aplica aos registos de auditoria. O Cloud Logging aplica algumas regras especiais para abreviar os nomes dos campos do esquema do BigQuery para registos de auditoria. Isto é abordado na secção Campos de registos de auditoria desta página.

Exemplo

Este exemplo mostra como os campos de payload estruturados são denominados e usados quando recebidos pelo BigQuery.

Suponha que a carga útil de uma entrada de registo está estruturada da seguinte forma:

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

O mapeamento para os campos do BigQuery é 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, uma vez que as regras de especificação de tipo não se aplicam a campos aninhados.

Assim, os seguintes nomes do BigQuery são definidos para a carga útil da entrada de registo:

  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 dos registos de auditoria

Se não estiver a trabalhar com registos de auditoria que foram encaminhados para o BigQuery, pode ignorar esta secção.

Esta secção aplica-se a campos estruturados que podem incluir um especificador de tipo opcional no seguinte formato:

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

Modificações do nome do campo

Quando um registo de auditoria contém uma carga útil com um especificador @type, o Cloud Logging pode modificar o valor [TYPE] anexado ao especificador antes de o nome do campo do BigQuery ser gerado. Estas modificações resultam em nomes de campos do BigQuery mais curtos.

O registo remove sempre o prefixo type.googleapis.com do valor [TYPE]. A tabela seguinte descreve quando o registo encurta os nomes dos campos:

Valor [TYPE] original Valor de [TYPE] modificado
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

Por exemplo, suponha que uma entrada do registo de auditoria contém o seguinte conteúdo:

{
  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"
      }
    }
  }
}

Os nomes dos campos do BigQuery são derivados da entrada de registo modificada, que é a seguinte:

{
  logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
  protoPayload: {
    @type: "AuditLog"
    serviceData: {
      @type: "legacy.appengine"
      eventData: {
        timezone: "UTC"
      }
    }
  }
}

Regras de nomenclatura para @type

Nos registos de auditoria, existem vários campos que podem ter um especificador @type:

  • protoPayload
  • protoPayload.serviceData
  • protoPayload.request
  • protoPayload.response
  • protoPayload.metadata

Os campos request, response e metadata são tratados como dados JSON. Ou seja, os nomes dos esquemas do BigQuery são os nomes dos campos com Json anexado e contêm dados de strings no formato JSON.

Os dois conjuntos de nomes de campos de payload do registo de auditoria estão listados na tabela seguinte:

Campo de entrada do registo Nome do campo do 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
Exemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.status.code protoPayload_auditlog.statuscode

Tenha em atenção que a convenção de nomenclatura serviceData é específica dos registos de auditoria gerados pelo BigQuery e que são, em seguida, encaminhados do Cloud Logging para o BigQuery. Essas entradas do registo de auditoria contêm um campo serviceData com um especificador @type de type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

Exemplo

Uma entrada do registo de auditoria gerada pelo BigQuery tem um campo com o seguinte nome:

protoPayload.serviceData.tableInsertRequest

Se esta entrada do registo fosse encaminhada para o BigQuery, como é que o campo tableInsertRequest seria referenciado? Antes da abreviatura do nome, o nome do campo correspondente no BigQuery seria:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Após a abreviatura do nome, o mesmo campo é referenciado nas tabelas do BigQuery da seguinte forma:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Organização da tabela

Esta secção oferece uma vista geral das tabelas particionadas para registos encaminhados para o BigQuery.

Quando encaminha registos para um conjunto de dados do BigQuery, o Logging cria tabelas para conter as entradas de registo. A primeira entrada de registo recebida pelo BigQuery determina o esquema da tabela de destino do BigQuery. O BigQuery cria uma tabela cujas colunas se baseiam nos campos da primeira entrada do registo e nos respetivos tipos. As entradas de registo subsequentes podem causar uma incompatibilidade de esquema. Para ver informações sobre quando ocorrem e como são processadas, consulte o artigo Inconsistências no esquema.

Existem dois tipos de tabelas através dos quais o Logging organiza os dados que encaminha: tabelas divididas por datas e tabelas particionadas. Ambos os tipos de tabelas dividem os dados dos registos com base nos campos timestampdas entradas de registo. No entanto, existem duas diferenças principais entre os tipos de tabelas, como se segue:

  • Desempenho: uma tabela particionada divide uma tabela grande em partições mais pequenas, para que possa melhorar o desempenho das consultas e, assim, controlar melhor os custos do BigQuery reduzindo o número de bytes lidos por uma consulta.

  • Nomenclatura das tabelas: os tipos de tabelas usam convenções de nomenclatura diferentes, conforme descrito na secção seguinte.

Organização da tabela

As entradas de registo são divididas em tabelas do BigQuery cuja organização e nomes se baseiam nos nomes e nas datas/horas dos registos das entradas.

Os nomes das tabelas têm o sufixo da data do calendário da data/hora UTC da entrada do registo, usando o formato básico ISO 8601 (AAAAMMDD).

A tabela seguinte mostra exemplos de como os nomes dos registos e as datas/horas de exemplo são mapeados para nomes de tabelas no BigQuery:

Nome de registo Entrada do registo timestamp1 Nome da tabela do BigQuery
(dividida por datas)		 Nome da tabela do BigQuery
(particionada)
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 As datas/horas das entradas do registo são expressas em UTC (Tempo Universal Coordenado).

Criar tabelas particionadas

Quando cria um destino para encaminhar os seus registos para o BigQuery, pode usar tabelas divididas por datas ou tabelas particionadas. A seleção predefinida é uma tabela dividida por datas:

Para instruções sobre como criar destinos, consulte os seguintes recursos:

Discrepâncias no esquema

A primeira entrada de registo recebida pelo BigQuery determina o esquema para a tabela de destino do BigQuery. O BigQuery cria uma tabela cujas colunas se baseiam nos campos da primeira entrada do registo e nos respetivos tipos.

Uma incompatibilidade de esquema ocorre quando as entradas do registo são escritas na tabela de destino e ocorre um dos seguintes erros:

  • Uma entrada de registo posterior altera o tipo de campo de um campo existente na tabela.

    Por exemplo, se o campo jsonPayload.user_id da entrada do registo inicial for a string, essa entrada do registo gera uma tabela com um tipo de string para esse campo. Se, mais tarde, começar a registar jsonPayload.user_id como array, isso causa uma incompatibilidade de esquema.

  • Uma nova entrada de registo 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 não fizer com que o limite de colunas seja excedido.

Quando o BigQuery identifica uma incompatibilidade de esquema, cria uma tabela no conjunto de dados correspondente para armazenar as informações de erro. O tipo de uma tabela determina o nome da tabela. Para tabelas divididas por datas, o formato de nomenclatura é export_errors_YYYYMMDD. Para tabelas particionadas, o formato de nomenclatura é export_errors. Para mais informações, consulte o artigo Organização de tabelas.

Quando encaminha entradas do registo, o Logging envia mensagens como um lote para o BigQuery. O BigQuery usa as seguintes regras para determinar em que tabela as entradas de registo no lote atual de mensagens são escritas:

  • Quando ocorre uma alteração do tipo de campo, apenas as entradas de registo que causaram uma incompatibilidade de esquema são escritas na tabela de erros. As entradas de registo no lote atual de mensagens que não causam uma incompatibilidade de esquemas são escritas na tabela de destino original.

  • Quando o limite de colunas é excedido, todas as entradas do registo no lote atual de mensagens são escritas na tabela de erros.

Esquema da tabela de erros

A tabela de erros contém dados do elemento LogEntry e informações sobre a falta de correspondência:

  • logEntry: contém a entrada de registo completa. No entanto, a entrada de registo é convertida de JSON num formato de string.
  • schemaErrorDetail: contém a mensagem de erro completa devolvida pelo BigQuery.
  • sink: contém o caminho de recurso completo do destino do registo.
  • logName: extraído do LogEntry.
  • timestamp: extraído do LogEntry.
  • receiveTimestamp: extraído do LogEntry.
  • severity: extraído do LogEntry.
  • insertId: extraído do LogEntry.
  • trace: extraído do LogEntry.
  • resourceType: extraído do LogEntry.

O registo comunica as incompatibilidades de esquemas ao projetoGoogle Cloud que contém o destino de encaminhamento das seguintes formas:

  • Os proprietários do projeto recebem um email. Os detalhes incluem: Google Cloud ID do projeto, nome do destino e destino.
  • A página Atividade da Google Cloud consola apresenta um erroStackdriver Config error. Os detalhes incluem o nome e o destino do coletor, bem como um link para um exemplo de uma entrada de registo que causou o erro.

Evite futuras incompatibilidades de tipos de campos

Para corrigir as incompatibilidades de tipo de campo para entradas de registo posteriores, corrija o tipo de campo para que corresponda ao esquema atual. Para obter informações sobre como corrigir um tipo de campo, consulte o artigo Altere o tipo de dados de uma coluna.

Por vezes, não é possível alterar o tipo de campo. Por exemplo, não pode alterar um tipo de campo para registos gerados automaticamente pelos serviços Google Cloud. Para evitar incompatibilidades de esquemas quando não pode alterar um tipo de campo, mude o nome da tabela ou altere os parâmetros do destino, para que o Logging recrie a tabela num conjunto de dados diferente. Para ver instruções, consulte o artigo Faça a gestão dos destinos.

Resolução de problemas

Se os registos parecerem estar em falta no destino do seu coletor ou suspeitar que o coletor não está a encaminhar corretamente os registos, consulte o artigo Resolva problemas de encaminhamento de registos.

Preços

O Cloud Logging não cobra o encaminhamento de registos para um destino suportado. No entanto, o destino pode aplicar cobranças. Com exceção do contentor de registos _Required, o Cloud Logging cobra taxas para transmitir registos para contentores de registos e para armazenamento durante um período superior ao período de retenção predefinido do contentor de registos.

O Cloud Logging não cobra pela cópia de registos, pela criação de âmbitos de registo ou vistas de estatísticas, nem por consultas emitidas através das páginas do Explorador de registos ou Log Analytics.

Para mais informações, consulte os seguintes documentos: