Esquema de BigQuery para registros

En esta página, se detalla el formato y las reglas que se aplican cuando se enrutan las entradas de registro de Cloud Logging a BigQuery.

Descripción general

Puedes enrutar entradas de registro de Cloud Logging a BigQuery mediante receptores. Cuando creas un receptor, defines un conjunto de datos de BigQuery como el destino. Logging envía entradas de registro que coinciden con las reglas del receptor a tablas particionadas que se crean para ti en ese conjunto de datos de BigQuery.

Los esquemas de tablas de BigQuery para los datos recibidos de Cloud Logging se basan en la estructura del tipo LogEntry y el contenido de las cargas útiles de entrada de registro. Cloud Logging también aplica reglas a fin de acortar los nombres de campo del esquema de BigQuery para los registros de auditoría y ciertos campos de carga útil estructurados.

Logging envía datos de registro de transmisión a BigQuery en lotes pequeños, lo que te permite consultar datos sin ejecutar un trabajo de carga. Para obtener más información, consulta Transmite datos a BigQuery. Para obtener información sobre los precios, consulta la sección de inserciones de transmisión que se encuentra en Precios de BigQuery: precios de transferencia de datos.

Convenciones de nombres de campo

Hay algunas convenciones de nombres que se aplican a los campos de entrada de registro cuando se envían registros a BigQuery:

  • Los nombres de los campos de entrada de registro no pueden superar los 128 caracteres.

  • Los nombres de los campos de entrada de registro pueden estar compuestos solo de caracteres alfanuméricos. Se quitan los caracteres no compatibles de los nombres de campo y se reemplazan por caracteres de guion bajo. Por ejemplo, jsonPayload.foo%% se transformaría en jsonPayload.foo__.

    Los nombres de los campos de entrada de registro deben comenzar con un carácter alfanumérico, incluso después de la transformación. se quitarán los guiones bajos iniciales.

  • 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.

  • En el caso de los campos de entrada de registro suministrados por el usuario, los nombres de los campos de BigQuery correspondientes están normalizados a minúsculas, pero los nombres se conservan de otra manera.

  • Para los campos en cargas útiles estructuradas, siempre que el especificador @type no esté presente, los nombres de los campos correspondientes de BigQuery se normalizan a minúsculas, pero los nombres se conservan de otra manera.

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

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

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 el especificador @type. Esto incluye las entradas de registro de auditoría enrutadas a BigQuery.

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

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

Las reglas de nomenclatura explican por qué el campo protoPayload de una entrada de registro de auditoría puede asignarse al campo del esquema de BigQuery protopayload_auditlog.

Reglas de nomenclatura para @type

Por lo general, los campos estructurados que tienen especificadores de tipo reciben nombres de campo de BigQuery que tienen un [TYPE] agregado a su nombre de campo. El valor de [TYPE] puede ser cualquier string.

Las reglas de denominación @type se aplican solo al nivel superior de jsonPayload o protoPayload. se ignoran los campos anidados. Cuando se tratan campos de carga útil estructurados de nivel superior, Logging quita el prefijo type.googleapis.com.

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 (ninguno) statusCode protoPayload.statuscode
protoPayload type.googleapis.com/abc.Xyz statusCode protopayload_abc_xyz.statuscode

Se aplican 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 enrutados a BigQuery es protoPayload, aunque la carga útil incluya un especificador de tipo.

  • Cloud 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 en esta página.

Ejemplo

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

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

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

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

  • El campo estructurado de nivel superior jsonPayload contiene un especificador @type. Su nombre de BigQuery es jsonpayload_v1_customtype.

  • Los campos anidados se tratan con las reglas de nomenclatura estándar de BigQuery, ya que las reglas de especificador de tipos no se aplican a los campos anidados.

Por lo tanto, los siguientes nombres de BigQuery se definen para la carga útil de la 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 de los registros de auditoría exportados

Si no trabajas con registros de auditoría que se enrutan a BigQuery, puedes omitir esta sección.

Los campos de carga útil del registro de auditoría, 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
protoPayload protopayload_auditlog
protopayload.metadata protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
Ejemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
protoPayload.request protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.responseJson

Ten en cuenta que la convención de nombres serviceData es específica de los registros de auditoría que generó BigQuery y que luego se enrutan de Cloud Logging a BigQuery. Esas entradas de registro de auditoría contienen un campo serviceData que tiene un especificador @type de type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata.

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 enruta a BigQuery, ¿cómo se haría referencia al campo tableInsertRequest? Antes de acortar el nombre, el nombre del campo correspondiente en BigQuery 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

Tablas particionadas

En esta sección, se proporciona una descripción general de tablas particionadas para los registros que se enrutan a BigQuery.

Cuando enrutas registros a un conjunto de datos de BigQuery, Logging crea tablas para contener las entradas de registro. Hay dos tipos de tablas en los que Logging organiza los datos que enruta: tablas fragmentadas de fecha y tablas particionadas. Ambos tipos de tabla particionan los datos de registro en función de los campos timestamp de las entradas de registro. Sin embargo, existen dos diferencias clave entre los tipos de tabla:

  • Rendimiento: una tabla particionada divide una tabla grande en particiones más pequeñas para que puedas mejorar el rendimiento de las consultas y, así, controlar mejor los costos de BigQuery mediante la reducción de la cantidad de bytes leídos por una consulta.

  • Nomenclatura de la tabla: los tipos de tabla usan convenciones de nombres diferentes, como se explica en la siguiente sección.

