Esquema de BigQuery de registros exportados

Los esquemas de tablas de BigQuery para los registros exportados se basan en la estructura del tipo LogEntry y el contenido de las cargas útiles del registro. Stackdriver Logging también aplica algunas reglas especiales a fin de acortar los nombres de campo del esquema de BigQuery para los registros de auditoría. Si deseas ver el esquema de la tabla, selecciona una tabla con entradas de registro exportadas en la IU web de BigQuery.

Convenciones de denominación de campo

Existen algunas convenciones de nombres que aplican a los campos de entrada de registro:

• Para los campos de entrada de registro que forman parte del tipo LogEntry, los nombres de campo de BigQuery correspondientes son los mismos que los campos de entrada de registro.

• Para cualquier campo suministrado por el usuario, está normalizado el uso de minúsculas, pero, por lo demás, los nombres se conservan.

  • Para los campos en cargas útiles estructuradas, siempre que el especificador @type no esté presente, está normalizado el uso de minúsculas, pero, por lo demás, se conservan los nombres.

    Para obtener más información sobre cargas útiles estructuradas en el que el especificador @type está presente, consulta Campos de carga útil con @type.

En los siguientes ejemplos, se muestra cómo se aplican estas convenciones de denominación:

Campo de entrada de registro	Asignación de tipo LogEntry	Nombre de campo de 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

La asignación de los campos de carga útil estructurada a los nombres de campo de BigQuery es más complicado cuando el campo estructurado contiene un especificador @type. Esto se analiza en la sección a continuación.

Campos de carga útil con @type

En esta sección, se analizan los nombres de campo del esquema de BigQuery especiales para entradas de registro cuyas cargas útiles contienen especificadores de tipo (campos @type). Esto incluye las entradas del registro de auditoría exportadas que se guardan en BigQuery. En esta sección, por ejemplo, se explica por qué el campo protoPayload de una entrada del registro de auditoría puede asignarse al campo del esquema de BigQuery protopayload_auditlog.

En la actualidad, existen dos esquemas para las entradas del registro de auditoría en BigQuery. Con dos esquemas nos referimos a que cierta información de la carga útil del registro de auditoría está duplicada en dos campos de BigQuery diferentes que contienen la información en formatos diferentes: un nombre de campo “extendido” más antiguo y un nombre de campo “compacto” más nuevo. El 1 de marzo de 2019, se quitará el esquema más antiguo (nombres de campo). Para obtener más detalles, consulta la sección Migración al esquema actualizado a continuación.

Reglas de denominación del esquema

Las cargas útiles en las entradas de registro pueden contener datos estructurados y estos pueden estar anidados en campos estructurados. Cualquier campo estructurado puede incluir un especificador de tipo opcional en el siguiente formato:

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

Los campos estructurados que tienen especificadores de tipo, por lo general, reciben nombres de campo de BigQuery que tienen un [TYPE] agregado a su nombre de campo.

En la siguiente tabla, por ejemplo, se muestra la asignación de los campos de carga útil estructurada de nivel superior a los nombres de campo de BigQuery:

Carga útil	Carga útil @type	Campo de carga útil	Nombre de campo de BigQuery
jsonPayload	(ninguna)	statusCode	jsonPayload.statusCode
jsonPayload	type.googleapis.com/abc.Xyz	statusCode	jsonPayload_abc_xyz.statuscode
protoPayload	(ninguna)	statusCode	protoPayload.statuscode
protoPayload	type.googleapis.com/abc.Xyz	statusCode	protopayload_abc_xyz.statuscode

Si jsonPayload o protoPayload contienen otros campos estructurados, esos campos internos se asignarán de la siguiente manera:

• Si un campo estructurado anidado no tiene un especificador @type, entonces el nombre de campo de BigQuery es el mismo que el nombre de campo original, excepto que está normalizado a letras minúsculas.
• Si el campo estructurado anidado si tiene un especificador @type, entonces el nombre de campo de BigQuery tiene un [TYPE] (vuelto a escribir) agregado al nombre de campo y se normaliza a letras minúsculas.

Existen algunas excepciones a las reglas anteriores para los campos con especificadores de tipo:

