Cómo escribir y visualizar registros

En esta página, se describen los registros disponibles para las apps de App Engine y cómo escribir, correlacionar y ver las entradas de registro.

App Engine recopila dos tipos de registros:

  • Registro de solicitudes: Registros de solicitudes enviadas a tu app. De forma predeterminada, App Engine emite de forma automática una entrada de registro para cada solicitud HTTP que recibe una app.

  • Registro de apps: Son entradas de registro que emite una app de App Engine según las entradas de registro que escribes en un framework o archivo compatible.

  • Registro del sistema: Son registros generados por la plataforma que contienen información sobre tu app. Estos registros se escriben en varlog/system.

App Engine envía de forma automática los registros de solicitud y los registros de la app al agente de Cloud Logging.

Escribe registros de apps

App Engine emite registros de forma automática para las solicitudes enviadas a tu app, por lo que no es necesario escribir registros de solicitudes. En esta sección, se explica cómo escribir registros de apps.

Cuando escribes registros de aplicaciones desde tu aplicación de App Engine, Cloud Logging selecciona los registros de forma automática, siempre y cuando los registros se escriban mediante los siguientes métodos:

Realiza la integración de Cloud Logging

Puedes integrar tu app de App Engine en Cloud Logging. Este enfoque te permite usar todas las funciones que ofrece Cloud Logging y solo requiere unas pocas líneas de código específico de Google.

Escribe registros estructurados en stdout y stderr

De forma predeterminada, App Engine usa la biblioteca cliente de Cloud Logging para enviar registros. Sin embargo, este método no admite el registro estructurado. Solo puedes escribir registros estructurados con stdout/stderr. Además, también puedes enviar strings de texto a stdout y stderr. De forma predeterminada, la carga útil del registro es una cadena de texto simple almacenada en el campo textPayload de la entrada de registro. Las strings aparecerán como mensajes en el Explorador de registros, la línea de comandos y la API de Cloud Logging y se asociarán con el servicio y la versión de App Engine que las emitió.

Para obtener más valor de los registros, puedes filtrar estas cadenas en el Explorador de registros por nivel de gravedad. Para filtrar estas cadenas, debes darles formato como datos estructurados. Para ello, debes escribir registros en el formato de una sola línea de JSON serializado. App Engine recoge y analiza esta línea JSON serializada y la coloca en el campo jsonPayload de la entrada de registro en lugar de textPayload.

En el entorno estándar de App Engine, escribir registros estructurados en stdout y stderr no cuenta para las cuotas de transferencia de registros por minuto en la API de Cloud Logging.

Campos JSON especiales en los mensajes

Cuando proporcionas un registro estructurado como un diccionario JSON, algunos campos especiales se quitan de jsonPayload y se escriben en el campo correspondiente en la LogEntry generada, como se describe en la documentación sobre campos especiales.

Por ejemplo, si el JSON incluye una propiedad severity, se quita de jsonPayload y aparece como la severity de la entrada de registro. La propiedad message se usa como el texto de visualización principal de la entrada de registro si está presente.

Correlaciona los registros de solicitudes con los registros de la app

Después de dar formato a las entradas como un objeto JSON y proporcionar metadatos específicos, puedes habilitar el filtrado y la correlación con los registros de solicitudes. Para correlacionar las entradas del registro de solicitudes con las entradas del registro de la app, necesitas el identificador de seguimiento de la solicitud. Sigue las instrucciones para correlacionar los mensajes de registro:

  1. Extrae el identificador de seguimiento del encabezado de la solicitud X-Cloud-Trace-Context.
  2. En la entrada de registro estructurada, escribe el ID en un campo llamado logging.googleapis.com/trace. Para obtener más información sobre el encabezado X-Cloud-Trace-Context, consulta Fuerza el seguimiento de una solicitud.

Para ver los registros correlacionados, consulta Visualiza las entradas de registro correlacionadas en el Explorador de registros.

Ver registros

Puedes ver los registros de la app y solicitar registros de las siguientes maneras:

Usa el Explorador de registros

Puedes ver tu app y solicitar registros con el Explorador de registros:

  1. Ve al Explorador de registros en la consola de Google Cloud:

    Ir al Explorador de registros

  2. Selecciona un proyecto existente de Google Cloud en la parte superior de la página.

  3. En Tipo de recurso, selecciona Aplicación en GAE.

Puedes filtrar el Explorador de registros por servicio y versión de App Engine, además de otros criterios. También puedes buscar los registros de las entradas específicas. Consulta Usa el Explorador de registros para obtener más detalles.

Si envías entradas de texto simples al resultado estándar, no puedes usar el visor de registros para filtrar las entradas de la app por gravedad, ni puedes ver qué registros de la app corresponden a solicitudes específicas. Sin embargo, puedes usar otros tipos de filtros en el Explorador de registros, como el texto y la marca de tiempo.

Visualiza las entradas de registro correlacionadas en el Explorador de registros

Para ver las entradas de registro secundarias correlacionadas con una entrada de registro superior en el Explorador de registros, expande la entrada de registro.

