Escribir y ver registros

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

App Engine recoge dos tipos de registros:

  • Registro de solicitudes: registros de las solicitudes enviadas a tu aplicación. De forma predeterminada, App Engine emite automáticamente una entrada de registro por cada solicitud HTTP que recibe una aplicación.

  • Registro de la aplicación: entradas de registro emitidas por una aplicación de App Engine en función de las entradas de registro que escribas en un framework o archivo compatible.

App Engine envía automáticamente los registros de solicitudes y los registros de aplicaciones al agente de Cloud Logging.

Escribir registros de aplicaciones

App Engine emite automáticamente registros de las solicitudes enviadas a tu aplicación, por lo que no es necesario que escribas registros de solicitudes. En esta sección se explica cómo escribir registros de aplicaciones.

Cuando escribes registros de aplicaciones desde tu aplicación de App Engine, Cloud Logging los recoge automáticamente, siempre que se escriban con los siguientes métodos:

Integración con Cloud Logging

Puedes integrar tu aplicación de App Engine con 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.

Escribir registros estructurados en stdout y stderr

De forma predeterminada, App Engine usa la biblioteca de 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 cadenas de texto a stdout y stderr. De forma predeterminada, la carga útil del registro es una cadena de texto almacenada en el campo textPayload de la entrada de registro. Las cadenas se muestran como mensajes en el Explorador de registros, en la línea de comandos y en la API Cloud Logging, y están asociadas al servicio y a la versión de App Engine que las ha emitido.

Para obtener más valor de los registros, puede filtrar estas cadenas en Explorador de registros por nivel de gravedad. Para filtrar estas cadenas, debe darles el formato de datos estructurados. Para ello, escribe los registros en forma 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 se tiene en cuenta en la cuota de solicitudes de ingestión de registros por minuto de la API Cloud Logging.

Campos JSON especiales en mensajes

Cuando proporcionas un registro estructurado como un diccionario JSON, se eliminan algunos campos especiales del jsonPayload y se escriben en el campo correspondiente del LogEntry generado, tal como se describe en la documentación de los campos especiales.

Por ejemplo, si tu JSON incluye una propiedad severity, se elimina del jsonPayload y aparece en su lugar como severity de la entrada de registro. La propiedad message se usa como texto principal de la entrada de registro, si está presente.

Correlacionar registros de solicitudes con registros de aplicaciones

Una vez que hayas formateado las entradas como un objeto JSON y hayas proporcionado metadatos específicos, podrás 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 aplicación, necesitas el identificador de seguimiento de la solicitud. Sigue las instrucciones para correlacionar mensajes de registro:

  1. Extrae el identificador de seguimiento del encabezado de 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 Forzar el seguimiento de una solicitud.

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

Ver registros

Puedes ver los registros de aplicaciones y de solicitudes de varias formas:

Usar el explorador de registros

Puedes ver los registros de tu aplicación y de las solicitudes mediante el Explorador de registros:

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

    Ir a Explorador de registros

  2. En la parte superior de la página, selecciona un Google Cloud proyecto.

  3. En Resource Type (Tipo de recurso), selecciona GAE Application (Aplicación de GAE).

Puede filtrar Explorador de registros por servicio, versión y otros criterios de App Engine. También puedes buscar entradas específicas en los registros. Para obtener más información, consulta el artículo Usar el Explorador de registros.

Si envía entradas de texto simples a la salida estándar, no podrá usar el visor de registros para filtrar las entradas de la aplicación por gravedad ni ver qué registros de la aplicación corresponden a solicitudes específicas. Puedes seguir usando otros tipos de filtros en el Explorador de registros, como texto y marca de tiempo.

Ver entradas de registro correlacionadas en el explorador de registros

En Explorador de registros, para ver las entradas de registro secundarias correlacionadas con una entrada de registro principal, amplía la entrada de registro.

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

  1. En el panel de navegación de la Google Cloud consola, selecciona Logging y, a continuación, Explorador de registros:

    Ir a Explorador de registros

  2. En Resource Type (Tipo de recurso), selecciona GAE Application (Aplicación de GAE).

  3. Para ver y correlacionar los registros de solicitudes, en Nombre de registro, selecciona request_log. También puede correlacionar por registros de solicitudes. Para ello, haga clic en Correlacionar por y seleccione request_log.

    Correlacionar registros

  4. En el panel Resultados de la consulta, para desplegar una entrada de registro, haz clic en Desplegar. Al desplegarlo, cada registro de solicitudes mostrará los registros de aplicaciones asociados.

Después de crear un filtro para los registros, cada registro de solicitudes muestra los registros de aplicaciones correspondientes como registros secundarios. Explorador de registros lo consigue correlacionando el campo trace de los registros de aplicaciones y un registro de solicitudes determinado, siempre que la aplicación use la biblioteca google-cloud-logging.

En la siguiente imagen se muestran los registros de la aplicación agrupados por el campo trace:

Las entradas de registro de la aplicación se anidan en la entrada de registro de la solicitud.

Usar Google Cloud CLI

Para 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 gcloud app logs tail.

Leer registros mediante programación

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

Precios, cuotas y política de conservación de registros

Para obtener información sobre los precios que se aplican tanto a los registros de solicitudes como a los de aplicaciones, consulta la página Precios de Cloud Logging.

Para consultar la política de conservación de registros y el tamaño máximo de las entradas de registro, consulta Cuotas y límites. Si quieres almacenar tus registros durante más tiempo, puedes exportarlos a Cloud Storage. También puedes exportar tus registros a BigQuery y Pub/Sub para procesarlos más adelante.

Gestionar el uso de recursos de registro

Puedes controlar la cantidad de actividad de registro de los registros de tu aplicación escribiendo más o menos entradas en el código de tu aplicación. Los registros de solicitudes se crean automáticamente, por lo que, para gestionar el número de entradas de registro de solicitudes asociadas a tu aplicación, usa la función de exclusión de registros de Cloud Logging.

Problemas conocidos

A continuación se indican algunos problemas de registro en los tiempos de ejecución de segunda generación:

  • A veces, las entradas de registro de la aplicación no se correlacionan con el registro de solicitudes. Esto ocurre la primera vez que tu aplicación recibe una solicitud y cada vez que App Engine escribe mensajes de estado en el registro de tu aplicación. Para obtener más información, consulta https://issuetracker.google.com/issues/138365527.

  • Cuando enrutas registros de un sumidero de registros a Cloud Storage, el destino de Cloud Storage solo contiene registros de solicitudes. App Engine escribe los registros de aplicaciones en carpetas diferentes.

  • BigQuery no puede ingerir registros debido al campo @type de los registros de solicitudes. Esto interrumpe la detección automática de esquemas, ya que BigQuery no permite el carácter @type en los nombres de los campos. Para solucionar este problema, debe definir manualmente el esquema y quitar el campo @type de los registros de solicitudes.

  • Si usas las APIs REST de registro, un subproceso en segundo plano escribe los registros en Cloud Logging. Si el hilo principal no está activo, la instancia no obtiene tiempo de CPU, lo que provoca que el hilo en segundo plano se detenga. El tiempo de procesamiento de los registros se retrasa. En algún momento, la instancia se elimina y se pierden los registros no enviados. Para evitar que se pierdan los 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 inmediatamente. Sin embargo, esto puede aumentar los límites de CPU necesarios.
    • 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.

Siguientes pasos

  • Consulta Monitorizar y alertar sobre la latencia para saber cómo usar Cloud Logging para ver los registros y depurar errores, y cómo usar Cloud Trace para comprender la latencia de las aplicaciones.