Esquema do BigQuery de registros exportados

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 Stackdriver Logging também aplica algumas regras especiais para reduzir os nomes de campo do esquema do BigQuery para registros de auditoria. Você vê o esquema ao selecionar uma tabela com 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 para 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 para letras minúsculas, mas a nomenclatura é preservada.

      Para mais informações sobre payloads estruturados em que o especificador @type está presente, consulte Campos de payload com @type.

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

Quando o campo estruturado contém um especificador @type, o mapeamento dos campos de payload estruturado para nomes de campo do BigQuery é mais complicado. Falaremos sobre isso na seção abaixo.

Campos de payload com @type

Nesta seção serão abordados nomes de campos de esquemas especiais do BigQuery para entradas de registro cujo payload contenha especificadores de tipo (campos @type). Isso inclui as entradas de registro de auditoria exportadas realizadas no BigQuery. Por exemplo, nesta seção explicaremos por que o campo protoPayload de uma entrada de registro de auditoria pode ser mapeado para o campo do esquema do BigQuery protopayload_auditlog.

Atualmente, existem dois esquemas para entradas de registro de auditoria no BigQuery. Por dois esquemas, queremos dizer que certas informações do payload do registro de auditoria estão duplicadas em dois campos diferentes do BigQuery que contêm as informações em diferentes formatos: um nome de campo "estendido" mais antigo e um nome de campo "compacto" mais recente. Em 1º de março de 2019, o esquema mais antigo (nomes de campo) será removido. Para ver mais detalhes, consulte a seção Migração para o esquema atualizado abaixo.

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.

Por exemplo, a tabela a seguir mostra o mapeamento de campos de payload estruturados e de nível superior para os 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 e aninhado não tiver um especificador @type, o nome de campo do BigQuery será o mesmo que o original, mas normalizado com letras minúsculas.
  • Se o campo estruturado e aninhado tiver um especificador @type, o nome de campo do BigQuery terá [TYPE] (que será preenchido) anexado e normalizado com 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, mesmo que ele tenha um especificador de tipo. Saiba mais sobre isso no exemplo de consulta de registros do App Engine em Consultas.

  • O Stackdriver Logging aplica algumas regras especiais para reduzir os nomes de campo do esquema do BigQuery para registros de auditoria. Essa questão é abordada na seção Campos do esquema de registro de auditoria abaixo.

  • Os registros de auditoria exportados para o BigQuery são gravados em um formato compacto atualizado. Algumas informações do payload são temporariamente duplicadas em dois campos diferentes. Para mais detalhes, consulte Migração para o esquema atualizado.

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

Veja abaixo como será feito o mapeamento de campos do BigQuery:

  • Os campos jsonPayload e name_a estão estruturados, mas não têm especificadores @type. Os nomes deles no BigQuery são jsonPayload e name_a, respectivamente.

  • Os campos sub_a e sub_b não estão estruturados. Portanto, os nomes deles no BigQuery são sub_a e sub_b, respectivamente.

  • O campo name_b tem um especificador @type, e o [TYPE] dele é google.cloud.v1.SubType. Portanto, o nome dele no 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 do esquema de registro de auditoria exportados

Se você não trabalhar com registros de auditoria que foram exportados para o BigQuery, ignore esta seção.

Os campos mais antigos ("estendidos") do payload do registro de auditoria têm especificadores de tipo (campos @type) no Stackdriver. Os nomes de campo correspondentes do BigQuery são especialmente criados para evitar que sejam muito longos.

Os campos do payload do registro de auditoria mais recentes ("compactos"), protoPayload.request, protoPayload.response e protoPayload.metadata, têm especificadores @type, mas são tratados como dados JSON. Ou seja, o nome de esquema do BigQuery deles é o nome do campo com Json anexado, e eles contêm dados de string no formato JSON.

Os dois conjuntos de nomes de campo do payload do registro de auditoria são listados na tabela a seguir:

Campo de entrada de registro Nome de campo do BigQuery estendido (mais antigo) Nome de campo do BigQuery compacto (mais recente)
protoPayload protopayload_auditlog Igual
protopayload.metadata protopayload_auditlog.metadata_* protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
Exemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
Igual
protoPayload.request protopayload_auditlog.request_[Vn]_[PROTO_NAME]
Exemplo: protopayload_auditlog.request_v2_listlogsinksrequest
protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.response_[Vn]_[PROTO_NAME]
Exemplo: protopayload_auditlog.response_v2_listlogsinksresponse
protopayload_auditlog.responseJson

É preciso revisar suas consultas para usar o esquema (nome de campo) compacto mais recente antes de 1º de março de 2019, quando o esquema (nome de campo) estendido mais antigo será removido.

Veja os detalhes a seguir sobre a nomenclatura do registro de auditoria:

  • A regra de nomenclatura serviceData é específica para os registros de auditoria gerados pelo BigQuery e exportados para ele. Essas entradas de registro contêm um campo serviceData com um especificador @type de:

    type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
    
  • As regras de nomenclatura para os campos estendidos (mais antigos) request e response consideram que os especificadores de tipo deles seguem um padrão comum:

    [GOOGLE_SERVICE].[Vn].[PROTO_NAME]
    

    Por exemplo, em um campo request, o especificador pode ser:

    google.logging.v2.ListLogSinksRequest
    

    Depois de substituir as frases por sublinhados e mudar as letras para minúsculas, isso resultará no seguinte nome de campo habitual:

    request_google_logging_v2_listlogsinksrequest
    

    O nome do campo do esquema especialmente construído é o seguinte:

    request_v2_listlogsinksrequest
    

    Se você encontrar um especificador de tipo com um padrão diferente, confira algumas entradas de registro exportadas para ver como os nomes de campo exportados são encurtados.

Exemplo

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

protoPayload.serviceData.tableInsertRequest

Se ela for exportada para o BigQuery, como ficaria o campo tableInsertRequest? Antes de encurtá-lo, o nome de campo exportado correspondente é:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Depois de encurtar o nome, o mesmo campo aparece nas tabelas do BigQuery assim:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Migração para o esquema atualizado

Atualmente, existem dois conjuntos de nomes de campos, "estendido" e "compacto", para entradas de registro de auditoria no BigQuery. Em 1º de março de 2019, os conjuntos de nomes de campos estendidos serão removidos. Analise suas consultas e determine se você precisa migrar para o novo conjunto de nomes de campos:

  • Se você não usa atualmente os campos request, response ou requestMetadata dos registros de auditoria exportados em qualquer consulta do BigQuery, essa migração não afeta você. Pule esta seção.

  • Se você começar a usar os campos request, response ou requestMetadata pela primeira vez, use os nomes compactos (mais novos) desde o início. Todos os registros de auditoria produzidos para novos serviços usarão somente o novo formato compacto. Pule esta seção.

  • Se você usa os campos request, response ou requestMetadata dos registros de auditoria exportados em qualquer consulta do BigQuery e estiver usando os nomes de campo estendidos (mais antigos), alterne para os nomes compactos (mais novos) o mais rápido possível. Leia esta seção e consulte Como atualizar suas consultas para encontrar um exemplo de como fazer isso.

Essa alteração afeta os registros de auditoria de atividade de administrador e acesso a dados, transformando-os do formato atual estendido, com um número arbitrário de campos, para um formato JSON atualizado e compacto. O Stackdriver Logging já usa o novo formato compacto na gravação dos registros de auditoria existentes:

Esquema compacto

Você poderá ver os dois formatos no BigQuery até 1º de março de 2019, quando o formato estendido será removido.

As exportações de registros que não são de auditoria não são afetadas. As exportações de registros de auditoria para locais diferentes do BigQuery não são afetadas.

Atualizar suas consultas

A tabela nos campos de esquema do registro de auditoria lista os campos que são afetados pela alteração do nome de campo estendido para o nome de campo compacto. Se você consultar algum desses campos, precisará analisar suas consultas do BigQuery e alterá-las conforme necessário antes de 1º de março de 2019, quando os campos mais antigos serão removidos.

Para atualizar suas consultas, é preciso usar o método BigQuery JSON_EXTRACT(). O especificador @type nesses campos precisa ser tratado como uma descrição do conteúdo dos dados JSON.

Por exemplo, veja como uma consulta que seleciona um dos campos createSinkRequest pode ficar com os nomes de campo estendidos:

 SELECT protopayload_auditlog.request_v2_createsinkrequest.sink.destination
 as dest FROM ...

Após a mudança para os nomes de campo compactos, a sintaxe ficará assim:

SELECT JSON_EXTRACT(protopayload_auditlog.requestJson, '$.sink.destination')
as dest FROM ...

Como exibir registros de auditoria

O Stackdriver Logging já usa o novo formato compacto e o formato estendido mais antigo na gravação dos registros de auditoria existentes. Você poderá ver os dois formatos no BigQuery até 1º de março de 2019, quando o formato estendido será removido.

Para ver seus registros de auditoria, selecione uma tabela com entradas de registro exportadas na IU da Web do BigQuery.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Stackdriver Logging
Precisa de ajuda? Acesse nossa página de suporte.