Usa registros exportados

En esta página, se explica cómo puedes encontrar y usar las entradas de registro exportadas en Cloud Storage, BigQuery y Pub/Sub.

Para obtener una descripción general conceptual de la exportación de registros mediante Stackdriver Logging, consulta Descripción general de las exportaciones de registros.

Para obtener instrucciones sobre cómo exportar los registros mediante Logging, ve a las siguientes páginas:

Cloud Storage

Para ver los registros exportados en Cloud Storage, haz lo siguiente:

  1. Ve al navegador de Cloud Storage en Cloud Console:

    Ir al navegador de Cloud Storage

  2. Selecciona el depósito que usarás para la exportación de registros.

Para obtener detalles sobre cómo se organizan los registros en el depósito, consulta la sección sobre organización de Cloud Storage en esta página.

Disponibilidad de registros exportados

Si no hay registros exportados, consulta las métricas del sistema de exportación. Estas métricas del sistema de exportación te pueden decir cuántas entradas de registro se exportan y cuántas se descartan debido a errores. Si las métricas del sistema de exportación indican que no se exportaron entradas de registro, revisa tu consulta de exportación para verificar que las entradas de registro que coincidan con tu consulta hayan llegado recientemente a Logging:

Ir a Exportación de registros

Las entradas de registro se guardan en depósitos de Cloud Storage en lotes por hora. Es posible que se necesiten entre 2 y 3 horas para que aparezcan las primeras entradas.

Organización de registros exportados

Cuando exportas registros a un depósito de Cloud Storage, Logging escribe un conjunto de archivos en el depósito. En el directorio, los archivos tienen una organización jerárquica según el tipo de registro y fecha. El tipo de registro, denominado [LOG_ID] en la referencia LogEntry, puede ser un nombre simple como syslog o un nombre compuesto como appengine.googleapis.com/request_log. Si estos registros se almacenan en un depósito llamado my-gcs-bucket, los directorios se nombrarán como en el siguiente ejemplo:

my-gcs-bucket/syslog/YYYY/MM/DD/
my-gcs-bucket/appengine.googleapis.com/request_log/YYYY/MM/DD/

Un único depósito puede contener registros de varios tipos de recursos.

Logging no garantiza que se anule la duplicación de las entradas de registro de los receptores que contienen consultas idénticas o superpuestas. Las entradas de registro de esos receptores se pueden escribir varias veces en un depósito de Cloud Storage.

Los directorios hoja (DD/) tienen varios archivos, cada uno de los cuales contiene las entradas de registro exportadas durante un período especificado en el nombre del archivo. Los archivos están fragmentados y sus nombres terminan en un número de fragmento, Sn o An (n=0,  1, 2, …). Por ejemplo, aquí hay dos archivos que podrían almacenarse dentro del directorio my-gcs-bucket/syslog/2015/01/13/:

08:00:00_08:59:59_S0.json
08:00:00_08:59:59_S1.json

Estos dos archivos juntos contienen las entradas de registro syslog correspondientes a todas las instancias durante la hora que comienza a las 0800 UTC. Las marcas de tiempo de las entradas de registro se expresan en UTC (Horario universal coordinado).

A fin de obtener todas las entradas de registro, debes leer todos los fragmentos de cada período; en este caso, los fragmentos de archivos 0 y 1. La cantidad de fragmentos de archivos escritos puede cambiar para cada período en función de la cantidad de entradas de registro.

Dentro de los archivos fragmentados individuales, las entradas de registro se almacenan como una lista de objetos LogEntry. Para ver un ejemplo de una entrada syslog, ve a Objetos de entrada de registro en esta página.

Ten en cuenta que el orden de clasificación de las entradas de registro en los archivos no es uniforme ni está garantizado de alguna otra manera.

Consultas

Si quieres ver ejemplos de consultas para exportar registros a Cloud Storage, ve a la página de ejemplos de consultas.

BigQuery

Para ver los registros exportados en BigQuery, haz lo siguiente:

  1. Ve a la IU de BigQuery en Cloud Console:

    Ir a BigQuery

  2. Selecciona el conjunto de datos que usas como destino de tu receptor.

  3. Selecciona una de las tablas del 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.

Para obtener más información, consulta la sección Organización en tablas si quieres aprender cómo se organizan las tablas y Esquema de BigQuery de registros exportados para saber cómo se nombran los campos de entradas de registros exportados.

Disponibilidad de registros exportados

