Profilazione delle applicazioni Java

In questa pagina viene descritto come modificare l'applicazione Java per acquisire i dati di profilazione e fare in modo che i dati vengano inviati al progetto Google Cloud. Per informazioni generali sulla profilazione, consulta i concetti di profilazione.

Tipi di profilo per Java:

• Tempo CPU
• Heap (richiede l'ambiente standard Java 11 o App Engine, disabilitato per impostazione predefinita)
• Tempo totale di esecuzione (non disponibile per l'ambiente standard Java 8 App Engine)

Versioni del linguaggio Java supportate:

• JVM basate su HotSpot (incluse le build Oracle JDK e alcune build OpenJDK) per Java 8, 11 o versioni successive.

Versioni dell'agente di profilazione supportate:

• È supportata la release più recente dell'agente. In generale, le release più vecchie di un anno non sono supportate. Ti consigliamo di usare la versione dell'agente rilasciata più di recente.

Sistemi operativi supportati:

• Linux. La profilazione delle applicazioni Java è supportata per i kernel Linux la cui libreria C standard è implementata con glibc o con musl. Per informazioni sulla configurazione specifiche per i kernel Linux Alps, consulta Esecuzione su Linux Alps.

Ambienti supportati:

• Compute Engine
• Google Kubernetes Engine (GKE)
• Ambiente flessibile di App Engine
• Ambiente standard di App Engine (richiede l'SDK App Engine versione 1.9.64 o successive)
• Dataproc (per informazioni, vedi Configurazione di Cloud Profiler per i job Dataproc Spark e Hadoop).
• Al di fuori di Google Cloud (per informazioni sui requisiti di configurazione aggiuntivi, consulta Profilazione delle applicazioni in esecuzione al di fuori di Google Cloud).

Abilitazione dell'API Profiler

Prima di utilizzare l'agente di profilazione, assicurati che l'API Profiler sottostante sia abilitata. Puoi controllare lo stato dell'API e abilitarla, se necessario, utilizzando Google Cloud CLI o la console Google Cloud:

Interfaccia a riga di comando gcloud

1. Se non hai già installato Google Cloud CLI sulla tua workstation, consulta la documentazione di Google Cloud CLI.

2. Esegui questo comando:

   gcloud services enable cloudprofiler.googleapis.com
   

Per maggiori informazioni, vedi gcloud services.

Console Google Cloud

1. Attiva l'API richiesta.

   Abilita l'API

2. Se viene visualizzato API abilitata, l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Installazione dell'agente Profiler

Compute Engine

1. Crea una directory di installazione, ad esempio /opt/cprof, per l'agente Profiler:

    sudo mkdir -p /opt/cprof

2. Scarica l'archivio degli agenti dal repository storage.googleapis.com ed estrailo nella directory di installazione:

   wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \
   | sudo tar xzv -C /opt/cprof

GKE

Nota: se abiliti Workload Identity su un cluster, assicurati di aggiungere il ruolo Agente Cloud Profiler (roles/cloudprofiler.agent) all'account di servizio Kubernetes. Per maggiori informazioni, consulta Utilizzare Workload Identity.

Modifica Dockerfile per creare una directory di installazione per l'agente Profiler, scarica l'archivio degli agenti ed estrai l'archivio nella directory di installazione.

Linux (libreria C basata su glibc):

Utilizza il seguente comando di installazione:

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

Linux Alps (libreria C basata su musl):

Alpha

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Utilizza il seguente comando di installazione:

wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent_alpine.tar.gz \
| tar xzv -C /opt/cprof

Ambiente flessibile

Quando utilizzi l'immagine di base del runtime Java 8 o dell'immagine di base del runtime Java 9 / Jet 9, l'agente Profiler è preinstallato, pertanto non sono necessari passaggi aggiuntivi per installare l'agente.

Per tutte le altre immagini di base, devi installare l'agente. Ad esempio, Dockerfile seguente contiene le istruzioni per utilizzare l'immagine openjdk:11-slim, installare l'agente Profiler e definire i parametri predefiniti da utilizzare all'avvio dell'applicazione:

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"]

Per utilizzare questo Dockerfile con l'ambiente flessibile di App Engine, devi:

• Sostituisci OPTION1 e OPTION2 con i valori di configurazione dell'agente necessari per la tua applicazione e sostituisci PATH_TO_YOUR_JAR_FILE con il percorso del file jar.
• Inserisci Dockerfile nella stessa directory del file app.yaml.
• Modifica il file app.yaml per specificare un runtime personalizzato. Per ulteriori informazioni, consulta Creazione di runtime personalizzati.

Ambiente standard

Nota: il runtime Java 8 non supporta GAE_PROFILER_MODE. Per continuare a utilizzare l'agente Profiler, devi eseguire la migrazione della tua applicazione all'ultima versione supportata di Java. Per configurare l'agente Profiler per l'applicazione Java di seconda generazione, consulta Avvio del programma.

Quando utilizzi l'ambiente di runtime Java, l'agente Profiler è preinstallato, pertanto non sono necessari passaggi aggiuntivi per installare l'agente. Per Java 11 e versioni successive, è preinstallato in /opt/cprof.

Al di fuori di Google Cloud

1. Crea una directory di installazione, ad esempio /opt/cprof, per l'agente Profiler:

    sudo mkdir -p /opt/cprof

2. Scarica l'archivio degli agenti dal repository storage.googleapis.com ed estrailo nella directory di installazione:

   wget -q -O- https://storage.googleapis.com/cloud-profiler/java/latest/profiler_java_agent.tar.gz \
   | sudo tar xzv -C /opt/cprof

Per elencare tutte le versioni dell'agente disponibili per il download, esegui questo comando:

gsutil ls gs://cloud-profiler/java/cloud-profiler-*

La risposta al comando è simile alla seguente:

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

Per scaricare una versione specifica dell'agente, passa il relativo URL al comando di download. Ad esempio, per scaricare l'agente creato il 28 ottobre 2019, devi utilizzare la seguente istruzione:

wget -q -O- https://storage.googleapis.com/cloud-profiler/java/cloud-profiler-java-agent_20191028_RC00.tar.gz \
  | sudo tar xzv -C /opt/cprof

La versione dell'agente viene registrata durante l'inizializzazione.

Caricamento dell'agente Profiler in corso...

Per profilare la tua applicazione, avvia Java come faresti normalmente per eseguire il programma, ma specifica le opzioni di configurazione dell'agente. Puoi specificare il percorso della libreria degli agenti e passare le opzioni alla libreria.

Per l'ambiente standard App Engine, l'agente viene caricato e configurato automaticamente. Passa direttamente a Avvio del programma per maggiori dettagli su come configurare e avviare il programma.

Configurazione agente

Per configurare l'agente di profilazione, includi il flag -agentpath all'avvio dell'applicazione:

 -agentpath:INSTALL_DIR/profiler_java_agent.so=OPTION1,OPTION2,OPTION3

In questa espressione, INSTALL_DIR è il percorso dell'agente di profilazione, mentre OPTION1, OPTION2 e OPTION3 sono opzioni di configurazione dell'agente. Ad esempio, se sostituisci OPTION1 con -cprof_service=myapp nell'espressione precedente, imposti il nome del servizio su myapp. Non ci sono limitazioni al numero di opzioni o al loro ordine. Le opzioni di configurazione supportate sono elencate nella tabella seguente:

Opzione agente	Descrizione
-cprof_service	Se la tua applicazione non è in esecuzione su App Engine, devi utilizzare questa opzione di configurazione per impostare il nome del servizio. Per le limitazioni relative al nome del servizio, vedi Argomenti Nome servizio e versione.
-cprof_service_version	Se vuoi avere la possibilità di analizzare i dati di profilazione utilizzando l'interfaccia utente di Profiler in base alla versione del servizio, utilizza questa opzione per impostare la versione. Per le limitazioni della versione, consulta Argomenti Nome servizio e versione.
-cprof_project_id	Quando esegui l'esecuzione al di fuori di Google Cloud, utilizza questa opzione per specificare l'ID progetto Google Cloud. Per maggiori informazioni, consulta Profilazione delle applicazioni in esecuzione al di fuori di Google Cloud.
-cprof_zone_name	Quando la tua applicazione è in esecuzione su Google Cloud, l'agente di profilazione determina la zona comunicando con il servizio per metadati di Compute Engine. Se l'agente di profilazione non riesce a comunicare con il servizio di metadati, devi utilizzare questa opzione.
-cprof_gce_metadata_server_retry_count -cprof_gce_metadata_server_retry_sleep_sec	Insieme, queste due opzioni definiscono il criterio per i nuovi tentativi che l'agente profiler utilizza quando comunica con il servizio per i metadati di Compute Engine. per raccogliere l'ID progetto Google Cloud e le informazioni sulla zona. Il criterio predefinito prevede di riprovare fino a 3 volte con un secondo tra un tentativo e l'altro. Questo criterio è sufficiente per la maggior parte delle configurazioni.
-cprof_cpu_use_per_thread_timers	Per profili di tempo CPU più precisi, imposta questa opzione su true. L'utilizzo di questa opzione comporta un aumento dell'overhead per thread. Il valore predefinito è false.
-cprof_force_debug_non_safepoints	Per impostazione predefinita, l'agente di profilazione obbliga la JVM a generare informazioni di debug per tutto il codice generato JIT (Just In Time), oltre a generare informazioni di debug per tutti i touchpoint. Ciò si traduce in informazioni più accurate sulla funzione e sulla posizione a livello di riga per il tempo di CPU e i profili heap, a scapito dell'overhead aggiuntivo dell'agente. Puoi disabilitare la generazione di informazioni di debug per il codice JIT impostando questa opzione su false. Il valore predefinito è true.
-cprof_wall_num_threads_cutoff	Per impostazione predefinita, i profili del wall non vengono raccolti se il numero totale di thread nell'applicazione supera 4096. Il limite garantisce che, durante la raccolta dei profili, il costo di attraversamento dello stack di thread sia minimo. Se il servizio normalmente ha più di 4096 thread e se vuoi raccogliere i dati di profilazione a scapito di un overhead aggiuntivo, utilizza questo flag per aumentare il limite. Il limite predefinito è 4096 thread.
-cprof_enable_heap_sampling	Per attivare la profilazione dell'heap per Java 11 e versioni successive, imposta -cprof_enable_heap_sampling=true. La profilazione dell'heap non è supportata per Java 10 e versioni precedenti. La profilazione dell'heap è disattivata per impostazione predefinita. Quando abiliti la profilazione heap, l'intervallo di campionamento viene impostato su 512 KiB per impostazione predefinita. Questo intervallo è sufficiente per la maggior parte delle applicazioni e comporta un overhead inferiore allo 0,5%. Sono supportati intervalli di campionamento da 256 KiB (262144) a 1024 KiB (1048576). Ad esempio, per impostare l'intervallo di campionamento su 256 KiB e raddoppiare la frequenza di campionamento, aggiungi l'opzione dell'agente: -cprof_heap_sampling_interval=262144 Analogamente, per impostare l'intervallo di campionamento su 1024 KiB, che dimezza la frequenza di campionamento, aggiungi l'opzione dell'agente: -cprof_heap_sampling_interval=1048576 Se abiliti questo tipo di profilo, specifica una nuova versione del servizio quando esegui il deployment dell'applicazione. Per maggiori informazioni, consulta la sezione Perché non ho i dati per un tipo di profilo specifico? Nota: l'uso simultaneo di più profiler heap disattiva il supporto della profilazione heap per Java. Questa è una limitazione JVM.

Argomenti per nome e versione del servizio

Quando carichi l'agente Profiler, specifichi un argomento service-name e un argomento facoltativo service-version per configurarlo.

Nota: nell'ambiente flessibile di App Engine, non devi specificare questi argomenti, perché sono derivati dall'ambiente.

Il nome del servizio consente a Profiler di raccogliere dati di profilazione per tutte le repliche di quel servizio. Il servizio profiler garantisce una frequenza di raccolta di un profilo al minuto, in media, per ciascun nome di servizio in ogni combinazione di versioni e zone del servizio.

Ad esempio, se hai un servizio con due versioni in esecuzione su repliche in tre zone, il profiler creerà una media di 6 profili al minuto per quel servizio.

Se utilizzi nomi di servizio diversi per le repliche, il servizio verrà profilato più spesso del necessario, con un overhead di conseguenza più elevato.

Quando selezioni il nome di un servizio:

• Scegli un nome che rappresenti chiaramente il servizio nell'architettura dell'applicazione. La scelta del nome del servizio è meno importante se esegui un solo servizio o un'unica applicazione. È più importante se l'applicazione viene eseguita come un insieme di microservizi, ad esempio.

• Assicurati di non utilizzare valori specifici del processo, ad esempio un ID di processo, nella stringa del nome del servizio.

• La stringa del nome del servizio deve corrispondere a questa espressione regolare:

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

Una buona linea guida è usare una stringa statica come imageproc-service come nome del servizio.

La versione del servizio è facoltativa. Se specifichi la versione del servizio, Profiler può aggregare le informazioni di profilazione di più istanze e visualizzarle correttamente. Può essere usato per contrassegnare versioni diverse dei tuoi servizi durante il deployment. La UI di Profiler consente di filtrare i dati in base alla versione del servizio; in questo modo, è possibile confrontare le prestazioni delle versioni precedenti e più recenti del codice.

Il valore dell'argomento service-version è una stringa in formato libero, ma i valori per questo argomento in genere sono come numeri di versione, ad esempio 1.0.0 o 2.1.2.

Avvio del programma

Compute Engine

Avvia Java come faresti normalmente per eseguire il tuo programma e aggiungi le opzioni di configurazione dell'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

Modifica il Dockerfile del container di servizio in modo che avvii Java come faresti normalmente per eseguire il programma e aggiungi le opzioni di configurazione dell'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 flessibile

Modifica il file di configurazione app.yaml per impostare la variabile di ambiente PROFILER_ENABLE. Poi avvia il programma come di consueto:

env_variables:
   PROFILER_ENABLE: true

Per ulteriori informazioni, consulta Definizione delle variabili di ambiente.

Ambiente standard

Ambiente di runtime Java 21

Se non utilizzi i servizi in bundle legacy, attiva la raccolta profiler modificando il file app.yaml per specificare il flag agentpath utilizzando uno dei seguenti metodi:

• Imposta la variabile di ambiente JAVA_TOOL_OPTIONS:

  runtime: java21
  env_variables:
    JAVA_TOOL_OPTIONS: "-agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true"
  

• Specifica agentpath utilizzando l'elemento entrypoint:

  runtime: java21
  entrypoint: java \
    -agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true \
    Main.java
  

Se utilizzi servizi in bundle legacy, attiva la raccolta profiler modificando il file appengine-web.xml per specificare il flag agentpath utilizzando uno dei seguenti metodi:

• Imposta la variabile di ambiente JAVA_USER_OPTS:

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <env-variables>
  <env-var name="JAVA_USER_OPTS" value="-agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true" />
  </env-variables>
  </appengine-web-app>
  

• Imposta la variabile di ambiente CPROF_ENABLE:

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <env-variables>
  <env-var name="CPROF_ENABLE" value="-agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true" />
  </env-variables>
  </appengine-web-app>
  

• Specifica agentpath utilizzando l'elemento entrypoint:

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <entrypoint>
     java
     -agentpath:/opt/cprof/profiler_java_agent.so=-logtostderr,-cprof_enable_heap_sampling=true
    </entrypoint>
  </appengine-web-app>
  

Se per la raccolta è configurato un nuovo tipo di profilo, assicurati di specificare una nuova versione del servizio quando esegui il deployment dell'applicazione. Per ulteriori informazioni, consulta la sezione Perché non ho i dati per un tipo di profilo specifico?

Logging agente

L'agente di profilazione può segnalare le informazioni di logging per l'ambiente flessibile di App Engine, Compute Engine e GKE. L'agente di profilazione supporta i seguenti livelli di logging:

• 0: registra tutti i messaggi. Livello di logging predefinito.
• 1: registra messaggi di avviso, errore e irreversibili.
• 2: registra errori e messaggi irreversibili.
• 3: registra solo i messaggi irreversibili e interrompi l'applicazione.

Per abilitare la scrittura dei log in errore standard con il livello di logging predefinito, aggiungi -logtostderr alla configurazione -agentpath.

Per impostare il livello di logging in modo che registri solo i messaggi di errore e irreversibili, aggiungi -minloglevel=2 alla configurazione -agentpath.

Ad esempio, per abilitare il logging dei messaggi di errore e irreversibili nell'errore standard, aggiungi -logtostderr e ‑minloglevel=2 alla configurazione -agentpath:

 java -agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myapp,-logtostderr,-minloglevel=2 \
   -jar myApp.jar

Risoluzione dei problemi

Questa sezione elenca i problemi specifici della profilazione delle applicazioni Java. Consulta Risoluzione dei problemi per assistenza in merito ai problemi più comuni.

Comportamento	Causa	Soluzione
Hai abilitato più profiler heap e non hai dati del profilo.	L'uso simultaneo di più profilatori heap disattiva tutto il supporto della profilazione heap per Java. Si tratta di una limitazione JVM.	Attiva 1 profiler.

Esecuzione con Linux alpino

Alpha

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici del servizio. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

L'agente di profilazione Java per Linux Alps è supportato solo per le configurazioni di Google Kubernetes Engine.

Per installare l'agente di profilazione Java più recente per Linux Alps, consulta Installazione dell'agente Profiler.

Errore di autenticazione

Se utilizzi immagini Docker eseguite con Linux Alps (ad esempio golang:alpine o solo alpine), potresti visualizzare il seguente errore di autenticazione:

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

Tieni presente che, per visualizzare l'errore, devi avere abilitato il logging dell'agente.

L'errore indica che nelle immagini Docker con Linux Alps non sono installati i certificati SSL root per impostazione predefinita. Questi certificati sono necessari affinché l'agente di profilazione possa comunicare con l'API Profiler. Per risolvere questo errore, aggiungi il seguente comando apk al Dockerfile:

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

Devi quindi ricreare la build ed eseguire nuovamente il deployment dell'applicazione.

Passaggi successivi

• Selezionare i profili da analizzare
• Interagire con il grafico a fiamme
• Filtrare il grafico a fiamme
• Metti a fuoco il grafico a fiamme
• Confrontare i profili