Ver los registros enrutados a BigQuery

En este documento se explica cómo encontrar las entradas de registro que ha enrutado desde Cloud Logging a tablas de BigQuery. Los receptores de registro transmiten datos de registro a BigQuery en pequeños lotes, lo que le permite consultar datos sin ejecutar una tarea de carga. Para ayudarte a crear consultas y entender el formato de tu tabla de BigQuery, en este documento también se describe el esquema de BigQuery de los registros enrutados.

Cloud Logging usa la API de streaming antigua para transmitir tus entradas de registro a BigQuery. Normalmente, las entradas de registro se pueden ver en BigQuery en un plazo de un minuto. Sin embargo, cuando se crea una tabla, pueden pasar varios minutos antes de que estén disponibles las primeras entradas de registro.

Antes de empezar

Para obtener información conceptual sobre los receptores, consulta Descripción general de los modelos de enrutamiento y almacenamiento: receptores.

Para obtener instrucciones sobre cómo enrutar los registros, consulta el artículo Enrutar registros a destinos admitidos.

Para saber cómo se denominan los campos de las entradas de registro enrutadas, consulte el esquema de BigQuery para los registros enrutados.

Ver registros

Para ver los registros enrutados a BigQuery, siga estos pasos:

1. En la Google Cloud consola, ve a la página BigQuery:

   Ve a BigQuery Studio.

   También puedes encontrar esta página mediante la barra de búsqueda.

2. 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. También puede consultar la tabla para obtener sus datos.

Consultas de ejemplo

Para obtener información sobre la sintaxis de las consultas de BigQuery, consulta la referencia de las consultas. Las funciones de comodín de tabla son especialmente útiles, ya que te permiten consultar varias tablas, así como el operador de aplanamiento, que te permite mostrar datos de campos repetidos.

Consulta de ejemplo de Compute Engine

La siguiente consulta de BigQuery obtiene entradas de registro de varios días y varios tipos de registro:

• La consulta busca en los registros de los últimos tres días syslog y apache-access. La consulta se hizo el 23 de febrero del 2020 y abarca todas las entradas de registro recibidas los días 21 y 22 de febrero, así como las entradas de registro recibidas el 23 de febrero hasta el momento en que se hizo la consulta.

• La consulta obtiene resultados de una sola 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;

Aquí tienes algunas filas de salida de ejemplo:

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 App Engine de ejemplo

La siguiente consulta de BigQuery obtiene las solicitudes 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

Estos son 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 de los registros enrutados

Los esquemas de las tablas de BigQuery de los registros enrutados se basan en la estructura del tipo LogEntry y en el contenido de las cargas útiles de los registros. Cloud Logging también aplica reglas para acortar los nombres de los campos del esquema de BigQuery en los registros de auditoría y en determinados campos de carga útil estructurada. Para ver el esquema de la tabla, selecciona una tabla con entradas de registro enrutadas en la interfaz de BigQuery.

Convenciones de nomenclatura de campos

Hay algunas convenciones de nomenclatura que se aplican a los campos de entrada de registro al enviar registros a BigQuery:

• Los nombres de los campos de las entradas de registro no pueden tener más de 128 caracteres.

• Los nombres de los campos de las entradas de registro solo pueden estar formados por caracteres alfanuméricos. Los caracteres no admitidos se quitan de los nombres de los campos y se sustituyen por guiones bajos. Por ejemplo, jsonPayload.foo%% se transformaría en jsonPayload.foo__.

  Los nombres de los campos de las entradas de registro deben empezar por un carácter alfanumérico, incluso después de la transformación. Se eliminan los guiones bajos iniciales.

• En el caso de los campos de entrada de registro que forman parte del tipo LogEntry, los nombres de los campos de BigQuery correspondientes son exactamente los mismos que los de los campos de entrada de registro.

• En el caso de los campos de entrada de registro proporcionados por los usuarios, los nombres de los campos de BigQuery correspondientes se normalizan a minúsculas, pero el resto de los nombres se conservan.

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

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

En los siguientes ejemplos se muestra cómo se aplican estas convenciones de nomenclatura:

Campos de carga útil con @type

En esta sección se describen los nombres de campos especiales del esquema de BigQuery para las entradas de registro cuya carga útil contiene el especificador @type. Para obtener información sobre las reglas de nomenclatura de los registros de auditoría, consulta la sección Campos de los registros de auditoría de esta página.

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

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

