Migrar a Cloud Logging

El registro en los entornos de ejecución de segunda generación es diferente al de los entornos de ejecución de la primera generación. Uno de los mayores cambios cuando se realiza una actualización a entornos de ejecución más nuevos es que el registro preintegrado en App Engine no es compatible con los entornos de ejecución de segunda generación y los registros no están correlacionados de forma automática. Si migras a los entornos de ejecución de segunda generación, debes usar la biblioteca cliente de Cloud Logging.

En esta guía, se describe cómo puedes actualizar tu app para usar Cloud Logging y lograr 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 administración de registros en tiempo real con asistencia para almacenamiento, búsqueda, análisis y supervisión. Cloud Logging recopila los registros de los recurso de Google Cloud de forma automática. También puedes recopilar registros de tus aplicaciones, recursos locales y recursos de otros proveedores de servicios en la nube.

Diferencias clave

En la siguiente tabla, se tratan las diferencias en el registro entre los entornos de ejecución de primera y segunda generación:

	Entornos de ejecución de primera generación	Entornos de ejecución de segunda generación
Registros de solicitudes y apps (también llamados registros de aplicaciones)	App Engine incorpora todos los registros de la app dentro del registro de solicitud. El registro en los entornos de ejecución de primera generación usa el campo protoPayload.line.logMessage del registro de solicitudes para incorporar los registros de la app.	App Engine no incorpora los registros de la app dentro del registro de solicitudes asociado. App Engine omite el atributo protoPayload.line en el registro de solicitud. Los registros de apps se enrutan según tu método de registro: stdout y stderr: Enruta registros 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 cliente de Cloud Logging para Python no está configurada para la correlación, el módulo de registro raíz de Python se enruta a logs/stderr de forma predeterminada.
Visualiza registros en el Explorador de registros	Los entornos de ejecución de primera generación solo contienen un tipo de registro, appengine.googleapis.com/request_log. Cuando expandes un registro de solicitud, puedes ver los registros de la aplicación anidados en él.	Los entornos de ejecución de segunda generación incluyen registros de varios tipos de registros, como registros de solicitudes appengine.googleapis.com/request_log, stdout, stderr, logs/python y muchos más, según la forma en que tu app emita registros. Los registros internos de Google también están disponibles en /var/log/google_init.log. Debido a que los registros de la app no están correlacionados automáticamente con los registros de solicitud, se necesitan pasos adicionales para mostrar la vista anidada de los registros de la solicitud y la app en el explorador de registros. Para obtener más información, consulta Correlaciona los registros de solicitud con los registros de la app y Visualiza los registros correlacionados en el Explorador de registros.
Integración en Cloud Trace	Se integra en Cloud Trace automáticamente para recopilar datos de latencia.	Debes integrar tu app de forma manual en Cloud Trace para recopilar datos sobre la latencia de App Engine. Para obtener más información, consulta Instrumento para Cloud Trace.
Correlación de nivel de error	Registra el error que se genera en los registros de solicitud de App Engine con un nivel de gravedad ERROR. Error Reporting correlaciona de forma automática estos detalles en el panel de Error Reporting.	De forma predeterminada, App Engine no integra Error Reporting en los entornos de ejecución de segunda generación. Para configurar la integración de registros con Error Reporting, consulta Instrumenta las apps con bibliotecas cliente.
Nivel de gravedad	El explorador de registros asigna un nivel de gravedad a los registros de solicitudes y el nivel refleja la gravedad más alta de cualquier entrada de registro de la app que esté correlacionada con la entrada de registro de la solicitud. Por ejemplo, si una solicitud provoca que la app emita una entrada de registro de advertencia, el explorador de registros mostrará un ícono de advertencia junto a la entrada de registro de la solicitud. Cuando expandes la entrada de la solicitud, verás la entrada de registro de advertencia anidada en la entrada de la solicitud.	De forma predeterminada, todos los registros de solicitudes tienen una gravedad de DEFAULT o INFO. Incluso si los registros de solicitud están correlacionados con los registros de la app y el Explorador de registros está configurado para ver registros correlacionados, los registros de solicitud no reflejan la gravedad de los registros de la app asociados.
API de Logservice	La API de Logservice forma parte del SDK de servicios en paquetes.	Se quitó la API de Logservice del SDK de servicios en paquetes. Para obtener más información, consulta la lista de APIs disponibles.

