Como criar perfis de aplicativos Java

Nesta página, descrevemos como modificar seu aplicativo Java 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 Java:

  • Tempo de CPU
  • Heap (Alpha, requer Java 11, requer ambiente padrão do App Engine)
  • Tempo decorrido (não disponível para o ambiente padrão do App Engine)

Versões compatíveis com a linguagem Java:

  • OpenJDK e Oracle JDK para Java 7, 8, 9 ou 11.

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 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 por API Profiler.

  5. Nos resultados da pesquisa, selecione a API 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 instalar o agente do Profiler

Compute Engine

  1. Crie um diretório de instalação, por exemplo, /opt/cprof, para o agente Profiler:

     sudo mkdir -p /opt/cprof

  2. 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 Profiler, faça o download do arquivo do agente e extraia-o no diretório 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

ambiente flexível

Quando você usa a imagem base do ambiente de execução do Java 8 do Google ou a imagem base do ambiente de execução Java 9 / Jetty 9, o agente 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, para instalar o agente Profiler e também define 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/JARFILE"]

Para usar esse Dockerfile com o ambiente flexível do App Engine, siga estas etapas:

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 (Beta), o agente Profiler é pré-instalado. Portanto, não há mais etapas necessárias para instalá-lo.

Fora do GCP

  1. Crie um diretório de instalação, por exemplo, /opt/cprof, para o agente Profiler:

     sudo mkdir -p /opt/cprof

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

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 seu 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, o nome do serviço será definido 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 GCP, use esta opção para especificar o ID do projeto do GCP. Para mais informações, consulte Como criar perfis de aplicativos em execução fora do Google Cloud Platform.
-cprof_zone_name Quando seu aplicativo é executado no GCP, 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 reunir as informações do ID do projeto do GCP e da zona.

A política padrão é tentar novamente até três vezes, esperando 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 por heap para Java 11 e superior, configure
-cprof_enable_heap_sampling como verdadeiro. A criação de perfil por heap não é compatível com Java 10 e inferior.

A criação de perfil por heap está desativada por padrão.

Quando você ativa a criação de perfil por 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:

-cprof_heap_sampling_interval=262144
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:

-cprof_heap_sampling_interval=1048576

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

Como iniciar o programa

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=myservice,-cprof_service_version=1.0.0 \
    [JAVA OPTIONS] -jar PATH/TO/YOUR/JARFILE [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=myservice,-cprof_service_version=1.0.0", \
    "-javaopt1=val1", "-javaopt2=val2", "-jar", "PATH/TO/YOUR/JARFILE", \
    "-programopt1=val1", "-programopt2=val2"]

ambiente flexível

Modifique o arquivo de configuração do 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

Modifique o app.yaml ou o arquivo de configuração appengine-web.xml para incluir a variável de ambiente GAE_PROFILER_MODE. Isso instrui o Profiler a coletar tempo de CPU e perfis heap, uma vez por minuto em média em todas as instâncias da mesma implantação:

app.yaml:

env_variables:
   GAE_PROFILER_MODE: cpu,heap

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.

Geração de registros do agente

O agente de criação de perfil pode relatar informações de geração de registros para o ambiente flexível do App Engine, Compute Engine e GKE. O agente de criação de perfil é compatível com os níveis de geração de registros a seguir:

  • 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 registros de gravação em 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 registrar apenas mensagens fatais e de erro, anexe -minloglevel=2 à configuração -agentpath.

Por exemplo, para ativar a geração de registros de erro e mensagens fatais em erro 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

A seguir

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: