Esta página foi traduzida pela API Cloud Translation.

Como criar perfis de aplicativos Python

Esta página descreve como modificar seu aplicativo Python para capturar dados de criação de perfil e enviá-los para seu projeto Google Cloud. 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)

Versões compatíveis com a linguagem Python:

Python 3.6 ou posterior.

Versões compatíveis com o agente de criação de perfil:

A versão mais recente do agente é compatível. Em geral, lançamentos com mais de um ano não são compatíveis. Recomendamos que você use a versão do agente lançada mais recentemente.

Sistemas operacionais compatíveis:

Linux. A criação de perfil de aplicativos Python é compatível com kernels do Linux em que a biblioteca C padrão foi implementada com glibc ou musl. Saiba mais sobre informações de configuração específicas aos kernels do Alpine Linux em Como executar no Alpine Linux.

Ambientes compatíveis:

Compute Engine
Google Kubernetes Engine (GKE)
Ambiente flexível do App Engine
Ambiente padrão do App Engine (requer o ambiente de execução do Python 3)
Fora do Google Cloud . Para informações sobre os requisitos de configuração adicionais, consulte Como criar perfis de aplicativos em execução fora do Google Cloud.

Como ativar a API Profiler

Antes de usar o agente de criação de perfil, garanta que a API Profiler subjacente esteja ativada. Você pode verificar o status da API e ativá-la, se necessário, usando a Google Cloud CLI ou o console Google Cloud :

CLI da gcloud

Se você ainda não instalou a CLI do Google Cloud na sua estação de trabalho, consulte a documentação da CLI do Google Cloud.

Execute este comando:

gcloud services enable cloudprofiler.googleapis.com

Para ver mais informações, consulte gcloud services.

Google Cloud console

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

Conceder papel do IAM à conta de serviço

Se você estiver implantando seu aplicativo em recursos do Google Cloud e se estiver usando a conta de serviço padrão e não tiver modificado as permissões de função para essa conta de serviço, pule esta seção.

Se você fizer qualquer uma das ações a seguir, precisará conceder à conta de serviço o papel do IAM de Agente do Cloud Profiler (roles/cloudprofiler.agent):

Você está usando a conta de serviço padrão, mas modificou as permissões de função dela.
Você está usando uma conta de serviço criada pelo usuário.
Você está usando a Identidade da carga de trabalho, conceda o papel de agente do Cloud Profiler à conta de serviço do Kubernetes.

É possível conceder um papel do IAM a uma conta de serviço usando o console do Google Cloud ou a Google Cloud CLI. Por exemplo, é possível usar o comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
    --member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudprofiler.agent

Antes de usar o comando anterior, substitua o seguinte:

GCP_PROJECT_ID: o ID do projeto.
MY_SVC_ACCT_ID: o nome da conta de serviço

Para mais informações, consulte Gerenciar o acesso a projetos, pastas e organizações.

Como usar o Cloud Profiler

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

Compute Engine

No Compute Engine:

Instale o compilador C/C ++ e as ferramentas de desenvolvimento:
```
sudo apt-get install -y build-essential
```
Instale o pip:
```
sudo apt-get install -y python3-pip
```
Instale o pacote do Profiler:
```
pip3 install google-cloud-profiler
```

Importe o módulo googlecloudprofiler e chame a função googlecloudprofiler.start o quanto antes no 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

Especifique 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. Saiba mais sobre solução de problemas e exceções em Como solucionar problemas.

GKE

Para o GKE:

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

Importe o módulo googlecloudprofiler e chame a função googlecloudprofiler.start o quanto antes no 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

Ambiente flexível

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

Adicione google-cloud-profiler ao seu arquivo requirements.txt.
Importe o módulo googlecloudprofiler e chame a função googlecloudprofiler.start o quanto antes no código de inicialização.

No App Engine, service e service_version são derivados do seu ambiente operacional. Saiba mais sobre solução de problemas e exceções em 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:

Adicione google-cloud-profiler ao seu arquivo requirements.txt.
Importe o módulo googlecloudprofiler e chame a função googlecloudprofiler.start o quanto antes no código de inicialização.

No App Engine, service e service_version são derivados do seu ambiente operacional. Saiba mais sobre solução de problemas e exceções em Como solucionar problemas.

