Como criar perfis de aplicativos Python

Nesta página, descrevemos como modificar seu aplicativo Python para capturar dados de criação de perfil e enviá-los para seu projeto do Google Cloud Platform (GCP). Para informações gerais sobre criação de perfil, consulte Conceitos de criação de perfil.

Tipos de perfil para Python:

  • Tempo de CPU
  • Tempo decorrido (linha de execução principal, requer Python 3.6 ou superior)

Versões compatíveis com a linguagem Python:

  • Python 3.2 ou posterior.

Sistemas operacionais compatíveis:

  • Versões Linux em que a biblioteca C padrão é implementada com glibc.

Ambientes compatíveis:

Como ativar a API Profiler

Antes de usar o agente de criação de perfil, garanta que a API do Profiler subjacente esteja ativada. Para verificar o status da API e ativá-la se necessário, use a ferramenta de linha de comando gcloud do SDK do Cloud ou o Console do Cloud:

SDK do Cloud

  1. Se você ainda não instalou o SDK do Cloud na sua estação de trabalho, consulte SDK do Google Cloud.

  2. Execute este comando:

    gcloud services enable cloudprofiler.googleapis.com
    

Para mais informações, consulte gcloud services.

Console do Cloud

  1. Acesse o painel de APIs e serviços:

    Acessar APIs e serviços

  2. Selecione o projeto que você usará para acessar a API.

  3. Clique no botão Adicionar APIs e serviços.

    Adicionar APIs e serviços

  4. Pesquise a API do Profiler.

  5. Nos resultados da pesquisa, selecione a API do Stackdriver Profiler.

  6. Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.

Como usar o Stackdriver Profiler

Para práticas recomendadas usando Python, acesse Como configurar um ambiente de desenvolvimento Python.

Compute Engine

No Compute Engine:

  1. Instale o compilador C/C ++ e as ferramentas de desenvolvimento:

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

    sudo apt-get install -y python3-pip
    
  3. Instale o pacote do Profiler:

    pip3 install google-cloud-profiler
    
  4. Importe o pacote googlecloudprofiler e chame a função googlecloudprofiler.start mais cedo possível no seu código de inicialização:

    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

    É preciso especificar o parâmetro service na função start. Para filtrar pela versão do aplicativo na interface do Profiler, especifique o parâmetro service_version. Para informações sobre solução de problemas e exceções, consulte Como solucionar problemas.

GKE

Para o GKE:

  1. Modifique o Dockerfile para instalar o pacote do Profiler:

    FROM python:3
    ...
    RUN apt-get update && apt-get install -y build-essential python3-pip
    RUN pip3 install google-cloud-profiler
    
  2. Importe o pacote googlecloudprofiler e chame a função googlecloudprofiler.start mais cedo possível no seu código de inicialização:

    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

    É preciso especificar o parâmetro service na função start. Para filtrar pela versão do aplicativo na interface do Profiler, especifique o parâmetro service_version. Para informações sobre solução de problemas e exceções, consulte Como solucionar problemas.

ambiente flexível

No ambiente flexível do App Engine, faça o seguinte:

  1. Adicione google-cloud-profiler ao arquivo requirements.txt.

  2. Importe o pacote googlecloudprofiler e chame a função googlecloudprofiler.start mais cedo possível no seu código de inicialização:

    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
    

No App Engine, service e service_version são derivados do ambiente operacional. Para informações sobre solução de problemas e exceções, consulte Como solucionar problemas.

ambiente padrão

No ambiente padrão do App Engine, que requer o ambiente de execução do Python 3, faça o seguinte:

  1. Adicione google-cloud-profiler ao arquivo requirements.txt.

  2. Importe o pacote googlecloudprofiler e chame a função googlecloudprofiler.start mais cedo possível no seu código de inicialização:

    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
    

No App Engine, service e service_version são derivados do ambiente operacional. Para informações sobre solução de problemas e exceções, consulte Como solucionar problemas.

função start

A função googlecloudprofiler.start cria uma linha de execução do daemon que faz a coleta e o upload dos perfis continuamente. É preciso chamar start uma vez e o mais cedo possível no aplicativo.

Parâmetro Descrição
service1 (Obrigatório) O nome do serviço para o qual você está criando um perfil. Para ver restrições no nome do serviço, consulte Argumentos de versão e nome de serviço.
service_version1 (Opcional) A versão do serviço para o qual você está criando um perfil. Para ver restrições na versão do serviço, consulte Nome do serviço e argumentos de versão.
verbose (Opcional) O nível de geração de registros. Para detalhes sobre ele, consulte Geração de registros do agente.

O valor padrão é 0 (erro).
project_id2 (Opcional) O ID do projeto do GCP.
disable_cpu_profiling (Opcional) Para desativar a criação de perfil da CPU, defina disable_cpu_profiling=True.

Este parâmetro é compatível apenas com o Python 3.2 e superior. Em todas as outras versões do Python, a criação de perfil do tempo da CPU não é compatível, e esse parâmetro é ignorado.

O valor padrão é Falso.
disable_wall_profiling (Opcional) Para desativar a criação de perfil do tempo decorrido, defina disable_wall_profiling=True.

Este parâmetro é compatível com o Python 2, 3.6 e superior. Em todas as outras versões do Python, a criação de perfil do tempo decorrido não é compatível, e esse parâmetro é ignorado.

Para ver restrições na função start quando a criação de perfil do tempo decorrido estiver ativada, consulte Limitações.

O valor padrão é Falso.

1 Somente no Compute Engine e GKE. No App Engine, o valor é derivado do ambiente.
2 No GCP, o valor é derivado do ambiente. Em outros ambientes, você precisa fornecer um valor. Para informações, consulte Como criar perfis de aplicativos em execução fora do Google Cloud Platform.

Análise de dados

Depois que o Profiler coletar dados, será possível visualizá-los e analisá-los usando a interface dele. Para começar a usar a interface, consulte Como abrir a interface do Profiler.

Argumentos de versão e nome de serviço

Ao carregar o agente do Profiler, você especifica um argumento de nome de serviço e um opcional de versão para configurá-lo.

Com o nome de serviço, o Profiler pode coletar dados de criação de perfil de todas as réplicas desse serviço. O criador de perfil garante uma taxa de coleta de um perfil por minuto, em média. Isso é para todos os nomes de serviço em cada combinação de zona e versão.

Por exemplo, se você tiver um serviço com duas versões executadas em réplicas em três zonas, o criador de perfil produzirá uma média de seis por minuto para esse serviço.

Se você usar nomes de serviço diferentes nas réplicas, o serviço terá perfis criados com mais frequência do que o necessário, com uma sobrecarga correspondente maior.

Ao selecionar um nome de serviço:

  • escolha um que represente claramente o serviço na arquitetura do aplicativo. Essa seleção não é tão importante se você executa apenas um serviço ou aplicativo. Ela é mais importante se o aplicativo é executado como um conjunto de microsserviços, por exemplo;

  • não use nenhum valor específico do processo, como o código, na string do nome de serviço;

  • a string do nome de serviço precisa corresponder a esta expressão regular:

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

Uma prática recomendada é usar uma string estática (por exemplo, imageproc-service) como o nome de serviço.

A versão de serviço é opcional. Se você especificá-la, o Profiler poderá agregar informações de criação de perfil de várias instâncias e exibi-las corretamente. É possível usá-la para marcar diferentes versões dos serviços conforme eles são implantados. Com a IU do Profiler, você filtra os dados por versão de serviço. Assim, é possível comparar o desempenho de versões mais antigas e mais recentes do código.

O valor do argumento da versão de serviço é uma string de formato livre. No entanto, os valores desse argumento geralmente se parecem com números de versão. Por exemplo, 1.0.0 ou 2.1.2.

Geração de registros do agente

Por padrão, o agente de criação de perfil registra mensagens com um nível de gravidade error. É possível configurar o agente para registrar mensagens com níveis de gravidade mais baixos. Basta especificar o parâmetro verbose ao iniciar o agente. Há quatro valores compatíveis com verbose:

  • 0: Error
  • 1: Warning
  • 2: Informational
  • 3: Debug

Se você definir o parâmetro verbose como 1 na chamada para start, as mensagens com nível de gravidade Warning ou Error serão registradas. Já as com Informational e Debug serão ignoradas.

Para registrar todas as mensagens, defina verbose como 3 ao iniciar o agente:

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

Solução de problemas

Nesta seção, você encontra limitações, exceções e problemas conhecidos.

Limitações

Tipo de perfil Restrições e limitações
Tempo de CPU
  • Compatível com o Python 3.2 e superior.
Tempo decorrido
  • Compatível com o Python 3.6 e superior.
  • Indisponível para o Python 3.0 a 3.5.
  • Disponível para o Python 2, mas incompatível com ele.
  • Somente criação de perfil na linha de execução principal.
  • É necessário chamar a função de perfil start a partir da linha de execução principal.
  • O gerenciador de sinal do Profiler é executado somente na linha de execução principal. Se não for possível executar essa linha de execução, nenhum dado de criação de perfil será coletado.

Exceções

Erro Causa Solução
NotImplementedError emitido durante start Aplicativo executado em um ambiente que não é Linux.
  • Execute o aplicativo em um ambiente Linux.
ValueError emitido durante start Os argumentos da função start são inválidos, não é possível determinar as informações necessárias a partir das variáveis de ambiente e dos argumentos ou da criação de perfil se os tipos "Tempo de CPU" e "tempo decorrido" estiverem desativados.
  • Garanta que o nome e a versão do serviço atendam aos requisitos definidos em Argumentos de versão e nome de serviço.
  • Se a criação de perfil do tempo decorrido estiver ativada, verifique se start é chamada na linha de execução principal.
  • Verifique se você usa uma versão compatível do Python, e se a criação de perfil dos tipos "Tempo de CPU" e "tempo decorrido" está ativada. Para mais informações, consulte a função start.
  • Verifique se você especificou o parâmetro project_id como start durante a execução fora do GCP. Para mais informações, consulte a função start.

Problemas conhecidos

Comportamento Causa Solução
As chamadas do sistema falham em aplicativos Python 3.4 ou anterior durante a criação do perfil de tempo de CPU ou tempo decorrido. Na versão 3.4 e anterior do Python, as chamadas do sistema são interrompidas por um sinal com EINTR. É necessário que o aplicativo saiba lidar com esse cenário. Para informações mais detalhadas, consulte PEP 475.
  • Use o Python 3.5 ou superior.
  • Garanta que o aplicativo lide com o código de resposta EINTR.
O aplicativo Python 3.5 ou anterior não responde a sinais quando a criação de perfil de tempo decorrido está ativada. O Python 3.5 e anterior contêm uma disputa no gerenciamento de sinais. Por isso, os aplicativos param de responder aos sinais, incluindo a interrupção Ctrl-C.
  • Use o Python 3.6 ou superior.

Próximas etapas

Para saber mais sobre o gráfico e os controles do Profiler, acesse Como usar a interface do Stackdriver Profiler. Para ver informações mais avançadas, acesse: