Membuat profil aplikasi Java

Halaman ini menjelaskan cara mengubah aplikasi Java Anda untuk mengambil data pembuatan profil dan mengirimkan data tersebut ke project Google Cloud Anda. Untuk informasi umum tentang pembuatan profil, lihat Konsep pembuatan profil.

Catatan: Jika berencana membuat profil aplikasi yang berjalan di luar Google Cloud, Anda perlu melakukan beberapa langkah konfigurasi yang tidak dibahas dalam dokumen ini. Misalnya, Anda harus mengonfigurasi kredensial untuk agen pembuatan profil dan menautkan agen ke project. Untuk informasi tentang langkah-langkah ini, lihat Membuat profil aplikasi yang berjalan di luar Google Cloud.

Jenis profil untuk Java:

• Waktu CPU
• Heap (memerlukan Java 11 atau lingkungan standar App Engine, dinonaktifkan secara default)
• Waktu berjalan (tidak tersedia untuk lingkungan standar App Engine Java 8)

Versi bahasa Java yang didukung:

• JVM berbasis HotSpot (termasuk Oracle JDK dan beberapa build OpenJDK) untuk Java 8, 11, atau yang lebih baru.

Versi agen pembuatan profil yang didukung:

• Rilis terbaru agen didukung. Secara umum, rilis yang lebih lama dari satu tahun tidak didukung. Sebaiknya gunakan versi agen yang baru dirilis.

Sistem operasi yang didukung:

• Linux. Membuat profil aplikasi Java didukung untuk kernel Linux yang library C standarnya diimplementasikan dengan glibc atau dengan musl. Untuk informasi konfigurasi khusus untuk kernel Linux Alpine, lihat Berjalan di Linux Alpine.

Lingkungan yang didukung:

• Compute Engine
• Google Kubernetes Engine (GKE)
• Lingkungan fleksibel App Engine
• Lingkungan standar App Engine (memerlukan App Engine SDK versi 1.9.64 atau yang lebih baru)
• Dataproc (Untuk informasi, lihat Mengonfigurasi Cloud Profiler untuk tugas Dataproc Spark dan Hadoop.)
• Di luar Google Cloud (Untuk informasi tentang persyaratan konfigurasi tambahan, lihat Membuat profil aplikasi yang berjalan di luar Google Cloud.)

Mengaktifkan Profiler API

Sebelum menggunakan agen pembuatan profil, pastikan Profiler API yang mendasarinya diaktifkan. Anda dapat memeriksa status API dan mengaktifkannya jika perlu menggunakan Google Cloud CLI atau konsol Google Cloud:

gcloud CLI

1. Jika Anda belum menginstal Google Cloud CLI di workstation, lihat dokumentasi Google Cloud CLI.

2. Jalankan perintah berikut:

   gcloud services enable cloudprofiler.googleapis.com
   

Untuk informasi selengkapnya, lihat gcloud services.

Konsol Google Cloud

1. Enable the required API.

   Enable the API

2. Jika API enabled ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

Memberikan peran IAM ke akun layanan

Jika Anda men-deploy aplikasi di resource Google Cloud dan jika Anda menggunakan akun layanan default dan belum mengubah pemberian peran ke akun layanan tersebut, Anda dapat melewati bagian ini.

Jika Anda melakukan salah satu tindakan berikut, Anda harus memberikan peran IAM Agen Cloud Profiler (roles/cloudprofiler.agent) kepada akun layanan:

1. Anda menggunakan akun layanan default, tetapi mengubah pemberian perannya.
2. Anda menggunakan akun layanan yang dibuat pengguna.
3. Anda menggunakan menggunakan identitas beban kerja, berikan peran Agen Cloud Profiler ke akun layanan Kubernetes.

Anda dapat memberikan peran IAM ke akun layanan menggunakan Konsol Google Cloud atau Google Cloud CLI. Misalnya, Anda dapat menggunakan perintah 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

Sebelum Anda menggunakan perintah sebelumnya, ganti perintah berikut:

• GCP_PROJECT_ID: Project ID Anda.
• MY_SVC_ACCT_ID: Nama akun layanan Anda.