Si no hay registros exportados, consulta las métricas del sistema de exportación. Estas métricas del sistema de exportación te pueden decir cuántas entradas de registro se exportan y cuántas se descartan debido a errores. Si las métricas del sistema de exportación indican que no se exportaron entradas de registro, revisa tu consulta de exportación para verificar que las entradas de registro que coincidan con tu consulta hayan llegado recientemente a Logging:

Ir a Exportaciones de registros

Cuando se crea una tabla nueva, Logging exporta las entradas de registro a BigQuery, es posible que transcurran varios minutos hasta que las primeras entradas de registro aparezcan en la tabla nueva. Las entradas de registro posteriores suelen aparecer en un minuto. Para obtener más información, consulta la sección sobre Organización de la tabla a continuación.

Organización de la tabla

Cuando exportas registros a un conjunto de datos de BigQuery, Logging crea tablas con fecha para contener las entradas de registro exportadas. Las entradas de registro se ubican en tablas cuyos nombres se basan en los nombres de registro y las marcas de tiempo de las entradas1. En la siguiente tabla, se muestran ejemplos sobre cómo se asignan los nombres de registros y las marcas de tiempo a los nombres de la tabla:

Nombre del registro Marca de tiempo de la entrada del registro1. Nombre de la tabla de BigQuery
syslog 2017-05-23T18:19:22.135Z syslog_20170523
apache-access 2017-01-01T00:00:00.000Z apache_access_20170101
compute.googleapis.com/activity_log 2017-12-31T23:59:59.999Z compute_googleapis_com_activity_log_20171231

1 Las marcas de tiempo de las entradas de registro se expresan en UTC (Horario universal coordinado)

Esquemas y campos

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. Para ver el esquema de la tabla, selecciona una tabla con entradas de registro exportadas en la IU web de BigQuery.

El esquema de la tabla de BigQuery que se usa para representar cargas útiles de entradas de registro complejas puede ser confuso y, en el caso de registros de auditoría exportados, se usan algunas reglas especiales de denominación. Para obtener más información, consulta el Esquema de BigQuery para los registros exportados.

Consultas

Si quieres ver ejemplos de consultas para exportar registros a BigQuery, ve a la página de ejemplos de consultas.

Para obtener más información sobre la sintaxis de consulta de BigQuery, revisa la referencia de consultas. Las funciones comodín de tablas, que permiten realizar consultas en varias tablas, y el operador Flatten, que te permite mostrar datos de campos repetidos, son de gran utilidad.

Una consulta de registros de Compute Engine de ejemplo

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 syslog y apache-access. La consulta se hizo el 23 de febrero de 2015 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  | 2015-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  | 2015-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  | 2015-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2015:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2015-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  | 2015-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2015:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

Una consulta de registros de App Engine de ejemplo

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  | 2015-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2015-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2015-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2015-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

Pub/Sub

Para ver tus registros exportados mientras se transmiten a través de Pub/Sub, haz lo siguiente:

  1. Ve a la página Pub/Sub en Cloud Console:

    Ir a Pub/Sub

  2. Encuentra o crea una suscripción al tema usado para la exportación de registros y extrae una entrada de registro de ella. Es posible que tengas que esperar a que se publique una nueva entrada de registro.

Para obtener detalles sobre cómo se organizan los registros, ve a la sección sobre Organización de registros exportados en esta página.

Disponibilidad de registros exportados

Si no hay registros exportados, consulta las métricas del sistema de exportación. Estas métricas del sistema de exportación te pueden decir cuántas entradas de registro se exportan y cuántas se descartan debido a errores. Si las métricas del sistema de exportación indican que no se exportaron entradas de registro, revisa tu consulta de exportación para verificar que las entradas de registro que coincidan con tu consulta hayan llegado recientemente a Logging:

Ir a Exportación de registros

Cuando exportas registros a un tema de Pub/Sub, Logging publica cada entrada de registro como un mensaje de Pub/Sub ni bien las recibe.

Organización de registros exportados

El campo data de cada mensaje es un objeto LogEntry codificado en base64. Por ejemplo, un suscriptor de Pub/Sub puede extraer el siguiente objeto de un tema que recibe entradas de registro. El objeto que se muestra contiene una lista con un solo mensaje, aunque Pub/Sub podría mostrar varios mensajes si hay varias entradas de registro disponibles. El valor data (alrededor de 600 caracteres) y el valor ackId (alrededor de 200 caracteres) se acortaron para facilitar la lectura del ejemplo:

