Migrar a Cloud Logging

El registro en los tiempos de ejecución de segunda generación es diferente al de los tiempos de ejecución de primera generación. Uno de los mayores cambios al actualizar a runtimes más recientes es que el registro preintegrado con App Engine no se admite en los runtimes de segunda generación y los registros no se correlacionan automáticamente. Si vas a migrar a los tiempos de ejecución de segunda generación, debes usar la biblioteca de cliente de Cloud Logging.

En esta guía se describe cómo puedes actualizar tu aplicación para usar Cloud Logging y disfrutar de casi las mismas funciones de filtrado y correlación de registros que estaban disponibles con la integración de registros en App Engine.

Cloud Logging es un sistema de gestión de registros en tiempo real que ofrece almacenamiento, búsqueda, análisis y supervisión. Cloud Logging recoge automáticamente los registros de los recursos de Google Cloud . También puedes recoger registros de tus aplicaciones, recursos locales y recursos de otros proveedores de servicios en la nube.

Diferencias principales

En la siguiente tabla se muestran las diferencias en el registro entre los runtimes de primera y segunda generación:

	Runtimes de primera generación	Runtimes de segunda generación
Registros de solicitudes y de aplicaciones	App Engine inserta todos los registros de la aplicación en el registro de solicitudes. El registro en los tiempos de ejecución de primera generación usa el campo protoPayload.line.logMessage del registro de solicitudes para insertar registros de aplicaciones.	App Engine no inserta registros de aplicaciones en el registro de solicitudes asociado. App Engine omite el atributo protoPayload.line en el registro de solicitudes. Los registros de aplicaciones se enrutan en función del método de registro: stdout y stderr: registra rutas como print() a logs/stdout o logs/stderr. Módulo de registro de Python: después de configurar el cliente de Cloud Logging, enruta todos los registros escritos por el módulo de registro raíz de Python, como logging.info() y logging.error(), a logs/python. Si la biblioteca de cliente de Cloud Logging para Python no está configurada para la correlación, el módulo de registro raíz de Python se dirige a logs/stderr de forma predeterminada.
Ver registros en el explorador de registros	Los tiempos de ejecución de primera generación solo contienen un tipo de registro: appengine.googleapis.com/request_log. Cuando amplías un registro de solicitudes, puedes ver los registros de la aplicación anidados en él.	Los tiempos de ejecución de segunda generación incluyen registros de varios tipos, como los siguientes: Registros de solicitudes en appengine.googleapis.com/request_log y stdout stderr y logs/python, entre otros, en función de cómo emita registros tu aplicación. Los registros internos de Google también están disponibles en /var/log/google_init.log. Como los registros de aplicaciones no se correlacionan automáticamente con los registros de solicitudes, se deben seguir pasos adicionales para mostrar la vista anidada de los registros de solicitudes y de aplicaciones en el Explorador de registros. Para obtener más información, consulta los artículos sobre cómo correlacionar registros de solicitudes con registros de aplicaciones y ver registros correlacionados en el Explorador de registros.
Integración de Cloud Trace	Se integra automáticamente con Cloud Trace para recoger datos de latencia.	Debes integrar manualmente tu aplicación con Cloud Trace para recoger datos de latencia de App Engine. Para obtener más información, consulta el artículo sobre instrumentación de Cloud Trace.
Correlación del nivel de error	Registra el error detectado en los registros de solicitudes de App Engine con un nivel de gravedad ERROR. Error Reporting correlaciona automáticamente estos detalles en el panel de control de Error Reporting.	De forma predeterminada, App Engine no integra Error Reporting en los tiempos de ejecución de segunda generación. Para configurar la integración del registro con Error Reporting, consulta el artículo sobre cómo instrumentar aplicaciones con bibliotecas de cliente .
Nivel de gravedad	Explorador de registros asigna un nivel de gravedad a los registros de solicitudes. Este nivel refleja la gravedad más alta de cualquier entrada de registro de aplicación que esté correlacionada con la entrada de registro de solicitudes. Por ejemplo, si una solicitud provoca que tu aplicación emita una entrada de registro de advertencia, el Explorador de registros mostrará un icono de advertencia junto a la entrada de registro de la solicitud. Si despliega la entrada de la solicitud, verá la entrada del registro de advertencias anidada en la entrada de la solicitud.	De forma predeterminada, todos los registros de solicitudes tienen una gravedad de DEFAULT o INFO. Aunque los registros de solicitudes estén correlacionados con los registros de la aplicación y Explorador de registros esté configurado para ver los registros correlacionados, los registros de solicitudes no reflejan la gravedad de los registros de la aplicación asociados.
API Logservice	La API Logservice forma parte del SDK de servicios empaquetados.	La API Logservice se ha retirado del SDK de servicios agrupados. Para obtener más información, consulta la lista de APIs disponibles.

Antes de empezar la migración

1. Habilita la API Cloud Logging en el proyecto que contiene tu aplicación.

   Activar la API

2. Asegúrate de que tu aplicación tenga permiso para escribir registros.

   De forma predeterminada, la cuenta de servicio predeterminada de tu aplicación tiene permiso para escribir registros.

   Si tu aplicación usa una cuenta de servicio diferente o has cambiado los permisos de la cuenta de servicio predeterminada, asegúrate de que la cuenta que uses tenga el permiso logging.logEntries.create para escribir registros.

