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:
|
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
Habilita la API de Cloud Logging en el proyecto que contiene la app.
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.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:
- Instala las bibliotecas cliente de Cloud para Cloud Logging
- Escribe registros con Cloud Logging
- Correlaciona los registros de solicitudes con los registros de la app
- Ver registros
- 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:
- Importa la biblioteca cliente de Cloud Logging.
- Crea una instancia del cliente de Cloud Logging.
- 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:
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:
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
constdout
ystderr
.
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 deappengine.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:
- Extrae el identificador de seguimiento del encabezado de la solicitud
X-Cloud-Trace-Context
. - 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 encabezadoX-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:
Ve al Explorador de registros en la consola de Google Cloud:
Selecciona un proyecto existente de Google Cloud en la parte superior de la página.
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:
En el panel de navegación de la consola de Google Cloud, elige Logging y, luego, Explorador de registros:
En Tipo de recurso, selecciona Aplicación en GAE.
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.
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.
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:
Ve al Explorador de registros y expande una solicitud de entrada de registro.
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.
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.