{
 "receivedMessages": [
  {
   "ackId": "dR1JHlAbEGEIBERNK0EPKVgUWQYyODM...QlVWBwY9HFELH3cOAjYYFlcGICIjIg",
   "message": {
    "data": "eyJtZXRhZGF0YSI6eyJzZXZ0eSI6Il...Dk0OTU2G9nIjoiaGVsbG93b3JsZC5sb2cifQ==",
    "attributes": {
     "compute.googleapis.com/resource_type": "instance",
     "compute.googleapis.com/resource_id": "123456"
    },
    "messageId": "43913662360"
   }
  }
 ]
}

Si decodificas el campo data y lo formateas, obtienes el siguiente objeto LogEntry:

{
  "log": "helloworld.log",
  "insertId": "2015-04-15|11:41:00.577447-07|10.52.166.198|-1694494956",
  "textPayload": "Wed Apr 15 20:40:51 CEST 2015 Hello, world!",
  "timestamp": "2015-04-15T18:40:56Z",
  "labels": {
    "compute.googleapis.com\/resource_type": "instance",
    "compute.googleapis.com\/resource_id": "123456"
  },
  "severity": "WARNING"
  }
}

Integración de terceros con Pub/Sub

Logging admite la integración de registros con terceros. Para ver una lista actual de integraciones, ve a Integraciones de Google Stackdriver.

Exporta tus registros a través de un tema de Pub/Sub y el tercero recibe tus registros cuando se suscribe al mismo tema.

A fin de realizar la integración, prepárate para realizar pasos como los siguientes:

  1. Obtén del tercero un nombre de cuenta de servicio de Google Cloud creado a partir de su proyecto de Google Cloud. Por ejemplo, 12345-xyz@developer.gserviceaccount.com. Usarás este nombre para darle permiso al tercero de recibir tus registros.

  2. En el proyecto que contiene los registros, usa

  3. Habilita lasPub/SubAPI.

    Habilita lasAPI

  4. Crea un tema de Pub/Sub. A fin de hacer esto, configura un receptor de registro o sigue estos pasos:

    1. Ve a la lista de temas de Pub/Sub.
    2. Selecciona Crear tema y, a continuación, ingresa un nombre de tema. Por ejemplo, projects/my-project-id/topics/my-pubsub-topic. Exportarás tus registros a este tema.

      Cada mensaje enviado al tema incluye la marca de tiempo de la entrada de registro exportada en el mensaje de Pub/Sub attributes; por ejemplo:

      "attributes": {
        "logging.googleapis.com/timestamp": "2018-10-01T00:00:00Z"
      }
      
    3. Haz clic en Crear.

    4. Autoriza a Logging para exportar registros al tema. Para obtener instrucciones, consulta información sobre cómo establecer permisos de Pub/sub.

  5. Autoriza al tercero a suscribirse a tu tema:

    1. Permanece en la lista de temas de Pub/Sub de tu proyecto en Cloud Console.
    2. Selecciona tu nuevo tema.
    3. Selecciona Permisos.
    4. Ingresa el nombre de la cuenta de servicio del tercero.
    5. En el menú Selecciona una función, selecciona Suscriptor de Pub/Sub.
    6. Haz clic en Agregar.
  6. Proporciona al tercero el nombre de tu tema de Pub/Sub por ejemplo, projects/my-project-number/topics/my-pubsub-topic. Debe suscribirse al tema antes de que tú comiences la exportación.

  7. Comienza a exportar los registros una vez que el tercero se haya suscrito al tema:

    1. En el proyecto que contiene los registros que deseas exportar, haz clic en Crear exportación encima del cuadro de búsqueda. Esto abrirá el panel Editar exportación (Edit Export):

      Edita el panel de exportación

    2. Ingresa un Nombre del receptor (Sink Name).

    3. En el menú Servicio del receptor (Sink Service), selecciona Cloud Pub/Sub.

    4. En el menú Destino del receptor (Sink Destination) selecciona el tema de Pub/Sub al que está suscrito el tercero.

    5. Selecciona Crear receptor (Create Sink) para comenzar la exportación.

    6. Aparecerá un cuadro de diálogo con la leyenda Se creó el receptor. Esto indica que tu receptor de exportación se creó correctamente con permisos para escribir futuros registros coincidentes con el destino que seleccionaste.

El tercero debería comenzar a recibir las entradas de los registros de inmediato.

Objetos de entradas de registro

Las entradas del registro son objetos del tipo LogEntry.

Las entradas de registro con el mismo tipo de registro, denominado [LOG_ID] en la referencia LogEntry, suelen tener el mismo formato. En la siguiente tabla, se muestran ejemplos de entradas de registro:

syslog

