Escribe y consulta entradas de registro con una secuencia de comandos de Python
En esta guía de inicio rápido, se presentan algunas de las funciones de Cloud Logging y se indica cómo hacer lo siguiente:
- Escribir entradas de registro con una secuencia de comandos Python
- Visualizar entradas de registro con una secuencia de comandos Python
- Borrar entradas de registro con una secuencia de comandos Python
- Enrutar los registros a un bucket de Cloud Storage
Logging puede enrutar entradas de registro a los siguientes destinos:
- Buckets de Cloud Storage
- Conjuntos de datos de BigQuery
- Pub/Sub
- Buckets de Logging
- Proyectos de Google Cloud
Antes de comenzar
Debes tener un proyecto de Google Cloud con la facturación habilitada para completar esta guía de inicio rápido. Si no tienes un proyecto de Google Cloud o si no tienes la facturación habilitada para el proyecto de Google Cloud, haz lo siguiente:- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
En esta guía de inicio rápido, se usa Cloud Logging y Cloud Storage. El uso de estos recursos puede generar gastos. Cuando finalices esta guía de inicio rápido, puedes borrar los recursos que creaste para evitar que continúe la facturación. Para obtener más detalles, consulta Realiza una limpieza en esta página.
Primeros pasos
Puedes usar el entorno de Cloud Shell o un entorno genérico de Linux para completar esta guía de inicio rápido. Python está preinstalado en Cloud Shell.
Cloud Shell
Abre Cloud Shell y verifica la configuración de tu proyecto de Google Cloud:
En la consola de Google Cloud, haz clic en Activar Cloud Shell:
Se abre Cloud Shell en una ventana y muestra un mensaje de bienvenida:
El mensaje de bienvenida repite el ID del proyecto de Google Cloud configurado. Si este no es el proyecto de Google Cloud que deseas usar, ejecuta el siguiente comando después de reemplazar PROJECT_ID por el ID de tu proyecto:
gcloud config set project PROJECT_ID
Linux
Asegúrate de que Python esté instalado y configurado. Si deseas obtener información sobre cómo preparar tu máquina para el desarrollo en Python, consulta Cómo configurar un entorno de desarrollo de Python.
Instala la biblioteca cliente de Cloud Logging:
pip install --upgrade google-cloud-logging
Configura los permisos de Identity and Access Management para tu proyecto de Google Cloud. En los siguientes pasos, debes crear una cuenta de servicio para el proyecto de Google Cloud y, luego, generar y descargar un archivo en la estación de trabajo de Linux.
-
En el panel de navegación de la consola de Google Cloud, selecciona IAM y administración y, luego, Cuentas de servicio:
Selecciona el proyecto de la guía de inicio rápido de Google Cloud y, luego, haz clic en Crear cuenta de servicio:
- Ingresa el nombre de la cuenta.
- Ingresa una descripción de la cuenta.
- Haz clic en Crear y continuar.
Haz clic en el campo Selecciona un rol y elige Administrador de Logging.
Haz clic en Listo para terminar de crear la cuenta de servicio.
Crea un archivo de claves y descárgalo en tu estación de trabajo:
- Para la cuenta de servicio, haz clic en more_vert Más opciones y selecciona Administrar claves.
- En el panel Claves, haz clic en Agregar clave.
- Haga clic en Crear clave nueva.
Para el tipo de clave, selecciona JSON y haz clic en Crear. Tras unos instantes, aparecerá una ventana emergente con un mensaje similar al que se mostró antes:
-
En tu estación de trabajo Linux, proporciona credenciales de autenticación a tu aplicación configurando la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
con la ruta hacia tu archivo de claves. Por ejemplo:export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"
Esta variable de entorno solo se aplica a la sesión actual del shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.
Clona la fuente
Para configurar Cloud Shell en esta guía de inicio rápido, haz lo siguiente:
Clona el proyecto
python-logging
de GitHub:git clone https://github.com/googleapis/python-logging
El directorio
samples/snippets
contiene las dos secuencia de comandos que se usan en esta guía de inicio rápido:snippets.py
te permite administrar entradas en un registro.export.py
te permite administrar las exportaciones de registros.
Cambia al directorio
snippets
:cd python-logging/samples/snippets
Escribe entradas de registro
La secuencia de comandos snippets.py
usa las bibliotecas cliente de Python para escribir entradas de registro en Logging. Cuando se especifica la opción write
en la línea de comandos, la secuencia de comandos escribe las siguientes entradas de registro:
- Una entrada con datos no estructurados y sin nivel de gravedad especificado
- Una entrada con datos no estructurados y un nivel de gravedad de
ERROR
- Una entrada con datos estructurados JSON y sin nivel de gravedad especificado
Para escribir entradas de registro nuevas en el registro my-log
, ejecuta la secuencia de comandos snippets.py
con la opción write
:
python snippets.py my-log write
Visualiza entradas de registro
Para ver las entradas de registro en Cloud Shell, ejecuta la secuencia de comandos snippets.py
con la opción list
:
python snippets.py my-log list
El comando se completa con el siguiente resultado:
Listing entries for logger my-log: * 2018-11-15T16:05:35.548471+00:00: Hello, world! * 2018-11-15T16:05:35.647190+00:00: Goodbye, world! * 2018-11-15T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}
Si el resultado no muestra ninguna entrada, vuelve a ejecutar el comando. Logging tarda unos minutos en recibir y procesar las entradas de registro.
Para ver tus entradas de registro, también puedes usar el Explorador de registros. Para obtener más detalles, consulta Visualiza los registros mediante el Explorador de registros.
Borra entradas de registro
Para borrar todas las entradas del registro my-log
, ejecuta la secuencia de comandos snippets.py
con la opción delete
:
python snippets.py my-log delete
El comando se completa con el siguiente resultado:
Deleted all logging entries for my-log
.
Registros de ruta
En esta sección, harás lo siguiente:
- Crear un bucket de Cloud Storage como destino para tus datos
- Crear un receptor que copie nuevas entradas de registro en el destino
- Actualizar los permisos de tu bucket de Cloud Storage
- Escribir entradas de registro en Logging
- De forma opcional, verificar el contenido de tu bucket de Cloud Storage.
Crea un destino
El destino de exportación de esta guía de inicio rápido es un bucket de Cloud Storage. Para crear un bucket de Cloud Storage, haz lo siguiente:
-
En el panel de navegación de la consola de Google Cloud, selecciona Cloud Storage y, luego, haz clic en Buckets:
- Haz clic en Crear bucket.
- Ingresa un nombre para tu bucket.
- En Tipo de ubicación, selecciona Región, que elige la ubicación de bucket con la latencia más baja.
- En Clase de almacenamiento predeterminada, selecciona Estándar.
- En Control de acceso, selecciona Detallado.
- En Herramientas de protección, selecciona Ninguna y, luego, haz clic en Crear.
En esta guía de inicio rápido, se usa un nombre de bucket myloggingproject-1
de Cloud Storage.
Crear un receptor
Un receptor es una regla que determina si Logging enruta una entrada de registros recién llegada a un destino. Un receptor tiene tres atributos:
- Nombre
- Destino
- Filtro
Para obtener más información sobre los receptores, consulta Receptores.
Si una entrada de registro nueva cumple con las condiciones de consulta, esa entrada se enruta al destino.
La secuencia de comandos export.py
usa las bibliotecas cliente de Python para crear, enumerar, modificar y borrar receptores. Para crear el receptor mysink
, que exporta todas las entradas de registro con una gravedad de INFO
como mínimo al bucket myloggingproject-1
de Cloud Storage, ejecuta el siguiente comando:
python export.py create mysink myloggingproject-1 "severity>=INFO"
Para ver tus receptores, ejecuta la secuencia de comandos export.py
con la opción list
:
python export.py list
La secuencia de comandos muestra lo siguiente:
mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1
Actualiza los permisos de destino
Los permisos del destino, en este caso, tu bucket de Cloud Storage, no se modifican cuando creas un receptor con la secuencia de comandos export.py
.
Debes cambiar la configuración de permiso de tu bucket de Cloud Storage para otorgar permiso de escritura al receptor. Para obtener información sobre las cuentas de servicio, los permisos de acceso y las funciones de Identity and Access Management, consulta Cuentas de servicio.
Para actualizar los permisos del bucket de Cloud Storage, sigue estos pasos:
Identifica la Identidad del escritor de tu receptor:
-
En el panel de navegación de la consola de Google Cloud, selecciona Logging y, luego, Enrutador de registros:
Verás una tabla de resumen de tus receptores.
Busca el receptor en la tabla, selecciona more_vert Menú y, luego, Ver detalles del receptor.
Copia la identidad del escritor en tu portapapeles.
-
-
En el panel de navegación de la consola de Google Cloud, selecciona Cloud Storage y, luego, haz clic en Buckets:
Para abrir la vista detallada, haz clic en el nombre de tu bucket.
Selecciona Permisos y haz clic en Otorgar acceso.
Pega la identidad del escritor en el cuadro Principales nuevas. Quita el prefijo
serviceAccount:
de la dirección de identidad del escritor.Configura el Rol como
Storage Object Creator
y, luego, haz clic en Guardar.
Para obtener más información, consulta Cómo configurar permisos de destino.
Valida el receptor
Para validar que tu receptor y destino estén configurados correctamente, haz lo siguiente:
Escribe entradas de registro nuevas en el registro
my-log
:python snippets.py my-log write
Visualiza el contenido de tu bucket de Cloud Storage:
-
En el panel de navegación de la consola de Google Cloud, selecciona Cloud Storage y, luego, haz clic en Buckets:
Para abrir la vista detallada, haz clic en el nombre de tu bucket. La vista de detalles muestra una lista de las carpetas que contienen datos. Si no hay datos en tu bucket, aparecerá el siguiente mensaje:
There are no live objects in this bucket.
Como se describe en Entradas de registro tardías, es posible que se necesiten entre 2 y 3 horas antes de que aparezcan las primeras entradas en el destino, o antes de que recibas la notificación de un error de configuración.
Una vez que el bucket recibió los datos, en la vista de detalles, se muestra un resultado similar al siguiente:
Los datos en cada carpeta están organizados en una serie de carpetas etiquetadas. La carpeta de nivel superior consiste en un nombre de registro y, sucesivamente, el año, el mes y el día. Para ver los datos que exportó tu receptor, haz clic en el nombre de la carpeta
my-log
y, luego, haz clic en las subcarpetas de año, mes y día hasta que llegues a un archivo que termine enjson
:El archivo JSON contiene las entradas de registro que se exportaron a tu bucket de Cloud Storage. Haz clic en el nombre del archivo JSON para ver su contenido. El contenido es similar a lo siguiente:
{"insertId":"yf1cshfoivz48", "logName":"projects/loggingproject-222616/logs/my-log", "receiveTimestamp":"2018-11-15T23:06:14.738729911Z", "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"}, "severity":"ERROR", "textPayload":"Goodbye, world!", "timestamp":"2018-11-15T23:06:14.738729911Z"}
Debido a que el nivel de gravedad de
ERROR
es mayor que el deINFO
, la entrada de registro que contiene la string “Goodbye, world!” se exporta al destino del receptor. Las otras entradas de registro que se escribieron no se exportaron al destino, porque el nivel de gravedad se estableció en el valor predeterminado, que es menor queINFO
.
-
Soluciona problemas
Existen diferentes motivos por los que un bucket de Cloud Storage podría estar vacío:
El bucket no recibió datos. Es posible que se necesiten entre 2 y 3 horas antes de que aparezcan las primeras entradas en el destino, o antes de que recibas la notificación de un error de configuración. Para obtener más información, consulta Entradas de registro tardías.
Se produjo un error de configuración. En este caso, recibirás un correo electrónico similar al siguiente asunto:
[ACTION REQUIRED] Logging export config error in myloggingproject.
En el contenido del cuerpo del correo electrónico se describe el error de configuración. Por ejemplo, si no actualizas los permisos de destino, el correo electrónico mostrará el siguiente código de error:
bucket_permission_denied
Para corregir esta condición en particular, consulta Actualiza los permisos de destino en esta página.
No se escribieron entradas de registro después de crear el receptor. El receptor se aplica solamente a las entradas de registro recién llegadas. Para corregir esta situación, escribe nuevas entradas de registro:
python snippets.py my-log write
Limpia
Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que se usaron en esta página.
Borra las entradas de registro que creaste (opcional). Si no las borras, caducarán y se quitarán. Consulta Cuotas y límites.
Para borrar todas las entradas de registro del registro
my-log
, ejecuta el siguiente comando:python snippets.py my-log delete
Borra el proyecto de Google Cloud o los recursos de la guía de inicio rápido.
Para borrar tu proyecto de Google Cloud, en el panel Información del proyecto de la consola de Google Cloud, haz clic en Ir a la configuración del proyecto y, luego, en Cerrar.
Para borrar tus recursos de inicio rápido, sigue estos pasos:
Borra tu receptor; para ello, ejecuta el siguiente comando:
python export.py delete mysink
Borra el bucket de Cloud Storage. Ve a la consola de Google Cloud y haz clic en Almacenamiento > Buckets. Marca la casilla ubicada junto al nombre de tu bucket y haz clic en Borrar.
¿Qué sigue?
- Para obtener información sobre cómo leer, escribir y configurar registros desde tus aplicaciones, consulta API de Cloud Logging.
- Para obtener información sobre el Explorador de registros, consulta Visualiza los registros con el Explorador de registros.
- Para obtener información sobre cómo enrutar tus datos de registros a destinos compatibles, consulta Descripción general del enrutamiento y el almacenamiento.
- Para obtener información sobre cómo recopilar entradas de registro de tus instancias de VM, consulta la Descripción general del Agente de operaciones.
- Para obtener información sobre la auditoría y el cumplimiento, consulta la descripción general de los registros de auditoría de Cloud.