Untuk mengetahui informasi mendetail, lihat Mengelola akses ke project, folder, dan organisasi.

Catatan: Jika akun layanan yang digunakan oleh agen pembuatan profil tidak memiliki peran IAM Agen Cloud Profiler, project Google Cloud Anda tidak akan memiliki data profil apa pun.

Menginstal agen Profiler

Compute Engine

1. Buat direktori penginstalan, misalnya, /opt/cprof, untuk Agen Profiler:

    sudo mkdir -p /opt/cprof

2. Download arsip agen dari repositori storage.googleapis.com dan ekstrak ke direktori penginstalan:

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

GKE

Ubah Dockerfile untuk membuat direktori penginstalan bagi agen Profiler, download arsip agen, lalu ekstrak arsip ke dalam direktori penginstalan.

Linux (library C berbasis glibc):

Gunakan perintah penginstalan berikut:

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 Alpine (library C berbasis musl):

Alfa

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Gunakan perintah penginstalan berikut:

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

Lingkungan Fleksibel

Saat Anda menggunakan image dasar runtime Java 8 Google atau runtime Java 9 / Jetty 9, agen Profiler sudah diinstal sebelumnya, sehingga tidak ada langkah tambahan yang perlu Anda lakukan untuk menginstal agen.

Untuk semua image dasar lainnya, Anda harus menginstal agen. Misalnya, Dockerfile berikut berisi petunjuk untuk menggunakan image openjdk:11-slim, menginstal agen Profiler, dan menentukan parameter default yang akan digunakan saat memulai aplikasi:

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

Untuk menggunakan Dockerfile ini dengan lingkungan fleksibel App Engine, Anda perlu melakukan hal berikut:

• Ganti OPTION1 dan OPTION2 dengan nilai konfigurasi agen yang diperlukan untuk aplikasi Anda, dan ganti PATH_TO_YOUR_JAR_FILE dengan jalur ke file jar Anda.
• Tempatkan Dockerfile di direktori yang sama dengan file app.yaml Anda.
• Ubah file app.yaml untuk menentukan runtime kustom. Untuk informasi selengkapnya, lihat Mem-build Runtime Kustom.

Lingkungan Standar

Catatan: Runtime Java 8 tidak mendukung GAE_PROFILER_MODE. Untuk terus menggunakan agen Profiler, Anda harus memigrasikan aplikasi ke versi Java terbaru yang didukung. Untuk mengonfigurasi agen Profiler untuk aplikasi Java generasi kedua, lihat Memulai program.

Saat Anda menggunakan lingkungan runtime Java, Agen Profiler sudah diinstal sebelumnya, sehingga tidak ada langkah tambahan yang perlu Anda lakukan untuk menginstal agen. Untuk Java versi 11 dan yang lebih baru, Java sudah diinstal sebelumnya di /opt/cprof.

Di luar Google Cloud

1. Buat direktori penginstalan, misalnya, /opt/cprof, untuk Agen Profiler:

    sudo mkdir -p /opt/cprof

2. Download arsip agen dari repositori storage.googleapis.com dan ekstrak ke direktori penginstalan:

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

Untuk menampilkan semua versi agen yang tersedia untuk didownload, jalankan perintah berikut:

gcloud storage ls gs://cloud-profiler/java/cloud-profiler-*

Respons perintah mirip dengan berikut ini:

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

Untuk mendownload versi agen tertentu, teruskan URL-nya ke perintah download. Misalnya, untuk mendownload agen yang dibuat pada 28 Oktober 2019, Anda akan menggunakan pernyataan berikut:

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

Versi agen dicatat ke dalam log selama inisialisasi.

Memuat agen Profiler

Untuk membuat profil aplikasi, mulai Java seperti biasa untuk menjalankan program, tetapi tentukan opsi konfigurasi agen. Anda menentukan jalur ke library agen, dan Anda dapat meneruskan opsi ke library.

Untuk lingkungan standar App Engine, agen akan otomatis dimuat dan dikonfigurasi. Langsung lanjutkan ke Memulai program, untuk mengetahui detail tentang cara mengonfigurasi dan memulai program.