3. Familiarízate con los diferentes tipos de registros de App Engine.

Visión general del proceso de migración

Para migrar tu aplicación a Cloud Logging, sigue estos pasos:

1. Instalar las bibliotecas de cliente de Cloud para Cloud Logging
2. Escribir registros con Cloud Logging
3. Correlacionar los registros de solicitudes con los registros de la aplicación
4. Ver registros
5. Probar la aplicación

Instalar las bibliotecas de cliente de Cloud para Cloud Logging

Para instalar y actualizar los archivos de configuración, añade las bibliotecas de cliente de Cloud para Cloud Logging a tu lista de dependencias en el archivo requirements.txt, como se muestra a continuación:

google-cloud-logging

Escribir registros con el módulo de registro estándar de Python

En cada archivo que escriba entradas de registro:

1. Importa la biblioteca de cliente de Cloud Logging.
2. Crea una instancia del cliente de Cloud Logging.
3. Ejecuta el método setup_logging() del cliente de Cloud Logging, que adjunta su listener predeterminado como controlador de registro del registrador raíz de Python.

Por ejemplo:

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

Una vez que se haya adjuntado el controlador, todos los registros de nivel INFO o superior que se emitan en tu aplicación se enviarán a Logging de forma predeterminada:

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

Correlacionar registros de solicitudes con registros de aplicaciones

Algunas funciones que están disponibles en los tiempos de ejecución de primera generación, como la correlación automática de los registros de solicitudes con los registros de aplicaciones, no están disponibles en los tiempos de ejecución de segunda generación.

Las aplicaciones que usan tiempos de ejecución de segunda generación pueden lograr un comportamiento de registro anidado similar al de los tiempos de ejecución de primera generación de dos formas:

• Configurar el cliente de Cloud Logging en tu aplicación y correlacionar registros.
• Usar un identificador trace con stdout y stderr.

El comportamiento de registro en los tiempos de ejecución de primera y segunda generación difiere de las siguientes formas:

• En los runtimes de primera generación, App Engine inserta todos los registros de la aplicación emitidos al gestionar una solicitud en el campo protoPayload.line.logMessage del registro de la solicitud. Estos registros se pueden consultar en el explorador de registros a través de appengine.googleapis.com/request_log.

  En la siguiente imagen se muestran los registros de solicitudes y de aplicaciones correlacionados en los tiempos de ejecución de primera generación:

  

• En los runtimes de segunda generación, App Engine omite el atributo protoPayload.line en el registro de solicitudes. El contenido de los registros de la aplicación no está presente en los registros de solicitudes JSON del Explorador de registros. Cada registro de aplicación aparecerá por separado en Explorador de registros con su nombre de registro.

  En la siguiente imagen se muestran los registros de solicitudes y de aplicaciones independientes en los tiempos de ejecución de segunda generación:

  

En las siguientes secciones se explica cómo usar el cliente de Cloud Logging o el registro estructurado con stdout y stderr para correlacionar registros.

Usar el módulo de registro de Python

Para añadir la correlación de solicitudes a los registros de aplicaciones registrados por el módulo de registro de Python, configura la biblioteca de cliente de Cloud Logging.

Cuando ejecutas el método client.setup_logging() al iniciar la aplicación, este método añade el campo trace y los detalles de la solicitud HTTP a los registros de la aplicación escritos por el módulo logging de Python, como logging.info() y logging.error(). Estos registros se dirigen a logs/python.

App Engine también añade este campo trace al registro de solicitudes asociado, lo que permite ver las entradas de registro correlacionadas en el Explorador de registros.

Usa stdout y stderr

Si usas stdout y stderr para escribir entradas de registro, estas entradas aparecerán en el explorador de registros. Sin embargo, para habilitar el filtrado y la correlación con los registros de solicitudes, debe dar formato a las entradas como un objeto JSON y proporcionar metadatos específicos. Para obtener más información sobre este enfoque, consulta Escribir registros estructurados en stdout y stderr. Este enfoque añade el identificador de seguimiento de la solicitud a los registros de la aplicación de la siguiente forma:

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

Ver registros

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

• Usa Explorador de registros de Cloud Logging en la Google Cloud consola.
• Usa Google Cloud CLI para ver los registros con gcloud.
• Leer registros de forma programática mediante varios métodos.

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.

   

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:

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:

• Usa un sumidero de registro en Pub/Sub y una secuencia de comandos para extraer datos de Pub/Sub.
• Llama a la API Cloud Logging a través de la biblioteca de cliente de tu lenguaje de programación.
• Llama directamente a los endpoints de la API REST de Cloud Logging.

Probar la aplicación

La migración se habrá completado correctamente si puedes desplegar tu aplicación sin errores. Para verificar que Cloud Logging funciona, sigue estos pasos:

1. Ve a Explorador de registros y despliega una entrada de registro de solicitudes.

   Ir a Explorador de registros

2. Asegúrate de que los registros de la aplicación que genera tu aplicación al procesar una solicitud estén anidados en el registro de la solicitud.

3. Si todos los endpoints de tu aplicación funcionan correctamente, usa la división del tráfico para aumentar lentamente el tráfico de tu aplicación actualizada. Monitoriza la aplicación de cerca para detectar cualquier problema antes de dirigir más tráfico a la aplicación actualizada.