Guía de inicio rápido del uso de Python

En esta guía de inicio, ejecutas programas de Python para escribir, leer, borrar y exportar entradas de registro.

Antes de comenzar

Para completar esta guía de inicio rápido, debes tener un proyecto de Google Cloud Platform con la facturación habilitada. Si no tienes un proyecto de GCP, o si no tienes la facturación activada para tu proyecto, sigue estos pasos:
  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Google Cloud Platform project.

    Go to the Manage resources page

  3. Asegúrate de tener habilitada la facturación para tu proyecto.

    Aprende a habilitar la facturación

En esta guía de inicio rápido, se utiliza Stackdriver Logging y Cloud Storage. El uso de estos recursos puede hacerte incurrir en un gasto. Cuando finalices esta guía de inicio rápido, puedes borrar los recursos que creaste para evitar que continúe la facturación. Consulta la sección Limpieza para obtener más detalles.

Comienza

Puedes utilizar el entorno de Cloud Shell o un entorno genérico de Linux para completar esta guía de inicio rápido.

Cloud Shell

  1. Las versiones de Python 2.7 y 3.5 están preinstaladas en Cloud Shell. No hace falta que instales o configures ningún otro programa.

  2. Abre Cloud Shell y verifica la configuración de tu proyecto:

    1. Desde GCP Console, haz clic en el botón Activar Cloud Shell en la esquina superior derecha:

      Activar Cloud Shell

      Se abre Cloud Shell en una ventana y muestra un mensaje de bienvenida:

      Welcome to Cloud Shell

    2. El mensaje de bienvenida muestra el ID del proyecto configurado. Si no es el proyecto que querías utilizar, ejecuta el siguiente comando una vez que hayas reemplazado [PROJECT_ID] con el ID de tu proyecto:

       gcloud config set project [PROJECT_ID]
      

Linux

  1. Instala y configura Python. Puedes utilizar las versiones 2 o 3 de Python en esta guía de inicio rápido. Consulta Configurar un entorno de desarrollo de Python para obtener más detalles.

  2. Establece los permisos de Cloud Identity and Access Management de tu proyecto. En los siguientes pasos crearás una cuenta de servicio para tu proyecto y, entonces, generarás y descargarás un archivo a tu estación de trabajo de Linux.

    1. En GCP Console, ve a IAM y administración > Cuentas de servicio:

      Ir a Cuenta de servicio

    2. Selecciona el proyecto de la guía y, a continuación, haz clic en Crear cuenta de servicio:

      • Ingresa el nombre de la cuenta.
      • Ingresa una descripción de la cuenta.
      • Haz clic en Crear.
    3. En el panel Permisos de la cuenta de servicio (opcional), para la Función, selecciona Administrador de Logging desde la lista desplegable. Haz clic en Continuar.

    4. Omite la opción de otorgar a los usuarios acceso a la cuenta de servicio.

    5. Crea un archivo de claves y descárgalo en tu estación de trabajo:

      • En el panel Crear clave (opcional), haz clic en Crear clave.
      • Para el tipo de clave, selecciona JSON y, a continuación, haz clic en Crear. Tras unos instantes, aparecerá una ventana emergente con un mensaje similar al que se mostró antes:

        Clave privada guardada

    6. Para completar la creación de tu cuenta de servicio, haz clic en Listo.

  3. 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

Clona el proyecto de GitHub python-docs-samples:

git clone https://github.com/GoogleCloudPlatform/python-docs-samples

El directorio python-docs-samples/logging/cloud-client contiene los dos programas utilizados en esta guía de inicio rápido:

  • snippets.py te permite administrar entradas en un registro.
  • export.py te permite administrar exportaciones de registros.

Para cambiar el directorio del programa, ejecuta el siguiente comando:

cd python-docs-samples/logging/cloud-client

Escribe entradas de registro