Konfigurasi agen

Untuk mengonfigurasi agen pembuatan profil, sertakan flag -agentpath saat memulai aplikasi Anda:

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

Dalam ekspresi ini, INSTALL_DIR adalah jalur ke agen pembuatan profil, sedangkan OPTION1, OPTION2, dan OPTION3 adalah opsi konfigurasi agen. Misalnya, jika Anda mengganti OPTION1 dengan -cprof_service=myapp dalam ekspresi sebelumnya, Anda akan menetapkan nama layanan ke myapp. Tidak ada batasan jumlah opsi atau pengurutannya. Opsi konfigurasi yang didukung tercantum dalam tabel berikut:

Opsi agen	Deskripsi
-cprof_service	Jika aplikasi Anda tidak berjalan di App Engine, Anda harus menggunakan opsi konfigurasi ini untuk menetapkan nama layanan. Untuk batasan nama layanan, lihat Argumen nama dan versi layanan.
-cprof_service_version	Jika Anda ingin memiliki kemampuan untuk menganalisis data pembuatan profil menggunakan Profiler UI berdasarkan versi layanan, gunakan opsi ini untuk menetapkan versi. Untuk batasan versi, lihat Argumen nama dan versi layanan.
-cprof_project_id	Saat Anda menjalankan di luar Google Cloud, gunakan opsi ini untuk menentukan project ID Google Cloud Anda. Untuk informasi selengkapnya, lihat Membuat profil aplikasi yang berjalan di luar Google Cloud.
-cprof_zone_name	Saat aplikasi Anda berjalan di Google Cloud, agen pembuatan profil menentukan zona dengan berkomunikasi dengan layanan metadata Compute Engine. Jika agen pembuatan profil tidak dapat berkomunikasi dengan layanan metadata, Anda harus menggunakan opsi ini.
-cprof_gce_metadata_server_retry_count -cprof_gce_metadata_server_retry_sleep_sec	Bersama-sama, kedua opsi ini menentukan kebijakan percobaan ulang yang digunakan agen profiler saat berkomunikasi dengan layanan metadata Compute Engine. untuk mengumpulkan ID project dan informasi zona Google Cloud Anda. Kebijakan defaultnya adalah mencoba ulang hingga 3 kali dengan menunggu 1 detik di antara percobaan. Kebijakan ini cukup untuk sebagian besar konfigurasi.
-cprof_cpu_use_per_thread_timers	Untuk profil waktu CPU yang paling akurat, tetapkan opsi ini ke benar. Penggunaan opsi ini akan meningkatkan overhead per thread. Nilai defaultnya adalah false.
-cprof_force_debug_non_safepoints	Secara default, agen pembuatan profil memaksa JVM untuk membuat informasi proses debug untuk semua kode yang dihasilkan tepat waktu (JIT), selain membuat informasi debug untuk semua safepoint. Hal ini menghasilkan informasi lokasi tingkat baris dan fungsi yang paling akurat untuk waktu CPU dan profil heap dengan mengorbankan overhead agen tambahan. Anda dapat menonaktifkan pembuatan informasi proses debug untuk kode JIT dengan menetapkan opsi ini ke salah (false). Nilai defaultnya adalah true.
-cprof_wall_num_threads_cutoff	Secara default, profil dinding tidak dikumpulkan jika jumlah total thread dalam aplikasi melebihi 4096. Batas ini memastikan bahwa selama pengumpulan profil, biaya untuk menjelajahi stack thread minimal. Jika layanan Anda biasanya memiliki lebih dari 4096 thread dan jika Anda ingin mengumpulkan data pembuatan profil dengan mengorbankan overhead tambahan, gunakan tanda ini untuk meningkatkan batas. Batas default adalah 4.096 thread.
-cprof_enable_heap_sampling	Untuk mengaktifkan pembuatan profil heap untuk Java 11 dan yang lebih baru, tetapkan -cprof_enable_heap_sampling=true. Pembuatan profil heap tidak didukung untuk Java 10 dan yang lebih lama. Profiling heap dinonaktifkan secara default. Saat Anda mengaktifkan profiling heap, interval sampling ditetapkan ke 512 KiB secara default. Interval ini cukup untuk sebagian besar aplikasi dan menimbulkan overhead kurang dari 0,5% untuk aplikasi. Interval pengambilan sampel dari 256 KiB (262144) hingga 1024 KiB (1048576) didukung. Misalnya, untuk menetapkan interval sampling ke 256 KiB, yang menggandakan kecepatan sampling, tambahkan opsi agen: -cprof_heap_sampling_interval=262144 Demikian pula, untuk menetapkan interval sampling ke 1024 KiB, yang mengurangi frekuensi sampling menjadi setengah, tambahkan opsi agen: -cprof_heap_sampling_interval=1048576 Jika Anda mengaktifkan jenis profil ini, tentukan versi layanan baru saat men-deploy aplikasi. Untuk mengetahui informasi selengkapnya, lihat Mengapa saya tidak memiliki data untuk jenis profil tertentu? Catatan: Penggunaan beberapa heap profiler secara bersamaan akan menonaktifkan semua dukungan pembuatan profil heap untuk Java. Ini adalah batasan JVM.