Por ejemplo, para mostrar tu entrada de registro de solicitud de App Engine y las entradas de registro de la aplicación, haz lo siguiente:

  1. En el panel de navegación de la consola de Google Cloud, elige Logging y, luego, Explorador de registros:

    Ir al Explorador de registros

  2. En Tipo de recurso, selecciona Aplicación en GAE.

  3. Para ver y correlacionar los registros de solicitudes, en Nombre del registro, elige request_log. Como alternativa, para correlacionar por registros de solicitud, haz clic en Correlacionar por y elige request_log.

    Correlacionar registros

  4. En el panel Resultados de la consulta, para expandir una entrada de registro, haz clic en Expandir. En la expansión, cada registro de solicitud mostrará los registros de la app asociados.

Después de crear un filtro para los registros, cada registro de solicitud muestra los registros de la app correspondientes como registros secundarios. El explorador de registros lo logra a través de la correlación del campo trace en los registros de la app con un registro de solicitud determinado, si la aplicación usa la biblioteca google-cloud-logging.

En la siguiente imagen, se muestran los registros de la app agrupados por el campo trace:

Las entradas del registro de la app se anidan en la entrada del registro de la solicitud.

Usa Google Cloud CLI.

Si deseas ver los registros de App Engine desde la línea de comandos, usa el siguiente comando:

gcloud app logs tail

Para obtener más información, consulta el comando gcloud app logs tail.

Lee registros de manera programática

Si deseas leer los registros de manera programática, puedes usar uno de estos métodos:

Información sobre los registros de escalamiento de instancias

Cuando se inician instancias nuevas para tu app, Cloud Logging incluye entradas de registro con el nombre de registro varlog/system para reflejar por qué se creó cada instancia. La entrada de registro sigue este formato:

Starting new instance. Reason: REASON - DESCRIPTION

En la siguiente tabla, se proporciona un desglose de las descripciones de las instancias:

Motivo Descripción
CUSTOMER_MIN_INSTANCE Es la instancia mínima configurada por el cliente para la app.
SCHEDULED La instancia se inició debido a los factores de escalamiento configurados (p.ej., uso de CPU, capacidad de procesamiento de solicitudes, etc.) y sus objetivos.
OVERFLOW Se inició la instancia porque no se encontró capacidad existente para el tráfico actual.

Política de retención de registros, precios y cuotas

Para obtener información sobre los precios que se aplican a los registros de las solicitudes y de las apps, consulta los precios de Cloud Logging.

Para conocer la política de retención de registros y el tamaño máximo de las entradas de registro, consulta Cuotas y límites. Si quieres almacenar los registros por un período más largo, puedes exportarlos a Cloud Storage. También puedes exportar registros a BigQuery y Pub/Sub para su procesamiento posterior.

Administra el uso de recursos de registros

Puedes controlar la cantidad de actividad de registro de los registros de tu app si escribes una cantidad mayor o menor de entradas desde el código de la app. Los registros de solicitudes se crean de forma automática, por lo que, para administrar la cantidad de entradas del registro de solicitudes asociadas con tu app, usa la función de exclusión de registros de Cloud Logging.

Problemas conocidos

Los siguientes son algunos problemas de registro en los entornos de ejecución de segunda generación:

  • En ocasiones, las entradas de registros de la app no están correlacionadas con el registro de solicitud. Esto sucede la primera vez que la app recibe una solicitud y en cualquier otro momento que App Engine escriba mensajes de estado en el registro de la app. Para obtener más información, consulta https://issuetracker.google.com/issues/138365527.

  • Cuando enrutas registros del receptor de registros a Cloud Storage, el destino de Cloud Storage solo contiene registros de solicitud. App Engine escribe registros de aplicaciones en diferentes carpetas.

  • BigQuery no puede transferir registros debido al campo @type en los registros de solicitud. Esto interrumpe la detección del esquema automático, ya que BigQuery no permite @type en los nombres de campo. Para resolver esto, debes definir el esquema de forma manual y quitar el campo @type de los registros de solicitudes.

  • Si usas las APIs de REST de registro, un subproceso en segundo plano escribe registros en Cloud Logging. Si el subproceso principal no está activo, la instancia no obtiene tiempo de CPU, lo que hace que se detenga el subproceso en segundo plano. El tiempo de procesamiento de registros está demorado. En algún momento, la instancia se quita y se pierden los registros no enviados. Para evitar perder registros, usa una de las siguientes opciones:

    • Configura el SDK de Cloud Logging para usar gRPC. Con gRPC, los registros se envían a Cloud Logging de inmediato. Sin embargo, esto puede aumentar los límites de CPU requeridos.
    • Envía mensajes de registro a Cloud Logging mediante stdout/stderr. Esta canalización está fuera de la instancia de App Engine y no se limita.

¿Qué sigue?

  • Consulta Supervisa y alerta sobre la latencia a fin de obtener información sobre cómo usar Cloud Logging para ver los registros de depuración de errores y cómo usar Cloud Trace para comprender la latencia de la app.