Crea perfiles de aplicaciones de Python

En esta página, se describe cómo modificar tu aplicación de Python para capturar datos de creación de perfiles y enviarlos a tu proyecto de Google Cloud. Para obtener información general sobre la creación de perfiles, consulta el artículo sobre conceptos de creación de perfiles.

Tipos de perfiles para Python:

  • Tiempo de CPU
  • Tiempo (subproceso principal, requiere Python 3.6 o superior)

Versiones del lenguaje Python compatibles:

  • Python 3.2 o una versión superior

Sistemas operativos compatibles:

  • Versiones de Linux cuya biblioteca C estándar se implementa con glibc

Entornos compatibles:

Habilita la API de Profiler

Antes de usar el agente de creación de perfiles, asegúrate de que la API de Profiler subyacente esté habilitada. Puedes verificar el estado de la API y habilitarla, si es necesario, con la herramienta de línea de comandos de gcloud del SDK de Cloud o Cloud Console:

SDK de Cloud

  1. Si aún no instalaste el SDK de Cloud en tu estación de trabajo, consulta SDK de Google Cloud.

  2. Ejecuta el siguiente comando:

    gcloud services enable cloudprofiler.googleapis.com
    

Para obtener más información, consulta gcloud services.

Cloud Console

  1. Ve al panel API y servicios:

    Ir a API y servicios

  2. Selecciona el proyecto que usarás para acceder a la API.

  3. Haz clic en el botón Add APIs and Services (Agregar API y servicios).

    Agregar API y servicios

  4. Busca la API de Profiler.

  5. En los resultados de la búsqueda, selecciona API de Cloud Profiler.

    Si no ves la API de Cloud Profiler en la lista, selecciona la API de Stackdriver Profiler.

  6. Si se muestra API habilitada, la API ya está habilitada. De lo contrario, haz clic en el botón Habilitar.

Usa Cloud Profiler

Para obtener prácticas recomendadas sobre el uso de Python, consulta la sección sobre cómo configurar un entorno de desarrollo de Python.

Compute Engine

Para Compute Engine, haz lo siguiente:

  1. Instala el compilador C/C++ y las herramientas de desarrollo:

    sudo apt-get install -y build-essential
    
  2. Instala pip:

    sudo apt-get install -y python3-pip
    
  3. Instala el paquete de Profiler:

    pip3 install google-cloud-profiler
    
  4. Importa el paquete googlecloudprofiler y llama a la función googlecloudprofiler.start lo antes posible en tu código de inicialización:

    import googlecloudprofiler
    
    def main():
        # Profiler initialization. It starts a daemon thread which continuously
        # collects and uploads profiles. Best done as early as possible.
        try:
            googlecloudprofiler.start(
                service='hello-profiler',
                service_version='1.0.1',
                # verbose is the logging level. 0-error, 1-warning, 2-info,
                # 3-debug. It defaults to 0 (error) if not set.
                verbose=3,
                # project_id must be set if not running on GCP.
                # project_id='my-project-id',
            )
        except (ValueError, NotImplementedError) as exc:
            print(exc)  # Handle errors here

    Debes especificar el parámetro service en tu función start. Para filtrar por versión de la aplicación en la interfaz de Profiler, especifica el parámetro service_version. Para obtener información sobre solución de problemas y excepciones, consulta la sección solución de problemas.

GKE

Para GKE, haz lo siguiente:

  1. Modifica tu Dockerfile para instalar el paquete de Profiler:

    FROM python:3
    ...
    RUN apt-get update && apt-get install -y build-essential python3-pip
    RUN pip3 install google-cloud-profiler
    
  2. Importa el paquete googlecloudprofiler y llama a la función googlecloudprofiler.start lo antes posible en tu código de inicialización:

    import googlecloudprofiler
    
    def main():
        # Profiler initialization. It starts a daemon thread which continuously
        # collects and uploads profiles. Best done as early as possible.
        try:
            googlecloudprofiler.start(
                service='hello-profiler',
                service_version='1.0.1',
                # verbose is the logging level. 0-error, 1-warning, 2-info,
                # 3-debug. It defaults to 0 (error) if not set.
                verbose=3,
                # project_id must be set if not running on GCP.
                # project_id='my-project-id',
            )
        except (ValueError, NotImplementedError) as exc:
            print(exc)  # Handle errors here

    Debes especificar el parámetro service en tu función start. Para filtrar por versión de la aplicación en la interfaz de Profiler, especifica el parámetro service_version. Para obtener información sobre solución de problemas y excepciones, consulta la sección sobre solución de problemas.

Entorno flexible