• En los registros de solicitud de App Engine, el nombre de la carga útil en los registros exportados a BigQuery es protoPayload, aunque la carga útil tenga un especificador de tipo. Puedes ver esto en el ejemplo de la consulta de registros de App Engine en Consultas.

• Stackdriver Logging aplica algunas reglas especiales a fin de acortar los nombres de campo del esquema de BigQuery para los registros de auditoría. Esto se analiza en la sección Campos del esquema del registro de auditoría a continuación.

• Los registros de auditoría que se exportan a BigQuery se escriben en un formato compacto actualizado. Parte de la información de la carga útil se duplica de forma temporal en dos campos diferentes. A fin de obtener detalles, consulta Migración al esquema actualizado.

Ejemplo

En este ejemplo, se muestra cómo los campos de carga útil estructurados se nombran y se usan cuando se exportan a BigQuery.

Supongamos que una carga útil de la entrada de registro está estructurada de la siguiente manera:

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

La asignación a los campos de BigQuery es la que se muestra a continuación:

• Los campos jsonPayload y name_a están estructurados, pero no tienen los especificadores @type. Sus nombres de BigQuery son jsonPayload y name_a, respectivamente.

• Los campos sub_a y sub_b no están estructurados, por lo que sus nombres de BigQuery son sub_a y sub_b, respectivamente.

• El campo name_b tiene un especificador de @type, cuyo [TYPE] es google.cloud.v1.SubType. Por lo tanto, su nombre de BigQuery es name_b_google_cloud_v1_subtype.

En resumen, los siguientes 5 nombres de BigQuery se definen por la carga útil de la entrada de registro:

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 exportados del esquema del registro de auditoría

Si no trabajas con registros de auditorías que se exportaron a BigQuery, puedes omitir este paso.

Nota: En la actualidad, existen dos conjuntos de campos para entradas de los registros de auditoría en BigQuery. El 1 de marzo de 2019, los campos “extensos” más antiguos se quitarán en favor de los campos “compactos” más nuevos. Si no exportas los registros de auditoría a BigQuery, este cambio no te afectará. Los usuarios que exporten registros de auditoría a BigQuery deben controlar los campos modificados y actualizar las consultas que los usan. A fin de obtener detalles, consulta Migración al esquema actualizado.

Todos los campos de carga útil del registro de auditoría más antiguos (“extensos”) tienen especificadores de tipo (campos @type) en Stackdriver. Sus nombres de campo de BigQuery correspondientes se diseñaron en particular para evitar que sean demasiado extensos.

Los campos de carga útil del registro de auditoría más nuevos (“compactos”), protoPayload.request, protoPayload.response y protoPayload.metadata, tienen especificadores @type, pero se tratan como datos de JSON. Es decir, sus nombres del esquema de BigQuery son sus nombres de campo con Json agregado a ellos y contienen datos de string en formato JSON.

Los dos conjuntos de nombres de campo de carga útil del registro de auditoría se enumeran en la siguiente tabla:

Campo de entrada de registro	Nombre de campo de BigQuery extenso (más antiguo)	Nombre de campo de BigQuery compacto (más nuevo)
protoPayload	protopayload_auditlog	Igual
protopayload.metadata	protopayloadauditlog.metadata*	protopayload_auditlog.metadataJson
protoPayload.serviceData	protopayload_auditlog.servicedata_v1_bigquery Ejemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest	Igual
protoPayload.request	protopayload_auditlog.request_[Vn]_[PROTO_NAME] Ejemplo: protopayload_auditlog.request_v2_listlogsinksrequest	protopayload_auditlog.requestJson
protoPayload.response	protopayload_auditlog.response_[Vn]_[PROTO_NAME] Ejemplo: protopayload_auditlog.response_v2_listlogsinksresponse	protopayload_auditlog.responseJson

Debes modificar tus consultas para que usen el esquema compacto más nuevo (nombres de campo) antes del 1 de marzo de 2019, cuando se quite el esquema extenso más antiguo (nombres de campo).

Ten en cuenta los detalles siguientes sobre la denominación del registro de auditoría:

• La regla de denominación serviceData es específica de los registros de auditoría que generó BigQuery y que luego se exportan a BigQuery. Esas entradas del registro de auditoría contienen un campo serviceData que tiene este especificador @type:

  type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
  