syslog de Compute Engine es un tipo de registro personalizado que crea el agente de registro, google-fluentd, que se ejecuta en instancias de máquinas virtuales:

{
  logName: "projects/my-gcp-project-id/logs/syslog",
  timestamp: "2015-01-13T19:17:01Z",
  resource: {
    type: "gce_instance",
    labels: {
      instance_id: "12345",
      zone: "us-central1-a",
      project_id: "my-gcp-project-id"
    }
  },
  insertId: "abcde12345",
  textPayload: "Jan 13 19:17:01 my-gce-instance /USR/SBIN/CRON[29980]: (root) CMD (   cd / && run-parts --report /etc/cron.hourly)"
}

request_log

El request_log de App Engine tiene entradas de registro que contienen campos protoPayload que comprenden objetos de tipo RequestLog:

{
  logName: "projects/my-gcp-project-id/logs/appengine.googleapis.com%2Frequest_log",
  timestamp: "2015-01-13T19:00:39.796169Z",
  resource: {
    type: "gae_app",
    labels: {
      module_id: "default",
      zone: "us6",
      project_id: "my-gcp-project-id",
      version_id: "20150925t173233"
    }
  }
  httpRequest: {
    status: 200
  }
  insertId: "abcde12345",
  operation: {
    id: "abc123",
    producer: "appengine.googleapis.com/request_id",
    first: true,
    last: true
  }
  protoPayload: {
    @type: "type.googleapis.com/google.appengine.logging.v1.RequestLog"
    versionId: "20150925t173233",
    status: 200,
    startTime: "2017-01-13T19:00:39.796169Z",
    # ...
    appId: "s~my-gcp-project-id",
    appEngineRelease: "1.9.17",
  }
}

activity

El registro activity es un registro de auditoría de la actividad del administrador. Su carga útil es una representación JSON del tipo AuditLog:

{
 logName: "projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity"
 timestamp: "2017-04-22T13:41:32.245Z"
 severity: "NOTICE"
 resource: {
  type: "gce_instance"
  labels: {
   instance_id: "2403273232180765234"
   zone: "us-central1-b"
   project_id: "my-gcp-project-id"
  }
 }
 insertId: "54DC1882F4B49.A4996C2.6A02F4C1"
 operation: {
  id: "operation-1492868454262-54dc185e9a4f0-249fe233-f73d472a"
  producer: "compute.googleapis.com"
  last: true
 }
 protoPayload: {
  @type: "type.googleapis.com/google.cloud.audit.AuditLog"
  authenticationInfo: {
   principalEmail: "649517127304@cloudservices.gserviceaccount.com"
  }
  requestMetadata: {…}
  serviceName: "compute.googleapis.com"
  methodName: "v1.compute.instances.delete"
  resourceName: "projects/my-gcp-project-id/zones/us-central1-b/instances/abc123"
 }
}

Entradas de registro tardías

Las entradas de registro exportadas se guardan en depósitos de Cloud Storage en lotes por hora. Es posible que se necesiten entre 2 y 3 horas para que aparezcan las primeras entradas. Los fragmentos de archivo de registro exportados con el sufijo An (“Append”) contienen las entradas de registro que llegaron tarde.

Si el destino de exportación experimenta una interrupción, Stackdriver Logging almacena en búfer los datos hasta que la interrupción finaliza.

Además, App Engine combina varias subentradas de tipo google.appengine.logging.v1.LogLine (también llamadas AppLog o AppLogLine) en una entrada de registro principal de tipo google.appengine.logging.v1.RequestLog para la solicitud que provoca la actividad de registro. Cada línea de registro cuenta con un "ID de solicitud" que define la entrada principal. El visor de registros muestra las líneas de registros con la entrada de registro de la solicitud. Logging intenta colocar todas las líneas de registro en el lote con la solicitud original, incluso si por sus marcas de tiempo se colocarían en el siguiente lote. Si eso no es posible, a la entrada del registro de la solicitud pueden faltarle algunas líneas de registro y es posible que existan líneas de registro “huérfanas” sin solicitud en el siguiente lote. Si esta posibilidad te parece importante, prepárate para volver a conectar las partes de la solicitud cuando proceses los registros.

Precios

Los registros exportados no incurren en cargos de Stackdriver Logging, pero es posible que se apliquen cargos de destino. Para obtener más información, revisa la página de precios del producto correspondiente:

Ten en cuenta que si envías y, luego, excluyes los registros de flujo de la nube privada virtual en Stackdriver Logging, se aplicarán cargos por generación de los registros de flujo de VPC además de los cargos de destino.