Argumen nama dan versi layanan

Saat memuat agen Profiler, Anda menentukan argumen nama layanan dan argumen versi layanan opsional untuk mengonfigurasinya.

Catatan: Di lingkungan fleksibel App Engine, Anda tidak perlu menentukan argumen ini; argumen ini berasal dari lingkungan.

Nama layanan memungkinkan Profiler mengumpulkan data pembuatan profil untuk semua replika layanan tersebut. Layanan profiler memastikan rata-rata rasio pengumpulan satu profil per menit untuk setiap nama layanan di setiap versi dan zona layanan kombinasi.

Misalnya, jika Anda memiliki layanan dengan dua versi yang berjalan di seluruh replika di tiga zona, profiler akan membuat rata-rata 6 profil per menit untuk layanan tersebut.

Jika Anda menggunakan nama layanan yang berbeda untuk replika, layanan Anda akan dibuat profilnya lebih sering daripada yang diperlukan, dengan overhead yang lebih tinggi.

Saat memilih nama layanan:

• Pilih nama yang dengan jelas mewakili layanan dalam arsitektur aplikasi Anda. Pilihan nama layanan kurang penting jika Anda hanya menjalankan satu layanan atau aplikasi. Hal ini lebih penting jika aplikasi Anda berjalan sebagai kumpulan layanan mikro, misalnya.

• Pastikan untuk tidak menggunakan nilai khusus proses, seperti ID proses, dalam string nama layanan.

• String nama layanan harus cocok dengan ekspresi reguler ini:

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

Pedoman yang baik adalah menggunakan string statis seperti imageproc-service sebagai nama layanan.

Versi layanan bersifat opsional. Jika Anda menentukan versi layanan, Profiler dapat menggabungkan informasi pembuatan profil dari beberapa instance dan menampilkannya dengan benar. Ini dapat digunakan untuk menandai berbagai versi layanan saat di-deploy. UI Profiler memungkinkan Anda memfilter data menurut versi layanan; dengan cara ini, Anda dapat membandingkan performa kode versi lama dan baru.

Nilai argumen versi layanan adalah string bentuk bebas, tetapi nilai untuk argumen ini biasanya terlihat seperti nomor versi, misalnya, 1.0.0 atau 2.1.2.

Memulai program

Compute Engine

Mulai Java seperti biasa untuk menjalankan program, dan tambahkan opsi konfigurasi agen:

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

Ubah Dockerfile penampung layanan untuk memulai Java seperti biasa untuk menjalankan program, dan tambahkan opsi konfigurasi agen:

CMD ["java", \
    "-agentpath:/opt/cprof/profiler_java_agent.so=-cprof_service=myapp,-cprof_service_version=1.0.0", \
     "-jar", "PATH_TO_YOUR_JAR_FILE" ]
    

Lingkungan Fleksibel

