En este documento, se explica cómo puedes encontrar las entradas de registro que enrutaste desde Cloud Logging a las tablas de BigQuery. Los receptores de registros transmiten datos de registro a BigQuery en lotes pequeños, lo que te permite consultar datos sin ejecutar un trabajo de carga. Para ayudarte a crear consultas y comprender el formato de tu tabla de BigQuery, en este documento también se describe el esquema de BigQuery para los registros de rutas.
Cloud Logging usa la API de transmisión heredada para transmitir tus entradas de registro a BigQuery. Por lo general, las entradas de registro se pueden ver en BigQuery en un minuto. Sin embargo, cuando se crea una tabla nueva, es posible que transcurran varios minutos hasta que las primeras entradas de registro estén disponibles.
Antes de comenzar
Para obtener una explicación conceptual de los receptores, consulta Descripción general de los modelos de enrutamiento y almacenamiento: Receptores.
Para obtener instrucciones sobre cómo enrutar tus registros, consulta Enruta registros a destinos compatibles.
Para obtener información sobre cómo se nombran los campos de entrada de registro enrutadas, consulta el esquema de BigQuery para los registros enrutados.
Ver registros
Para ver los registros exportados a BigQuery, haz lo siguiente:
-
En la consola de Google Cloud , ve a la página BigQuery.
También puedes usar la barra de búsqueda para encontrar esta página.
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
Las entradas de registro se pueden ver en la pestaña Detalles, o puedes consultar la tabla para que muestre tus datos.
Consultas de muestra
Para obtener información sobre la sintaxis de las consultas de BigQuery, consulta la referencia de consultas. Las funciones comodín de tablas, que te permiten realizar consultas en varias tablas, y el operador Flatten, que te permite mostrar datos de campos repetidos, son de gran utilidad.
Consulta de muestra de Compute Engine
La siguiente consulta de BigQuery recupera entradas de registro de días y tipos de registros múltiples:
La consulta busca en los últimos tres días de los registros
syslogyapache-access. La consulta se hizo el 23 de febrero de 2020 y comprende todas las entradas de registro recibidas el 21 y el 22 de febrero, además de las entradas de registro recibidas el 23 de febrero hasta el momento en que se emitió la consulta.La consulta recupera los resultados de una única instancia de 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;
A continuación, se muestran algunas filas de ejemplos de resultados:
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 "-" "-"
Consulta de muestra de App Engine
La siguiente consulta de BigQuery recupera consultas de App Engine fallidas del último mes:
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
A continuación, se muestran algunos de los 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 de BigQuery para los registros enrutados
Los esquemas de tablas de BigQuery para los registros enrutados se basan en la estructura del tipo LogEntry y el contenido de las cargas útiles del registro. Cloud Logging también aplica reglas para acortar los nombres de campo del esquema de BigQuery para los registros de auditoría y para ciertos campos de carga útil estructurados. Para ver el esquema de la tabla, selecciona una tabla con entradas de registro enrutadas en la interfaz de BigQuery.
Convenciones de nombres de campo
Existen algunas convenciones de nombres que 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 solo pueden tener caracteres alfanuméricos. Los caracteres no compatibles se quitan de los nombres de campo y se reemplazan por caracteres de guion bajo. Por ejemplo,
jsonPayload.foo%%se transformaría enjsonPayload.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 quitan 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.Para cualquier campo de entrada de registro suministrado por el usuario, los nombres de campo de BigQuery correspondientes están normalizados a minúsculas, pero los nombres se conservan.
Para los campos en cargas útiles estructuradas, siempre que el especificador
@typeno esté presente, los nombres de campo correspondientes de BigQuery se normalizan a 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
@typeestá presente, consulta Campos de carga útil con@typeen 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. Para obtener información sobre las reglas de nomenclatura de los registros de auditoría, consulta la sección Campos de registro de auditoría en esta página.
Las cargas útiles en las 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]
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.
El tipo de entrada de registro determina las reglas de nomenclatura para los campos con el especificador @type. En el caso de las entradas de registro que no son registros de auditoría, estas reglas solo se aplican al nivel superior de jsonPayload o protoPayload; se ignoran los campos anidados. Para obtener información sobre las reglas de asignación de nombres para los registros de auditoría, consulta la sección Campos de registros de auditoría en esta página.
Cuando se tratan campos de carga útil estructurada de nivel superior, Logging quita el prefijo type.googleapis.com.
Por ejemplo, en la siguiente tabla, se muestra la asignación de los campos de carga útil estructurada de nivel superior a los nombres de campo de BigQuery para las entradas de registro que no son registros de auditoría:
| 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 |
Algunas excepciones se aplican 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 incluye un especificador de tipo.La tabla anterior no se aplica a los registros de auditoría. Cloud Logging aplica algunas reglas especiales para acortar los nombres de campo del esquema de BigQuery para los registros de auditoría. Esto se analiza en la sección Campos de los registros 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 reciben en BigQuery.
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
jsonPayloadcontiene un especificador@type. Su nombre de BigQuery esjsonpayload_v1_customtype.Los campos anidados se tratan con las reglas de nombres estándar de BigQuery, ya que las reglas que especifican el tipo no se aplican a los campos anidados.
Por lo tanto, los siguientes nombres de BigQuery se definen por 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 registros de auditoría
Si no trabajas con registros de auditoría que se enrutan a BigQuery, puedes omitir esta sección.
Esta sección se aplica a los campos estructurados que pueden incluir un especificador de tipo opcional en el siguiente formato:
@type: type.googleapis.com/[TYPE]
Modificaciones del nombre del campo
Cuando un registro de auditoría contiene una carga útil con un especificador @type, es posible que Cloud Logging modifique el valor [TYPE] que se agrega al especificador antes de que se genere el nombre del campo de BigQuery. Estas modificaciones generan nombres de campos de BigQuery más cortos.
El registro siempre quita el prefijo type.googleapis.com del valor [TYPE]. En la siguiente tabla, se describe cuándo Logging acorta los nombres de los 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 ejemplo, supongamos que una entrada de registro de auditoría contiene el siguiente contenido:
{
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"
}
}
}
}
Los nombres de los campos de BigQuery se derivan de la entrada de registro modificada, que es la siguiente:
{
logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "AuditLog"
serviceData: {
@type: "legacy.appengine"
eventData: {
timezone: "UTC"
}
}
}
}
Reglas de nomenclatura para @type
En los registros de auditoría, hay varios campos que pueden tener un especificador @type:
protoPayloadprotoPayload.serviceDataprotoPayload.requestprotoPayload.responseprotoPayload.metadata
Los campos request, response y metadata se tratan como datos JSON.
Es decir, sus nombres del esquema de BigQuery son sus nombres de campo con Json agregado a ellos y contienen datos de cadena 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.request |
protopayload_auditlog.requestJson |
protoPayload.response |
protopayload_auditlog.responseJson |
protoPayload.serviceData |
protopayload_auditlog.servicedata_v1_bigquery Ejemplo: protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest |
protoPayload.status.code |
protoPayload_auditlog.statuscode |
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 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 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
Organización de la tabla
En esta sección, se proporciona una descripción general de las 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. 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. Las entradas de registro posteriores podrían provocar un error de coincidencia del esquema. Para obtener información sobre cuándo ocurren y cómo se manejan, consulta Coincidencias en el esquema.
Existen dos tipos de tablas mediante las cuales Logging organiza los datos que enruta: 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 se dividen 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 llevan el sufijo de la fecha de calendario de la marca de tiempo 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 timestamp1 |
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 |
1 Las marcas de tiempo de las entradas de registro se expresan en UTC (Horario universal coordinado)
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 sobre cómo crear receptores, consulta los siguientes recursos:
Consola deGoogle Cloud : Enruta registros a destinos compatibles.
Google Cloud CLI:
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.
Una desigualdad del esquema ocurre 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 para un campo existente en la tabla.
Por ejemplo, si el campo
jsonPayload.user_idde la entrada de registro inicial esstring, esa entrada de registro genera una tabla con un tipo de string para ese campo. Si luego comienzas a generar registrosjsonPayload.user_idcomoarray, eso provoca un error de coincidencia del esquema.Una nueva entrada de registro contiene un campo que no está en el esquema actual, y la inserción de ese campo en la tabla de destino superaría el límite de columnas de BigQuery.
La tabla de destino puede aceptar el campo nuevo si no se supera el límite de columnas.
Cuando BigQuery identifica una discrepancia de esquema, crea una tabla dentro del conjunto de datos correspondiente para almacenar la información de error. El tipo de tabla determina el nombre de la tabla. Para las tablas fragmentadas por fecha, el formato de nomenclatura es export_errors_YYYYMMDD. Para las tablas particionadas, el formato de nomenclatura es export_errors. Para obtener más información, consulta Organización de la tabla.
Cuando enruta 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 actual de mensajes:
Cuando se produce un cambio de tipo de campo, solo se escriben en la tabla de errores aquellas entradas de registro que generaron una discrepancia del esquema. Las entradas de registro en el lote actual de mensajes que no provocan una discrepancia de esquema se escriben en la tabla de destino original.
Cuando se excede el límite de columna, todas las entradas de registro en el lote actual de mensajes se escriben en la tabla de error.
Esquema de la tabla de errores
La tabla de errores contiene datos de LogEntry y la información sobre la falta de coincidencia:
logEntry: Contiene la entrada de registro completa; sin embargo, la entrada de registro se convierte de JSON en una cadena.schemaErrorDetail: Contiene el mensaje de error completo que devolvió BigQuery.sink: Contiene la ruta de acceso completa al receptor de registros.logName: Se extrae deLogEntry.timestamp: Se extrae deLogEntry.receiveTimestamp: Se extrae deLogEntry.severity: Se extrae deLogEntry.insertId: Se extrae deLogEntry.trace: Se extrae deLogEntry.resourceType: Se extrae deLogEntry.
Logging comunica las discrepancias del esquema con el proyecto deGoogle 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, el nombre del receptor y el destino. Google Cloud
- En la página Actividad de la consola, se muestra un error,
Stackdriver Config error. Google Cloud 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.
Cómo evitar futuros errores de coincidencia de tipos de campos
Si deseas corregir las discrepancias por tipo de campo para las entradas de registro posteriores, corrige el tipo de campo a fin de que coincida con el esquema actual. Para obtener información sobre cómo corregir un tipo de campo, consulta Cambia el tipo de datos de una columna.
A veces, el tipo de campo no se puede cambiar. Por ejemplo, no puedes cambiar el tipo de campo de los registros que generan automáticamente los servicios de Google Cloud. Para evitar discrepancias en el esquema cuando no puedes cambiar el tipo de un campo, cambia 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, consulta Administra receptores.
Soluciona problemas
Si parece que faltan registros en el destino del receptor o sospechas que el receptor no enruta los registros correctamente, consulta Soluciona problemas de enrutamiento de registros.
Precios
Cloud Logging no cobra por enrutar registros a un destino compatible; sin embargo, es posible que el destino aplique cargos.
Con la excepción del bucket de registros _Required, Cloud Logging cobra por transmitir registros a los buckets de registros y por el almacenamiento que supere el período de retención predeterminado del bucket de registros.
Cloud Logging no cobra por copiar registros, crear alcances de registros o vistas de análisis, ni por las consultas que se emiten a través de las páginas del Explorador de registros o del Análisis de registros.
Para obtener más información, consulta los siguientes documentos:
- Resumen de precios de Cloud Logging
Costos de destino:
- Se aplican cargos por generación de registros de flujo de VPC cuando envías y, luego, excluyes tus registros de flujo de Virtual Private Cloud de Cloud Logging.