Organización de la tabla

Las entradas de registro se fragmentan en tablas de BigQuery cuya organización y nombres se basan en las marcas de tiempo y los nombres de registro de las entradas.

A los nombres de la tabla se les agrega un sufijo con la fecha del calendario de la marca de tiempo en UTC de la entrada de registro mediante el formato básico ISO 8601 (YYYYMMDD).

En la siguiente tabla, se muestran ejemplos sobre cómo se asignan los nombres de registros y las marcas de tiempo de muestra a los nombres de tablas en BigQuery:

Nombre del registro Entrada de registro timestamp Nombre de la tabla de BigQuery
(fragmentada por fecha)
Nombre de tabla de 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

Crea tablas particionadas

Cuando creas un receptor para enrutar tus registros a BigQuery, puedes usar tablas fragmentadas por fecha o tablas particionadas. La selección predeterminada es una tabla fragmentada por fecha.

Para obtener instrucciones mediante Google Cloud Console, consulta Configura receptores.

Para obtener instrucciones mediante el SDK de Cloud, la interfaz de línea de comandos, consulta gcloud logging sinks create.

Discrepancias en el esquema

La primera entrada de registro que recibe BigQuery determina el esquema para la tabla de BigQuery de destino. BigQuery crea una tabla cuyas columnas se basan en los campos de la primera entrada de registro y sus tipos.

Se produce una falta de coincidencia del esquema cuando se escriben entradas de registro en la tabla de destino y se produce cualquiera de los siguientes errores:

  • Una entrada de registro posterior cambia el tipo de campo de un campo existente en la tabla.

    Por ejemplo, si el campo jsonPayload.user_id de la entrada de registro inicial es string, esta genera una tabla con un tipo de string para ese campo. Si más adelante comienzas a registrar jsonPayload.user_id como array, se generará una discrepancia de esquema.

  • Se agregan campos nuevos a una entrada de registro y eso hace que la cantidad de columnas en la tabla de destino supere el límite de columnas de BigQuery. Para obtener más información sobre el límite de columnas, consulta Cuotas y límites de BigQuery.

Cuando BigQuery identifica un desajuste en el esquema, crea una tabla dentro del conjunto de datos correspondiente para almacenar la información del error. El tipo de tabla determina el nombre de la tabla. Para las tablas fragmentadas por fecha, el formato es export_errors_YYYYMMDD. Para las tablas particionadas, el formato es export_errors. Para obtener más información, consulta Organización de la tabla.

Cuando se exportan entradas de registro, Logging envía mensajes como un lote a BigQuery. BigQuery usa las siguientes reglas para determinar en qué tabla se escriben las entradas de registro en el lote de mensajes actual:

  • Cuando se produce un cambio de tipo de campo, solo se escriben en la tabla de errores aquellas entradas de registro que generaron un error de coincidencia en el esquema. Las entradas de registro en el lote actual de mensajes que no causan una discrepancia de esquema se escriben en la tabla de destino original.

  • Cuando se excede el límite de la columna, todas las entradas de registro en el lote actual de mensajes se escriben en la tabla de errores.

La tabla de errores contiene datos de la LogEntry y la información sobre la falta de coincidencia:

  • Campos LogEntry escritos en la tabla de errores:

    • logName
    • timestamp
    • receiveTimestamp
    • severity
    • insertId
    • trace
    • resource.type
  • La información del esquema no coincide y se escribió en la tabla de errores:

    • Ruta de acceso completa de los recursos al receptor de registros
    • El mensaje de error completo que muestra BigQuery
    • La entrada de registro completa Sin embargo, la entrada de registro se convierte de JSON en una string

Logging comunica las discrepancias de esquema al proyecto de Cloud que contiene el receptor de enrutamiento de las siguientes maneras:

  • Los propietarios del proyecto reciben un correo electrónico. Los detalles incluyen el ID del proyecto de Google Cloud, el nombre del receptor y el destino.
  • En la página Actividad de Google Cloud Console, se muestra un error, Stackdriver Config error. Los detalles incluyen el nombre y el destino del receptor, y un vínculo a un ejemplo de una entrada de registro que causó el error.
  • La métrica basada en registros del sistema exports/error_count te informa la cantidad total de entradas de registro que no se enrutaron debido a errores.

Para corregir las discrepancias de los tipos de campo en las entradas de registro posteriores, corrige el tipo de campo para que coincida con el esquema actual. También puedes cambiar el nombre de la tabla o los parámetros del receptor para que Logging vuelva a crear la tabla en un conjunto de datos diferente. Para obtener instrucciones, consulta Administra receptores.

Visualiza los registros

Para ver los registros y su esquema de BigQuery, selecciona una tabla en la IU web de BigQuery que haya recibido entradas de registro de Cloud Logging.