Como criar perfis de aplicativos Java
Esta página explica como modificar seu aplicativo Java para capturar dados de criação de perfil e enviá-los para seu projeto do Google Cloud. Para informações gerais sobre criação de perfil, consulte Conceitos de criação de perfil.
Tipos de perfil para Java:
- Tempo de CPU
- Heap (requer Java 11 ou ambiente padrão do App Engine, desativado por padrão)
- Tempo decorrido (não disponível para o Java 8 no ambiente padrão do App Engine)
Versões compatíveis com a linguagem Java:
- JVMs baseadas em HotSpot (incluindo Oracle JDK e alguns builds do OpenJDK) para Java 8, 11 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 Java é compatível com kernels do Linux
em que a biblioteca C padrão foi implementada com
glibc
oumusl
. 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 SDK do App Engine versão 1.9.64 ou superior)
- Dataproc (Para mais informações, consulte Como configurar o Cloud Profiler para jobs do Dataproc Spark e Hadoop)
- Fora do Google Cloud. Saiba mais sobre os requisitos de configuração adicionais em 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. É possível verificar o status da API e ativá-la, se necessário, usando a CLI do Google Cloud ou o Console do 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
.
Console do Google Cloud
-
No Console do Google Cloud, selecione APIs e serviços, clique em Ativar APIs e serviços e, em seguida, ative a API Cloud Profiler ou clique no botão a seguir:
Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.
Como instalar o agente do Profiler
Google Compute Engine
Crie um diretório de instalação, por exemplo,
/opt/cprof
, para o agente do Profiler:sudo mkdir -p /opt/cprof
Faça o download do arquivo do agente no repositório
storage.googleapis.com
e extraia-o no diretório de instalação:wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \ | sudo tar xzv -C /opt/cprof
GKE;
Modifique o Dockerfile
para criar um diretório de instalação para o
agente do Profiler, faça o download do arquivo do agente
e o extraia no diretório de instalação.
Linux (biblioteca C baseada em glibc
):
Use o seguinte comando de instalação:
RUN mkdir -p /opt/cprof && \
wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \
| tar xzv -C /opt/cprof
Alpine Linux (biblioteca C baseada em musl
):
Use o seguinte comando de instalação:
wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent_alpine.tar.gz \ | tar xzv -C /opt/cprof
Ambiente flexível
Quando você usa a imagem de base do ambiente de execução do Java 8 do Google ou a imagem de base do ambiente de execução do Java 9 / local 9 (em inglês), o agente do Profiler é pré-instalado. Portanto, não há mais etapas necessárias para instalá-lo.
Para todas as outras imagens de base, é preciso instalar o agente. Por exemplo, o Dockerfile
a seguir contém as instruções para usar a imagem openjdk:11-slim
e instalar o agente do Profiler, além de definir os parâmetros padrão a serem usados ao iniciar o aplicativo:
FROM openjdk:11-slim
COPY . .
RUN apt-get update \
&& apt-get install wget \
&& rm -rf /var/lib/apt/lists/*
RUN mkdir -p /opt/cprof && \
wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \
| tar xzv -C /opt/cprof
CMD ["java", "-agentpath:/opt/cprof/profiler_java_agent.so=OPTION1,OPTION2", "-jar", "PATH_TO_YOUR_JAR_FILE"]
Para usar esse Dockerfile
com o ambiente flexível do App Engine, faça o seguinte:
- Substitua
OPTION1
eOPTION2
pelos valores de configuração do agente necessários para o aplicativo e substituaPATH_TO_YOUR_JAR_FILE
pelo caminho para o arquivo jar. - Coloque o
Dockerfile
no mesmo diretório que o arquivoapp.yaml
. - Modifique seu arquivo
app.yaml
para especificar um ambiente de execução personalizado. Para mais informações, consulte Como criar ambientes de execução personalizados.
Ambiente padrão
Quando você usa o ambiente de execução do Java 8 do Google ou o ambiente de execução do Java 11, o agente do Profiler está pré-instalado. Portanto, não há etapas adicionais necessárias para instalar o agente.
Para o Java 11 padrão, ele está pré-instalado em /opt/cprof
.
Fora do Google Cloud
Crie um diretório de instalação, por exemplo,
/opt/cprof
, para o agente do Profiler:sudo mkdir -p /opt/cprof
Faça o download do arquivo do agente no repositório
storage.googleapis.com
e extraia-o no diretório de instalação:wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \ | sudo tar xzv -C /opt/cprof
Para listar todas as versões do agente disponíveis para download, execute o seguinte comando:
gsutil ls gs://cloud-profiler/java/cloud-profiler-*
A resposta do comando é semelhante a esta:
gs://cloud-profiler/java/cloud-profiler-java-agent_20191014_RC00.tar.gz gs://cloud-profiler/java/cloud-profiler-java-agent_20191021_RC00.tar.gz gs://cloud-profiler/java/cloud-profiler-java-agent_20191028_RC00.tar.gz
Para fazer o download de uma versão específica do agente, transmita o URL para o comando de download. Por exemplo, para fazer o download do agente criado em 28 de outubro de 2019, use a seguinte declaração:
wget -q -O- https://storage.googleapis.com/cloud-profiler/java/cloud-profiler-java-agent_20191028_RC00.tar.gz \
| sudo tar xzv -C /opt/cprof
A versão do agente é registrada durante a inicialização.
Como carregar o agente Profiler
Para criar um perfil do seu aplicativo, inicie o Java normalmente para executar seu programa. No entanto, é preciso especificar as opções de configuração do agente. Determine o caminho para a biblioteca do agente para poder transmitir opções a ela.
No ambiente padrão do App Engine, o agente é automaticamente carregado e configurado. Pule para a seção Como iniciar o programa para ver detalhes sobre como configurar e iniciar o programa.
Configuração do agente
Para configurar o agente de criação de perfil, inclua a sinalização -agentpath
ao iniciar o aplicativo:
-agentpath:INSTALL_DIR/profiler_java_agent.so=OPTION1,OPTION2,OPTION3
Nesta expressão, INSTALL_DIR
é o caminho para o agente de criação de perfil, enquanto OPTION1
, OPTION2
, e OPTION3
são opções de configuração do agente. Por exemplo, se você substituir OPTION1
por -cprof_service=myapp
na expressão anterior, definirá o nome do serviço como myapp
. Não há restrições quanto ao número de opções ou ao pedido. As opções de configuração compatíveis estão listadas na tabela a seguir:
Opção de agente | Descrição |
---|---|
-cprof_service
|
Se seu aplicativo não estiver em execução no App Engine, use esta opção de configuração para definir o nome do serviço.
Para restrições de nome de serviço, consulte Argumentos de versão e nome do serviço.
|
-cprof_service_version
|
Quando quiser analisar os dados de criação de perfil usando a IU do Profiler pela versão do serviço, use esta opção para definir a versão. Para restrições de versão, consulte Argumentos de versão e nome do serviço. |
-cprof_project_id
|
Quando você estiver executando fora do Google Cloud, use essa opção para especificar o ID do projeto do Google Cloud. Saiba mais em Como criar perfis de aplicativos em execução fora do Google Cloud. |
-cprof_zone_name
|
Quando seu aplicativo é executado no Google Cloud, o agente de criação de perfil determina a zona comunicando-se com o serviço de metadados do Compute Engine. Se o agente de criação de perfil não puder se comunicar com o serviço de metadados, será necessário usar esta opção. |
-cprof_gce_metadata_server_retry_count -cprof_gce_metadata_server_retry_sleep_sec
|
Juntas, essas duas opções definem a política de repetição que o agente profiler usa quando se comunica com o serviço de metadados do Compute Engine.
para coletar o ID do projeto do Google Cloud e as informações da zona.
A política padrão é tentar novamente até três vezes, aguardando um segundo entre as tentativas. Essa política é suficiente para a maioria das configurações. |
-cprof_cpu_use_per_thread_timers
|
Para os perfis de tempo de CPU mais precisos, defina esta opção como verdadeira. O uso desta opção resulta em aumento da sobrecarga por linha de execução.
O valor padrão é falso. |
-cprof_force_debug_non_safepoints
|
Por padrão, o agente de criação de perfil força o JVM a gerar informações de depuração para todo o código gerado just in time (JIT), além de gerar informações de depuração para todos os pontos seguros. Isso resulta em informações mais precisas das funções e da localização no nível da linha para perfis de heap e de tempo da CPU à custa de sobrecarga extra do agente. É possível desativar a geração de informações de depuração para o código JIT, configurando esta opção como falsa. O valor padrão é verdadeiro. |
-cprof_wall_num_threads_cutoff
|
Por padrão, os perfis de tempo decorrido não são coletados se o número total de linhas de execução no aplicativo exceder 4096. O limite garante que, durante a coleta de perfis, o custo de atravessar a pilha de linhas de execução seja mínimo.
Se seu serviço normalmente tem mais de 4096 linhas de execução e se você quer coletar dados de criação de perfil à custa de sobrecarga extra, use essa sinalização para aumentar o limite. O limite padrão é de 4096 linhas de execução. |
-cprof_enable_heap_sampling
|
Para ativar a criação de perfil de alocação heap para Java 11 e posterior, configure-cprof_enable_heap_sampling=true .
A criação de perfil por heap não é compatível com Java 10 e inferior.A criação de perfil de alocação heap está desativada por padrão. Quando você ativa a criação de perfil de alocação heap, o intervalo de amostragem é definido como 512 KiB por padrão. Ele é suficiente para a maioria dos aplicativos e incorre em menos de 0,5% de sobrecarga para o aplicativo. Intervalos de amostragem de 256 KiB (262144) a 1024 KiB (1048576) são compatíveis. Por exemplo, para definir o intervalo de amostragem para 256 KiB, o que duplica a taxa de amostragem, adicione a opção de agente:
Da mesma forma, para definir o intervalo de amostragem como 1024 KiB, que reduz pela metade a taxa de amostragem, adicione a opção de agente:
Se você ativar esse tipo de perfil, especifique uma nova versão do serviço
ao implantar seu aplicativo. Para mais informações, acesse
Por que não tenho dados para um tipo de perfil específico?
|
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
.
Como iniciar o programa
Google Compute Engine
Inicie o Java normalmente para executar seu programa e especifique as opções de configuração do agente.
java \
-agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myapp,-cprof_service_version=1.0.0 \
JAVA_OPTIONS -jar PATH_TO_YOUR_JAR_FILE PROGRAM_OPTIONS
GKE;
Modifique o Dockerfile do contêiner de serviço para iniciar o Java normalmente e executar o programa. Depois, especifique as opções de configuração do agente:
CMD ["java", \
"-agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myapp,-cprof_service_version=1.0.0", \
"-jar", "PATH_TO_YOUR_JAR_FILE" ]
Ambiente flexível
Modifique o arquivo de configuração app.yaml
para definir a variável de ambiente PROFILER_ENABLE
. Depois, inicie o programa normalmente:
env_variables:
PROFILER_ENABLE: true
Consulte Como definir variáveis de ambiente para mais informações.
Ambiente padrão
Ambiente de execução do Java 11
Para ativar a coleta de perfis, modifique o app.yaml
para especificar a sinalização agentpath
.
Exemplo de app.yaml
que define a variável de ambiente
JAVA_TOOL_OPTIONS
:
runtime: java11
env_variables:
JAVA_TOOL_OPTIONS: "-agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true"
Exemplo de app.yaml
que define o entrypoint
:
runtime: java11
entrypoint: java \
-agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true \
Main.java
Ambiente de execução do Java 8
Modifique o ponto de entrada no arquivo de configuração appengine-web.xml
para incluir a variável de ambiente GAE_PROFILER_MODE
para ativar o agente do Profiler.
appengine-web.xml:
<env-variables>
<env-var name="GAE_PROFILER_MODE" value="cpu,heap" />
</env-variables>
Depois, inicie o programa normalmente.
Consulte Como definir variáveis de ambiente para mais informações.
Se um novo tipo de perfil estiver configurado para coleta, especifique uma nova versão de serviço ao implantar o aplicativo. Saiba mais em Por que não tenho dados para um tipo de perfil específico?.
Geração de registros do agente
O agente de criação de perfil pode relatar informações de geração de registros do ambiente flexível do App Engine, Compute Engine e GKE. O agente de criação de perfil é compatível com os seguintes níveis de geração de registros:
0
: registra todas as mensagens. Nível de geração de registros padrão.1
: aviso de registro, erro e mensagens fatais.2
: erro de registro e mensagens fatais.3
: registra apenas mensagens fatais e interrompe o aplicativo.
Para ativar a gravação de registros no erro padrão com o nível de geração de registros padrão, anexe -logtostderr
à configuração -agentpath
.
Para definir o nível de registro para que registre apenas mensagens fatais e de erro, anexe -minloglevel=2
à configuração -agentpath
.
Por exemplo, para ativar a geração de registros de erros e mensagens fatais em erros padrão, anexe -logtostderr
e ‑minloglevel=2
à configuração -agentpath
:
java -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myapp,-logtostderr,-minloglevel=2 \
-jar myApp.jar
Solução de problemas
Nesta seção, listamos problemas específicos da criação de perfil de aplicativos Java. Consulte Solução de problemas para conseguir ajuda com problemas comuns.
Comportamento | Causa | Solução |
---|---|---|
Você ativou vários criadores de perfil de alocação heap e não tem dados de perfil. | O uso simultâneo de vários criadores de perfil de alocação heap desativa todo o suporte de criação desse tipo para Java. Essa é uma limitação da JVM. | Ativar 1 criador de perfil. |
Como executar com o Alpine Linux
O agente de criação de perfil do Java para Alpine Linux é compatível apenas com as configurações do Google Kubernetes Engine.
Para instalar o agente de criação de perfil do Java mais recente para o Alpine Linux, consulte Como instalar o agente do Profiler.Erro de autenticação
Se você usar imagens do Docker executadas com o Linux Alpine (como golang:alpine
ou apenas alpine
), talvez veja 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.
A seguir
- Selecione os perfis para analisar
- Interagir com o gráfico de chama
- Filtrar o gráfico de chama
- Focar o gráfico de chama
- Comparar perfis