• Las reglas de denominación para los campos request y response extensos (más antiguos) suponen que sus especificadores de tipo siguen un patrón común:

  [GOOGLE_SERVICE].[Vn].[PROTO_NAME]
  

  Por ejemplo, en un campo request, el especificador podría ser el siguiente:

  google.logging.v2.ListLogSinksRequest
  

  Después se reemplazar los puntos con guiones bajos y cambiar a minúsculas, esto da como resultado el siguiente nombre de campo tradicional:

  request_google_logging_v2_listlogsinksrequest
  

  Este es el nombre de campo del esquema creado especialmente:

  request_v2_listlogsinksrequest
  

  Si encuentras un especificador de tipo con un patrón diferente, mira algunas entradas de registro exportadas para ver cómo se acortan los nombres de campo exportados.

Ejemplo

Una entrada del registro de auditoría generada por BigQuery tiene un campo con el siguiente nombre:

protoPayload.serviceData.tableInsertRequest

Si esta entrada de registro se exporta a BigQuery, ¿cómo se haría referencia al campo tableInsertRequest? Antes de acortar el nombre, el nombre del campo exportado correspondiente sería el siguiente:

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

Después de acortar el nombre, se hace referencia al mismo campo en las tablas de BigQuery de esta manera:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Migración al esquema actualizado

En la actualidad, existen dos conjuntos de nombres de campo, “extensos” y “compactos”, para las entrada del registro de auditoría en BigQuery. El 1 de marzo de 2019, se quitarán los conjuntos de nombres de campo extensos. Revisa tus consultas y determina si necesitas migrar a un conjunto nuevo de nombres de campo:

• Si ahora no usas los campos request, response o requestMetadata de los registros de auditoría exportados en cualquier consulta de BigQuery, esta migración no te afecta. Omite esta sección.

• Si comienzas a usar los campos request, response o requestMetadata por primera vez, usa los nombres compactos (más nuevos) desde el comienzo. Todos los registros de auditoría producidos para servicios nuevos solo usarán el formato compacto nuevo. Omite esta sección.

• Si usas los campos request, response o requestMetadata de los registros de auditoría exportados en cualquier consulta de BigQuery y usas los nombres de campo extensos (más antiguos), cambia a los nombres compactos (más nuevos) lo antes posible. Lee esta sección y consulta Actualiza tus consultas para obtener un ejemplo de cómo actualizar tus consultas.

Este cambio afecta la actividad de administrador y los registros de auditoría de acceso a los datos, ya que los transforma del formato actual extenso con un número arbitrario de campos a un formato JSON actualizado y compacto. Para los registros de auditoría existentes, Stackdriver Logging ya escribe con el nuevo formato compacto:

Puedes ver ambos formatos en BigQuery hasta el 1 de marzo de 2019, día en el que se quitará el formato extenso.

Las exportaciones de registros que no son de auditoría no se ven afectadas. Las exportaciones del registro de auditoría a ubicaciones que no sean BigQuery no se ven afectadas.

Actualiza tus consultas

La tabla en los campos del esquema del registro de auditoría enumera los campos que se ven afectados por el cambio del nombre de campo extenso al nombre de campo compacto. Si consultas cualquiera de estos campos, debes revisar tus consultas de BigQuery y modificarlas según sea necesario antes del 1 de marzo de 2019, día en el que se quitarán los campos más antiguos.

Para actualizar tus consultas, debes usar el método de BigQuery JSON_EXTRACT(). El especificador @type en estos campos debe tratarse como una descripción del contenido de los datos JSON.

A modo de ejemplo, así es cómo se vería una consulta que selecciona uno de los campos createSinkRequest con los nombres de campo extensos:

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

Luego del cambio a los nombres de campo compacto, la sintaxis se verá de la siguiente manera:

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

Visualiza tus registros de auditoría

Para los registros de auditoría existentes, Stackdriver Logging escribe con el formato compacto más nuevo y el formato extenso más antiguo. Puedes ver ambos formatos en BigQuery hasta el 1 de marzo de 2019, día en el que se quitará el formato extenso.

Para ver tus registros de auditoría, selecciona una tabla con las entradas de registro exportadas en la IU web de BigQuery.