El programa snippets.py utiliza las bibliotecas cliente de Python para escribir entradas de registro en Logging. Cuando la opción write está especificada en la línea de comandos, el programa 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 nuevas entradas de registro en el registro my-log, ejecuta el programa snippets.py con la opción write:

python snippets.py my-log write

Visualiza las entradas de registro

Para ver las entradas de registro en Cloud Shell, ejecuta el programa snippets.py con la opción list:

python snippets.py my-log list

Tras unos instantes, el comando finaliza y el resultado es algo así:

    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 tiene entradas, vuelve a ejecutar el comando. Logging tarda unos instantes en recibir y procesar las entradas de registro.

Para ver tus entradas de registro, también puedes utilizar el visor de registros. Consulta Visualiza los registros en el visor de registros para obtener más información.

Borra entradas de registro

Para borrar todas las entradas de registro en el registro my-list, ejecuta el programa snippets.py con la opción delete:

python snippets.py my-log delete

Tras unos instantes, el comando finaliza y muestra el siguiente resultado:

Deleted all logging entries for my-log.

Exporta registros

Logging puede exportar entradas de registro a depósitos de Cloud Storage, a conjuntos de datos de BigQuery y a Cloud Pub/Sub. Para obtener información detallada sobre la exportación, consulta Descripción general de la exportación de registros.

En esta sección, harás lo siguiente:

  • Crear un depósito 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 depósito de Cloud Storage
  • Escribir entradas de registro en Logging
  • De forma opcional, verificar el contenido de tu depósito de Cloud Storage.

Crea un destino

El destino de exportación de esta guía de inicio rápido es un depósito de Cloud Storage. Para crear un depósito de Cloud Storage sigue estos pasos:

  1. En GCP Console, ve a Almacenamiento > Navegador:

    Ir al navegador

  2. Haz clic en Crear depósito.

  3. Selecciona un nombre para tu depósito.

  4. Selecciona Regional y elige la opción geográfica más cercana para la Ubicación. Deja el resto de la configuración con su valor predeterminado. Haz clic en Crear.

En esta guía de inicio rápido, se utiliza un nombre para del depósito de Cloud Storage que es myloggingproject-1.

Crea un receptor

Un receptor es una regla que determina si Logging exporta una entrada de registros recién llegada a un destino. Un receptor tiene tres atributos:

  • Nombre
  • Destino
  • Filtro

Si una entrada de registro recién llegada cumple con las condiciones de filtro, entonces se la exporta al destino.

El programa export.py utiliza 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 al menos INFO al depósito de Cloud Storage myloggingproject-1, ejecuta el siguiente comando:

python export.py create mysink myloggingproject-1 "severity>=INFO"

Para ver tus receptores, ejecuta el programa export.py con la opción list:

python export.py list

El resultado se parece al siguiente:

    mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

Actualiza los permisos de destino

Los permisos del destino, que, en este caso, es tu depósito de Cloud Storage, no se modifican cuando creas un depósito con el programa export.py. Debes cambiar la configuración de permiso de tu depósito de Cloud Storage para otorgar permiso de escritura a tu receptor.

Para actualizar los permisos de tu depósito de Cloud Storage, sigue estos pasos:

  1. Identifica la Identidad del escritor de tu receptor:

    1. Ve a la página Visor de registros:

      Ir a la página Visor de registros

    2. Selecciona Exportaciones para ver un resumen de tus receptores, incluida la Identidad del escritor del receptor.

  2. Desde GCP Console, haz clic en Almacenamiento > Navegador:

    Ir al navegador

  3. Para abrir la vista detallada, haz clic en el nombre de tu depósito.

  4. Selecciona Permisos y, a continuación, haz clic en Agregar miembros.

  5. Establece la Función como Storage Object Creator y, a continuación, ingresa la identidad del escritor del receptor.

Consulta Permisos de destino para obtener más información.

Valida el receptor

Para validar que tu receptor y destino estén correctamente configurados, sigue estos pasos:

  1. Escribe nuevas entradas de registro en el registro my-log:

    python snippets.py my-log write
    
  2. Visualiza el contenido de tu depósito de Cloud Storage:

    1. Desde GCP Console, haz clic en Almacenamiento > Navegador:

      Ir al navegador

    2. Para abrir la vista detallada, haz clic en el nombre de tu depósito. La vista de detalles muestra una lista de las carpetas que contienen datos. Si tu depósito no contiene datos, aparecerá el siguiente mensaje:

      There are no live objects in this bucket.

      Como se describe en Disponibilidad de registros exportados, 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.

    3. Una vez que el depósito recibió los datos, la vista de detalles muestra un resultado similar al siguiente:

      Contenido del depósito

    4. Los datos en cada carpeta están organizados en diferentes carpetas etiquetadas. La de nivel superior consta de un nombre de registro y, a continuación, 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-logs y, a continuación, vuelve a hacer clic en las subcarpetas de año, mes y día hasta que llegues a un archivo que termine en json:

      Contenido del depósito

    5. El archivo JSON contiene las entradas de registro que se exportaron a tu depósito de Cloud Storage. Haz clic en el nombre del archivo JSON para ver su contenido. Será similar al 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"}
      

      Como el nivel de gravedad de ERROR es mayor que el de INFO, 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, ya que el nivel de gravedad se configuró con el valor predeterminado, y el nivel de gravedad predeterminado es menor que INFO.

Solución de problemas

Existen diferentes motivos por los que un depósito de Cloud Storage podría estar vacío:

  • No esperaste el tiempo suficiente para que los datos aparezcan en el depósito. 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. Consulta Disponibilidad de registros exportados para obtener más detalles.

  • Tienes un error de configuración. En este caso, recibirás un correo electrónico similar al siguiente asunto:

     [ACTION REQUIRED] Stackdriver 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 actualizaste los permisos de destino, se mostrará el siguiente código de error:

     bucket_permission_denied

    Para corregir esta condición en particular, consulta Actualiza los permisos.

  • No escribiste 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
    

Limpieza

Para evitar que se apliquen cargos a tu cuenta de GCP por los recursos que se utilizan en esta guía de inicio rápido, haz lo siguiente:

  1. (Opcional) Borra las entradas de registro que creaste. Si no las borras, caducarán y se quitarán. Consulta Política de cuotas. Para borrar todas las entradas de registro en la entrada my-log, ejecuta el siguiente comando:

     python snippets.py my-log delete
    
  2. Borra tu proyecto o los recursos de inicio rápido.

    • Para borrar tu proyecto, en el panel Información del proyecto en GCP Console, haz clic en Ir a la configuración del proyecto y, a continuación, haz clic en Cerrar.

    • Para borrar tus recursos de inicio rápido, sigue estos pasos:

      1. Borra tu receptor; para ello, ejecuta el siguiente comando:

        python export.py delete mysink
        
      2. Borra el depósito de Cloud Storage. Ve a GCP Console y haz clic en Almacenamiento > Navegador. Marca la casilla junto al nombre de tu depósito y haz clic en Borrar.

¿Qué sigue?

  • Consulta Cuentas de servicio para obtener una descripción detallada de cuentas de servicio, ámbitos de acceso y funciones de Cloud Identity and Access Management.
  • Consulta Visor de registros para obtener una descripción más detallada sobre este.
  • Consulta Exporta registros para aprender a exportar tus entradas de registro a Cloud Storage, BigQuery y Cloud Pub/Sub.
  • Consulta Agente de registro para aprender a recopilar entradas de registro de las instancias de tu máquina virtual en Stackdriver Logging.
  • Consulta Registros de auditoría para obtener información sobre tus necesidades de auditoría y cumplimiento.
  • Consulta API de Stackdriver Logging para descubrir cómo leer, escribir y configurar registros desde tus aplicaciones.
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Stackdriver Logging
¿Necesitas ayuda? Visita nuestra página de asistencia.