Reglas de nomenclatura de @type

Los campos estructurados que tienen especificadores de tipo suelen recibir nombres de campo de BigQuery que tienen el sufijo [TYPE]. El valor de [TYPE] puede ser cualquier cadena.

El tipo de entrada de registro determina las reglas de nomenclatura de los campos con el especificador @type. En el caso de las entradas de registro que no son registros de auditoría, estas reglas se aplican solo al nivel superior de jsonPayload o protoPayload. Los campos anidados se ignoran. Para obtener información sobre las reglas de nomenclatura de los registros de auditoría, consulta la sección Campos de los registros de auditoría de esta página.

Cuando se tratan campos de carga útil estructurada de nivel superior, Logging elimina 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 los campos de BigQuery para las entradas de registro que no son registros de auditoría:

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

• En los registros de solicitudes 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 los campos del esquema de BigQuery en los registros de auditoría. Esto se explica en la sección Campos de los registros de auditoría de esta página.

Ejemplo

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

Supongamos que la carga útil de una entrada de registro tiene la siguiente estructura:

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 siguiente:

• El campo estructurado de nivel superior jsonPayload contiene un especificador @type. Su nombre en 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 tipo no se aplican a los campos anidados.

Por lo tanto, se definen los siguientes nombres de BigQuery 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 registros de auditoría

Si no trabajas con registros de auditoría que se hayan enrutado a BigQuery, puedes saltarte esta sección.

Esta sección se aplica a los campos estructurados que pueden incluir un especificador de tipo opcional con el siguiente formato:

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

Modificaciones de nombres de campos

Cuando un registro de auditoría contiene una carga útil con un especificador @type, Cloud Logging puede modificar el valor [TYPE] que se añade al especificador antes de que se genere el nombre del campo de BigQuery. Estas modificaciones dan como resultado nombres de campo de BigQuery más cortos.

El registro siempre elimina el prefijo type.googleapis.com del valor [TYPE]. En la siguiente tabla se describe cuándo acorta Logging los nombres de los campos:

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 de @type

En los registros de auditoría, hay varios campos que pueden tener un especificador @type:

• protoPayload
• protoPayload.serviceData
• protoPayload.request
• protoPayload.response
• protoPayload.metadata

Los campos request, response y metadata se tratan como datos JSON. Es decir, los nombres de su esquema de BigQuery son sus nombres de campo con Json añadido y contienen datos de cadena en formato JSON.

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

Ten en cuenta que la convención de nomenclatura serviceData es específica de los registros de auditoría que genera BigQuery y que, a continuación, 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 de registro de auditoría generada por BigQuery tiene un campo con el siguiente nombre:

protoPayload.serviceData.tableInsertRequest

Si esta entrada de registro se enrutara a BigQuery, ¿cómo se haría referencia al campo tableInsertRequest? Antes de acortar el nombre, el nombre de campo correspondiente en BigQuery era 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 la siguiente manera:

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

Organización de tablas

En esta sección se ofrece una descripción general de las tablas con particiones de los registros que se enrutan a BigQuery.

Cuando enruta registros a un conjunto de datos de BigQuery, Logging crea tablas para almacenar las entradas de registro. La primera entrada de registro que recibe BigQuery determina el esquema de la tabla de destino de BigQuery. 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 pueden provocar una discordancia de esquema. Para obtener información sobre cuándo se producen y cómo se gestionan, consulta Incoherencias en el esquema.

Hay dos tipos de tablas por los que Logging organiza los datos que enruta: tablas fragmentadas por 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, hay dos diferencias clave entre los tipos de tabla, que se indican a continuación:

• Rendimiento: una tabla con particiones divide una tabla grande en particiones más pequeñas, lo que te permite mejorar el rendimiento de las consultas y, por lo tanto, controlar mejor los costes de BigQuery al reducir el número de bytes leídos por una consulta.

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

Organización de tablas

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

Los nombres de las tablas tienen el sufijo de la fecha del calendario de la marca de tiempo UTC de la entrada de registro, con el formato básico ISO 8601 (AAAAMMDD).

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

¹ Las marcas de tiempo de las entradas de registro se expresan en UTC (tiempo universal coordinado).

Crear tablas con particiones

Cuando creas un receptor para enrutar tus registros a BigQuery, puedes usar tablas con particiones por fecha o tablas con particiones. La selección predeterminada es una tabla particionada por fecha:

Para obtener instrucciones sobre cómo crear sinks, consulta los siguientes recursos:

• Google Cloud Consola: Enruta registros a destinos admitidos.

• Google Cloud CLI: gcloud logging sinks create.

Discrepancias en el esquema

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

Se produce un error de incompatibilidad de esquemas cuando se escriben entradas de registro en la tabla de destino y se produce uno de los siguientes errores:

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

  Por ejemplo, si el campo jsonPayload.user_id de la entrada de registro inicial es a string, esa entrada de registro genera una tabla con un tipo de cadena para ese campo. Si más adelante empiezas a registrar jsonPayload.user_id como array, se producirá un error de coincidencia de esquemas.

• Una nueva entrada de registro contiene un campo que no está en el esquema actual y, si se insertara ese campo en la tabla de destino, se superaría el límite de columnas de BigQuery.

  La tabla de destino puede aceptar el nuevo campo si no se supera el límite de columnas.

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

Al enrutar entradas de registro, Logging envía mensajes en lote a BigQuery. BigQuery usa las siguientes reglas para determinar en qué tabla se escriben las entradas de registro del lote actual de mensajes:

• Cuando se produce un cambio en el tipo de campo, solo se escriben en la tabla de errores las entradas de registro que han provocado un error de coincidencia de esquema. Las entradas de registro del lote de mensajes actual que no provocan un error de coincidencia de esquema se escriben en la tabla de destino original.

• Si se supera el límite de columnas, todas las entradas de registro del lote de mensajes actual se escribirán en la tabla de errores.

Error de esquema de tabla

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

• logEntry: contiene la entrada de registro completa, pero se convierte de JSON a una cadena.
• schemaErrorDetail: contiene el mensaje de error completo devuelto por BigQuery.
• sink: contiene la ruta completa del recurso del receptor de registro.
• logName: extraído del LogEntry.
• timestamp: extraído del LogEntry.
• receiveTimestamp: extraído del LogEntry.
• severity: extraído del LogEntry.
• insertId: extraído del LogEntry.
• trace: extraído del LogEntry.
• resourceType: extraído del LogEntry.

El registro comunica las discrepancias de esquema alGoogle Cloud proyecto que contiene el receptor de enrutamiento de las siguientes formas:

• Los propietarios del proyecto reciben un correo. Los detalles incluyen el ID del proyecto, el nombre del sumidero y el destino. Google Cloud
• La página Actividad de la consola muestra un error, Google Cloud .Stackdriver Config error Los detalles incluyen el nombre y el destino del receptor, así como un enlace a un ejemplo de entrada de registro que ha provocado el error.

Evitar que se produzcan errores de tipo de campo en el futuro

Para corregir las discrepancias de tipo de campo en entradas de registro posteriores, corrija el tipo de campo para que coincida con el esquema actual. Para obtener información sobre cómo corregir el tipo de un campo, consulta Cambiar 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 que haya discrepancias en el esquema cuando no puedas cambiar el tipo de un campo, cambia el nombre de la tabla o los parámetros del sumidero para que Logging vuelva a crear la tabla en otro conjunto de datos. Para ver las instrucciones, consulta Gestionar sumideros.

Solución de problemas

Si parece que faltan registros en el destino de tu receptor o sospechas que no está enrutando los registros correctamente, consulta Solucionar problemas con el enrutamiento de registros.

Precios

Cloud Logging no cobra por enrutar registros a un destino compatible, pero es posible que el destino aplique cargos. A excepción del segmento de registros _Required, Cloud Logging cobra por transmitir registros a los segmentos de registros y por el almacenamiento que supere el periodo de conservación predeterminado del segmento de registros.

Cloud Logging no cobra por copiar registros, crear ámbitos de registro ni vistas de analíticas, ni por las consultas enviadas a través de las páginas Explorador de registros o Analíticas de registros.

Para obtener más información, consulte los documentos siguientes:

• Las secciones de Cloud Logging de la página Precios de Observabilidad de Google Cloud.

• Costes al enrutar datos de registro a otros servicios: Google Cloud

  • Precios de Cloud Storage
  • Precios de BigQuery
  • Precios de Pub/Sub
• Se aplican cargos por generar registros de flujo de VPC cuando envías y luego excluyes tus registros de flujo de nube privada virtual de Cloud Logging.