Antes de comenzar la migración

1. Habilita la API de Cloud Logging en el proyecto que contiene la app.

   Habilitar la API

2. Asegúrate de que la app tenga permiso para escribir registros.

   De forma predeterminada, la cuenta de servicio predeterminada de la app tiene permiso para escribir registros.

   Si tu app usa una cuenta de servicio diferente, o si cambiaste 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 en App Engine.

Descripción general del proceso de migración

Para migrar la app con el objetivo de usar Cloud Logging, haz lo siguiente:

1. Instala las bibliotecas cliente de Cloud para Cloud Logging
2. Escribe registros con Cloud Logging
3. Correlaciona los registros de solicitudes con los registros de la app
4. Ver registros
5. Prueba tu app

Instala las bibliotecas cliente de Cloud para Cloud Logging

Si deseas instalar y actualizar tus archivos de configuración, agrega las bibliotecas 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

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

En cada archivo en los que se escriben entradas de registro, haz lo siguiente:

1. Importa la biblioteca 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 objeto de escucha predeterminado como el controlador de registro para el 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()

Después de que se adjunta el controlador, todos los registros a nivel de 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)

Correlaciona los registros de solicitudes con los registros de la app

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

Las apps que usan entornos de ejecución de segunda generación pueden lograr un comportamiento de registro anidado similar al de los entornos de ejecución de primera generación de las siguientes maneras:

• Configura el cliente de Cloud Logging en tu aplicación y correlaciona los registros.
• Usa un identificador trace con stdout y stderr.

El comportamiento del registro en los entornos de ejecución de primera y segunda generación difiere de las siguientes maneras:

• En los entornos de ejecución de primera generación, App Engine incorpora todos los registros de la app emitidos mientras controla una solicitud en el campo protoPayload.line.logMessage del registro de la solicitud. Estos registros se pueden ver en el Explorador de registros a través de appengine.googleapis.com/request_log.

  En la siguiente imagen, se muestran los registros de apps y solicitudes correlacionados en los entornos de ejecución de primera generación:

  

• En los entornos de ejecución de segunda generación, App Engine omite el atributo protoPayload.line en el registro de solicitud. El contenido de los registros de la app no está presente en los registros de solicitud JSON en el Explorador de registros. Cada registro de app aparecerá por separado por su nombre de registro en el Explorador de registros.

  En la siguiente imagen, se muestran registros de apps y solicitudes independientes en los entornos 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 los registros.

Usa el módulo de registro de Python

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

Si ejecutas el método client.setup_logging() al inicio de la aplicación, este método agrega el campo trace y los detalles de la solicitud HTTP a los registros de la app que escribe el módulo logging de Python, como logging.info() ylogging.error(). Estos registros se enrutan a logs/python.

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

Pueden usar stdout y stderr

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

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

Ver registros

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

• Usa el Explorador de registros de Cloud Logging en la consola de Google Cloud.
• Usa la Google Cloud CLI para ver registros mediante gcloud.
• Lee registros de manera programática a través de varios métodos.

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.

   

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:

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:

• Usa un receptor de registros en Pub/Sub y una secuencia de comandos para extraerlos de Pub/Sub.
• Llama a la API de Cloud Logging a través de la biblioteca cliente de tu lenguaje de programación.
• Llama a los extremos de la API de REST de Cloud Logging directamente.

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.

Prueba tu app

La migración se realiza de forma correcta si puedes implementar la app sin errores. Para verificar que Cloud Logging funciona, sigue estos pasos:

1. Ve al Explorador de registros y expande una solicitud de entrada de registro.

   Ir al Explorador de registros

2. Asegúrate de que los registros de la app que genera la aplicación cuando procesa una solicitud estén anidados en el registro de solicitud.

3. Si todos los extremos de tu app funcionan como se espera, usa la división del tráfico para aumentar con lentitud el tráfico de la app actualizada. Supervisa la app de cerca para detectar cualquier problema antes de enrutar más tráfico a la app actualizada.