En esta página, se detalla el formato y las reglas que se aplican cuando se exportan entradas de registro de Cloud Logging a BigQuery.
Logging transmite datos de registros a BigQuery, un registro a la vez, en lugar de usar trabajos de carga. En este enfoque, se habilita la consulta de datos en BigQuery sin la demora de ejecutar un trabajo de carga. Para obtener más información, consulta Transmite datos a BigQuery.
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. Cloud 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. Para 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 las 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
. Se analiza en detalle en la siguiente secció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
.
Reglas de denominación de esquemas
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]
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.
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 sí 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.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 exportados del esquema del registro de auditoría a continuación.
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
yname_a
están estructurados, pero no tienen los especificadores@type
. Sus nombres de BigQuery sonjsonPayload
yname_a
, respectivamente.Los campos
sub_a
ysub_b
no están estructurados, por lo que sus nombres de BigQuery sonsub_a
ysub_b
, respectivamente.El campo
name_b
tiene un especificador@type
, cuyo [TYPE] esgoogle.cloud.v1.SubType
. Por lo tanto, su nombre de BigQuery esname_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 de los registros de auditoría exportados
Si no trabajas con registros de auditoría que se exportaron a BigQuery, puedes omitir este paso.
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 exportan de Cloud Logging a BigQuery. Esas entradas del 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 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
Tablas particionadas
En esta sección, se proporciona una descripción general de las tablas particionadas para las exportaciones de registros a BigQuery.
Cuando exportas registros a un conjunto de datos de BigQuery, Logging crea tablas para contener las entradas de registro exportadas.
Existen dos tipos de tablas mediante las cuales Logging organiza los datos que exporta: tablas fragmentadas por fecha y tablas particionadas. En ambos tipos de tabla, se dividen los datos de los registros en función de los campos timestamp
de las entradas de registro. Sin embargo, hay dos diferencias fundamentales entre los tipos de tabla:
Rendimiento: en la tabla particionada, se divide una tabla grande en particiones más pequeñas para mejorar el rendimiento de las consultas y controlar mejor los costos de BigQuery mediante la reducción en la cantidad de bytes que se leen en 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 exportadas se fragmentan en tablas de BigQuery cuya organización y nombres se basan en los nombres de registro y las marcas de tiempo de las entradas.
Los nombres de las tablas tienen el sufijo de la fecha del calendario de la marca de tiempo de UTC de la entrada de registro mediante el formato básico ISO 8601 (AAAAMMDD).
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 exportar 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 acerca de cómo usar Google Cloud Console, ve a Exporta con el Explorador de registros.
Para obtener instrucciones acerca de cómo usar la interfaz de línea de comandos del SDK de Cloud, ve a gcloud logging sinks create
.
Discrepancias en el esquema
La primera entrada de registro que se exporta determina el esquema de la tabla de BigQuery de destino. La entrada de registro genera una tabla cuyas columnas se basan en los campos de entradas de registro y sus tipos. El esquema de la tabla se actualiza si aparecen campos nuevos en las entradas de registro posteriores. Sin embargo, si cambia el tipo de valor para un campo existente, se descartan las entradas de registro más nuevas que no coinciden con el esquema.
Por ejemplo, si la exportación inicial contiene una entrada de registro en la que jsonPayload.user_id
es un string
, esa entrada de registro genera una tabla con un tipo de string para ese campo. Si comienzas a generar registros jsonPayload.user_id
como array
, esas entradas no se insertarán en la tabla y se perderán.
Logging comunica esta pérdida de datos para el proyecto de Google Cloud que contiene la exportación de las siguientes formas:
- 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 de la exportación.
- En la página Actividad de Google Cloud Console, se muestra un error,
Stackdriver Config error
. Los detalles incluyen el nombre del receptor y el destino de la exportación, 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
informa la cantidad total de entradas de registro que no se exportaron debido a errores.
Para corregir el problema de las entradas de registro subsiguientes, de modo que no se pierdan más datos, 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. Si deseas obtener instrucciones, ve a la sección Actualiza receptores.
Visualiza los registros
Para ver los registros mediante la IU web de BigQuery, selecciona una tabla con las entradas de registro exportadas.