Ubah file konfigurasi app.yaml untuk menetapkan variabel lingkungan PROFILER_ENABLE. Kemudian, mulai program seperti biasa:

env_variables:
   PROFILER_ENABLE: true

Lihat Menentukan variabel lingkungan untuk mengetahui informasi selengkapnya.

Lingkungan Standar

Lingkungan runtime Java 21

Jika Anda tidak menggunakan paket layanan lama, aktifkan pengumpulan profiler dengan mengubah file app.yaml untuk menentukan tanda agentpath menggunakan salah satu metode berikut:

• Tetapkan variabel lingkungan JAVA_TOOL_OPTIONS:

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

• Tentukan agentpath menggunakan elemen entrypoint:

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

Jika Anda menggunakan paket layanan lama, aktifkan pengumpulan profiler dengan mengubah file appengine-web.xml untuk menentukan tanda agentpath menggunakan salah satu metode berikut:

• Tetapkan variabel lingkungan 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>

• Tetapkan variabel lingkungan 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>

• Tentukan agentpath menggunakan elemen 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>

Jika jenis profil baru dikonfigurasi untuk pengumpulan, pastikan Anda menentukan versi layanan baru saat men-deploy aplikasi. Untuk mengetahui informasi selengkapnya, lihat Mengapa saya tidak memiliki data untuk jenis profil tertentu?

Logging agen

Agen pembuatan profil dapat melaporkan informasi logging untuk lingkungan fleksibel App Engine, Compute Engine, dan GKE. Agen pembuatan profil mendukung level logging berikut:

• 0: Mencatat semua pesan ke dalam log. Level logging default.
• 1: Mencatat pesan peringatan, error, dan fatal ke dalam log.
• 2: Mencatat error dan pesan fatal dalam log.
• 3: Hanya mencatat pesan fatal ke dalam log dan menghentikan aplikasi.

Untuk mengaktifkan penulisan log ke error standar dengan tingkat logging default, tambahkan -logtostderr ke konfigurasi -agentpath.

Untuk menetapkan level logging agar hanya mencatat pesan error dan fatal, tambahkan -minloglevel=2 ke konfigurasi -agentpath.

Misalnya, untuk mengaktifkan logging error dan pesan fatal ke error standar, tambahkan -logtostderr dan ‑minloglevel=2 ke konfigurasi -agentpath:

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

Pemecahan masalah

Bagian ini mencantumkan masalah yang khusus untuk membuat profil aplikasi Java. Lihat Pemecahan masalah untuk mendapatkan bantuan terkait masalah umum.

Perilaku	Penyebab	Solusi
Anda telah mengaktifkan beberapa profiler heap dan tidak memiliki data profil.	Penggunaan beberapa profiler heap secara bersamaan akan menonaktifkan semua dukungan pembuatan profil heap untuk Java. Ini adalah batasan JVM.	Mengaktifkan 1 profiler.

Berjalan dengan Linux Alpine

Alfa

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Agen pembuatan profil Java untuk Linux Alpine hanya didukung untuk konfigurasi Google Kubernetes Engine.

Untuk menginstal agen pembuatan profil Java terbaru untuk Linux Alpine, lihat Menginstal agen Profiler.

Error autentikasi

Jika menggunakan image Docker yang berjalan dengan Linux Alpine (seperti golang:alpine atau hanya alpine), Anda mungkin melihat error autentikasi berikut:

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

Perhatikan bahwa untuk melihat error, Anda harus mengaktifkan logging agen.

Error ini menunjukkan bahwa image Docker dengan Linux Alpine tidak memiliki sertifikat SSL root yang diinstal secara default. Sertifikat tersebut diperlukan agar agen pembuatan profil dapat berkomunikasi dengan profiler API. Untuk mengatasi error ini, tambahkan perintah apk berikut ke Dockerfile Anda:

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

Kemudian, Anda perlu mem-build ulang dan men-deploy ulang aplikasi.

Langkah selanjutnya

• Memilih profil yang akan dianalisis
• Berinteraksi dengan flame graph
• Memfilter grafik flame
• Memfokuskan flame graph
• Membandingkan profil