Função `start`

A função googlecloudprofiler.start cria uma linha de execução do daemon que coleta e faz upload de perfis continuamente. Você deve chamar start uma vez e o mais cedo possível no seu aplicativo.

Parâmetro	Descrição
`service`¹	(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_version`¹	(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_id`²	(Opcional) O ID do projeto do Google Cloud .
`disable_cpu_profiling`	(Opcional) Para desativar a criação de perfil de tempo de CPU, defina `disable_cpu_profiling=True`. Este parâmetro é compatível apenas com o Python 3.2 e posterior. 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`. Esse parâmetro é compatível com Python 3.6 e versões mais recentes. 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. Veja as restrições na função `start` quando a criação de perfil do tempo decorrido está ativada em Limitações. O valor padrão é Falso.

¹ Somente para o Compute Engine e o GKE. Para o App Engine, o valor é derivado do ambiente.
² Para Google Cloud, o valor é derivado do ambiente. Para ambientes que não são doGoogle Cloud , é necessário fornecer um valor. Para informações, consulte Como criar perfis de aplicativos em execução fora do Google Cloud.

Análise de dados

Depois que o Profiler coletar dados, será possível visualizá-los e analisá-los usando a interface dele.

No console do Google Cloud , acesse a página Profiler:

Acessar o Profiler

Também é possível encontrar essa página usando a barra de pesquisa.

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 perfis 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-z0-9]([-a-z0-9_.]{0,253}[a-z0-9])?$

Uma boa diretriz é usar uma string estática como imageproc-service como o nome do 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 do 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 de error. É possível configurar o agente para registrar mensagens com níveis de gravidade mais baixos especificando o parâmetro verbose ao iniciar o agente. Há quatro valores compatíveis com verbose:

0: erro
1: aviso
2: mensagem informativa
3: depuração

Se você definir o parâmetro verbose para 1 na sua chamada para start, as mensagens com um nível de gravidade de Warning ou Error serão registrados, enquanto as mensagens 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, listamos as limitações, exceções e problemas conhecidos específicos da criação de perfil de aplicativos Python. Consulte Solução de problemas para conseguir ajuda com problemas comuns.

Limitações

Tipo de perfil Restrições e limitações

Tempo decorrido real

Tipo de perfil	Restrições e limitações
Tempo decorrido real	Somente criação de perfil na linha de execução principal. A função do perfil `start` precisa ser chamada 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. Observação: não ative a criação de perfil de tempo decorrido se o aplicativo tiver um número grande de linhas de execução. Usá-la nessa configuração resulta em lentidão no desempenho e não gera dados de perfil.

Somente criação de perfil na linha de execução principal.
A função do perfil start precisa ser chamada 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.
Observação: não ative a criação de perfil de tempo decorrido se o aplicativo tiver um número grande de linhas de execução. Usá-la nessa configuração resulta em lentidão no desempenho e não gera dados de perfil.

Exceções

Erro	Causa	Solução
`NotImplementedError` gerado durante `start`	Aplicativo executado em um ambiente que não é Linux.	Execute o aplicativo em um ambiente Linux.
`ValueError` gerado durante `start`	Os argumentos da função `start` são inválidos. As informações necessárias não podem ser determinadas a partir das variáveis de ambiente e dos argumentos nem da criação de perfil se a criação de perfil de tempo de CPU e de tempo decorrido estão 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 de tempo decorrido estiver ativada, `start` deverá ser chamada a partir da 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 saber mais, veja a função `start`. Verifique se você especificou o parâmetro `project_id` para `start` se estiver executando fora do Google Cloud. Para saber mais, consulte a função `start`.

Problemas conhecidos

Comportamento	Causa	Solução
Você não tem dados de perfil ou ativou um novo tipo de perfil e não tem dados de perfil.	As causas comuns estão relacionadas à configuração.	Consulte Solução de problemas.
Você está usando uWSGI (em inglês) e não tem Tempo de CPU e dados de perfil do tempo decorrido para todos os processos.	Quando o uWSGI usa vários workers para processar solicitações, o comportamento padrão é executar a inicialização do aplicativo apenas no processo principal ("mestre"). Os processos bifurcados não executam a sequência de inicialização. Se você configurar o agente de criação de perfil na sequência de inicialização do aplicativo, por exemplo, no `AppConfig.ready()` em um aplicativo Django, o efeito será que o agente de criação de perfil não estará configurado para os processos bifurcados.	Para executar a inicialização do aplicativo em todos os processos do worker, defina a sinalização lazy-apps (em inglês) como `true`. Consulte o próximo tópico nesta tabela para ver um problema relacionado.
Você está usando uWSGI (em inglês) e não tem dados de perfil do tempo decorrido, mas tem dados de perfil do Tempo de CPU.	O criador de perfil do tempo decorrido depende do módulo de sinal do Python. Quando o interpretador de Python é compilado com suporte à linha de execução, a configuração padrão desativa o processamento de sinal personalizado para processos bifurcados.	Para aplicativos uWSGI, ative o processamento de sinal personalizado ao definir a sinalização py-call-osafterfork (em inglês) como `true`. Consulte o tópico anterior nesta tabela para ver um problema relacionado.
Depois de ativar o criador de perfil, o registro de erros terá novas entradas: `BlockingIOError: [Errno 11] Resource temporarily unavailable Exception ignored when trying to write to the signal wakeup fd` Problema do GitHub (em inglês)	Seu aplicativo registrado com o descritor do arquivo de ativação do sinal, `signal.set_wakeup_fd`. Por padrão, se o buffer do descritor do arquivo for preenchido, um aviso será registrado no stderr. O Cloud Profiler aciona sinais com alta frequência quando coleta perfis. Esse comportamento pode fazer com que o buffer do descritor do arquivo fique cheio.	Se seu aplicativo puder ser executado com segurança quando os sinais forem perdidos, use o Cloud Profiler. Se você estiver usando o Python 3.7 ou posterior e quiser desativar as mensagens de aviso, transmita `warn_on_full_buffer=False` como um parâmetro para `signal.set_wakeup_fd`. Se seu aplicativo não puder ser executado com segurança quando os sinais forem perdidos, recomendamos que você pare de usar o Cloud Profiler. O uso contínuo pode causar a perda de números de sinal e excesso de entradas no registro de erros.

Execução com o Alpine Linux

O agente de criação de perfil do Python para Alpine Linux é compatível apenas com as configurações do Google Kubernetes Engine.

Para criar o agente de criação de perfil do Python, instale o pacote build-base. Para usar o agente de criação de perfil do Python no Alpine sem instalar outras dependências na imagem Alpine final, use um build de dois estágios e compile o agente de criação de perfil do Python na primeira etapa. Por exemplo, a imagem do Docker a seguir usa um build de vários estágios para compilar e instalar o agente de criação de perfil do Python:

FROM python:3.7-alpine as builder

# Install build-base to allow for compilation of the profiling agent.
RUN apk add --update --no-cache build-base

# Compile the profiling agent, generating wheels for it.
RUN pip3 wheel --wheel-dir=/tmp/wheels google-cloud-profiler

FROM python:3.7-alpine

# Copy over the directory containing wheels for the profiling agent.
COPY --from=builder /tmp/wheels /tmp/wheels

# Install the profiling agent.
RUN pip3 install --no-index --find-links=/tmp/wheels google-cloud-profiler

# Install any other required modules or dependencies, and copy an app which
# enables the profiler as described in "Enable the profiler in your
# application".
COPY ./bench.py .

# Run the application when the docker image is run, using either CMD (as is done
# here) or ENTRYPOINT.
CMD python3 -u bench.py

Erro de autenticação

Se você usar imagens do Docker executadas com o Linux Alpine (como golang:alpine ou apenas alpine), você poderá encontrar o seguinte erro de autenticação:

connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"

Para ver o erro, você precisa ativar a geração de registros do agente.

O erro indica que as imagens do Docker com o Alpine Linux não têm os certificados SSL raiz instalados por padrão. Esses certificados são necessários para que o agente de criação de perfil se comunique com a API Profiler. Para resolver esse erro, adicione o seguinte comando apk ao seu Dockerfile:

FROM alpine
...
RUN apk add --no-cache ca-certificates

Depois, será necessário recriar e reimplantar o aplicativo.