Para el entorno flexible de App Engine, haz lo siguiente:

  1. Agrega google-cloud-profiler a tu archivo requirements.txt.

  2. Importa el paquete googlecloudprofiler y llama a la función googlecloudprofiler.start lo antes posible en tu código de inicialización:

    import googlecloudprofiler
    
    # Profiler initialization. It starts a daemon thread which continuously
    # collects and uploads profiles. Best done as early as possible.
    try:
        # service and service_version can be automatically inferred when
        # running on App Engine. project_id must be set if not running
        # on GCP.
        googlecloudprofiler.start(verbose=3)
    except (ValueError, NotImplementedError) as exc:
        print(exc)  # Handle errors here
    

Para App Engine, service y service_version se derivan de tu entorno operativo. Para obtener información sobre solución de problemas y excepciones, consulta la sección sobresolución de problemas.

Entorno estándar

Para el entorno estándar de App Engine, que requiere que uses el entorno de ejecución de Python 3, haz lo siguiente:

  1. Agrega google-cloud-profiler a tu archivo requirements.txt.

  2. Importa el paquete googlecloudprofiler y llama a la función googlecloudprofiler.start lo antes posible en tu código de inicialización:

    import googlecloudprofiler
    
    # Profiler initialization. It starts a daemon thread which continuously
    # collects and uploads profiles. Best done as early as possible.
    try:
        # service and service_version can be automatically inferred when
        # running on App Engine. project_id must be set if not running
        # on GCP.
        googlecloudprofiler.start(verbose=3)
    except (ValueError, NotImplementedError) as exc:
        print(exc)  # Handle errors here
    

Para App Engine, service y service_version se derivan de tu entorno operativo. Para obtener información sobre solución de problemas y excepciones, consulta la sección sobre solución de problemas.

Función start

La función googlecloudprofiler.start crea un subproceso de daemon que recopila y sube perfiles de forma continua. Debes llamar a start una vez y lo antes posible en tu aplicación.

Parámetro Descripción
service1 El nombre del servicio para el que se crean perfiles (obligatorio). Para conocer las restricciones en el nombre del servicio, consulta la sección sobre argumentos de la versión y del nombre del servicio.
service_version1 La versión del servicio para la que se crean perfiles (opcional). Para conocer las restricciones en la versión del servicio, consulta la sección sobre argumentos de la versión y del nombre del servicio.
verbose El nivel de registro (opcional). Para obtener detalles sobre los niveles de registro, consulta la sección sobre registro de agente.

El valor predeterminado es 0 (Error).
project_id2 Tu ID del proyecto de Google Cloud (opcional).
disable_cpu_profiling Para inhabilitar la creación de perfiles de tiempo de CPU, configura disable_cpu_profiling=True.

Este parámetro solo es compatible con Python 3.2 y versiones posteriores. Para todas las demás versiones de Python, no se admite la creación de perfiles de tiempo de CPU y este parámetro se ignora.

El valor predeterminado es falso.
disable_wall_profiling Para inhabilitar la creación de perfiles de tiempo, configura disable_wall_profiling=True (opcional).

Este parámetro es compatible con Python 2, Python 3.6 y versiones posteriores. Para todas las demás versiones de Python, no se admite la creación de perfiles de tiempo y este parámetro se ignora.

Para conocer las restricciones en la función start cuando la creación de perfiles de tiempo está habilitada, consulta la sección sobre limitaciones.

El valor predeterminado es falso.

1 Solo para Compute Engine y GKE. Para App Engine, el valor se deriva del entorno.
2 Para Google Cloud, el valor se deriva del entorno. Para entornos que no son de Google Cloud, debes proporcionar un valor. Para obtener más información, consulta la sección sobre cómo crear perfiles de aplicaciones que se ejecutan fuera de Google Cloud.

Analiza datos

Una vez que Profiler haya recopilado los datos, podrás verlos y analizarlos con la interfaz de Profiler. Para comenzar a usar esta interfaz, consulta la sección sobre cómo abrir la interfaz de Profiler.

Argumentos de versión y del nombre del servicio

Cuando cargas el agente de Profiler, especificas un argumento de nombre del servicio y un argumento de versión del servicio opcional para configurarlo.

El nombre del servicio permite que Profiler recopile datos de creación de perfiles para todas las réplicas de ese servicio. El servicio del generador de perfiles garantiza una tasa de recopilación de un perfil por minuto en promedio para cada nombre de servicio en cada combinación de zonas y versiones del servicio.

Por ejemplo, si tienes un servicio con dos versiones que se ejecutan en réplicas de tres zonas, el generador de perfiles creará un promedio de 6 perfiles por minuto para ese servicio.

Si usas nombres de servicio diferentes para tus réplicas, se crearán los perfiles del servicio con más frecuencia que la necesaria y con una sobrecarga más alta.

Cuando seleccionas un nombre de servicio, ten en cuenta lo siguiente:

  • Elige un nombre que represente claramente el servicio en la arquitectura de tu aplicación. La elección del nombre del servicio es menos importante si solo ejecutas un único servicio o aplicación. Por ejemplo, es más importante si tu aplicación se ejecuta como un conjunto de microservicios.

  • Asegúrate de no usar ningún valor específico del proceso, como un ID de proceso, en la string de nombre del servicio.

  • La string de nombre del servicio debe coincidir con esta expresión regular:

    ^[a-z]([-a-z0-9_.]{0,253}[a-z0-9])?$

Un buen lineamiento es usar una string estática, como imageproc-service, como nombre del servicio.

La versión del servicio es opcional. Si especificas la versión del servicio, Profiler puede agregar información de creación de perfiles de varias instancias y mostrarla correctamente. Esta se puede usar para marcar diferentes versiones de tus servicios a medida que se implementan. La IU de Profiler te permite filtrar los datos por versión del servicio. De esta manera, puedes comparar el rendimiento de las versiones anteriores y más recientes del código.

El valor del argumento de la versión del servicio es una string de formato libre, pero los valores de este argumento suelen verse como números de versión, por ejemplo, 1.0.0 o 2.1.2.

Registro de agente

De forma predeterminada, el agente de creación de perfiles registra los mensajes con un nivel de gravedad de error. A fin de configurar el agente para que registre mensajes con niveles de gravedad más bajos, especifica el parámetro verbose cuando inicies el agente. Hay cuatro valores admitidos para verbose:

  • 0: error
  • 1: advertencia
  • 2: mensajes informativos
  • 3: depurar

Si configuras el parámetro verbose para 1 en la llamada a start, los mensajes con un nivel de gravedad Warning o Error se registran, mientras que los mensajes Informational y Debug se ignoran.

Para registrar todos los mensajes, configura verbose en 3 cuando inicies el agente:

googlecloudprofiler.start(service='service_name', verbose=3)

Solución de problemas

En esta sección, se enumeran las limitaciones, las excepciones y los problemas conocidos.

Limitaciones

Tipo de perfil Restricciones y limitaciones
Tiempo de CPU
  • Compatible con Python 3.2 y versiones posteriores.
Tiempo
  • Compatible con Python 3.6 y versiones posteriores.
  • No disponible para Python 3.0 a 3.5.
  • Disponible, pero no compatible, para Python 2.
  • Creación de perfiles de subprocesos principales únicamente.
  • La función start del perfil se debe llamar desde el subproceso principal.
  • El controlador de señal de Profiler solo se ejecuta en el subproceso principal. Si el subproceso principal no se puede ejecutar, no se capturan los datos de creación de perfiles.

Excepciones

Error Causa Solución
Se muestra NotImplementedError durante start Aplicación ejecutada en un entorno que no es de Linux.
  • Ejecuta tu aplicación en un entorno Linux.
Se muestra ValueError durante start Los argumentos de la función start no son válidos, la información necesaria no puede determinarse a partir de las variables de entorno, los argumentos o la creación de perfiles si tanto la creación de perfiles de tiempo de CPU como la de tiempo se inhabilitan.
  • Asegúrate de que el nombre y la versión del servicio cumplan con los requisitos definidos en la sección sobre argumentos de la versión y del nombre del servicio.
  • Si la creación de perfiles de tiempo está habilitada, asegúrate de que se llame a start desde el subproceso principal.
  • Asegúrate de usar una versión compatible de Python y de que la creación de perfiles de tiempo de CPU o tiempo esté habilitada. Para obtener más información, consulta la función start.
  • Verifica que hayas especificado el parámetro project_id en start si estás realizando la ejecución fuera de Google Cloud. Para obtener más información, consulta la función start.

Problemas conocidos

Comportamiento Causa Solución
Las llamadas al sistema fallan con las aplicaciones de Python 3.4 o anteriores cuando se crea el perfil de tiempo de CPU o tiempo. La versión 3.4 de Python y las versiones anteriores provocan la falla de las llamadas al sistema interrumpidas por una señal con EINTR. Tu aplicación debe controlar esta situación. Para obtener información más detallada, consulta PEP 475.
  • Usa Python 3.5 o una versión posterior.
  • Haz que la aplicación maneje el código de respuesta EINTR.
Tu aplicación de Python 3.5 o una versión anterior no responde a las señales cuando la creación de perfiles de tiempo está habilitada. Python 3.5 y las versiones anteriores contienen una condición de carrera en su manejo de señales. El efecto es que las aplicaciones dejan de responder a las señales, incluida la señal de cierre Ctrl-C.
  • Usa Python 3.6 o una versión posterior.

Próximos pasos

Para obtener más información sobre el gráfico y los controles de Profiler, consulta la sección sobre cómo usar la interfaz de Cloud Profiler. Para obtener información avanzada, consulta lo siguiente: