Membuat profil aplikasi Python

Halaman ini menjelaskan cara mengubah aplikasi Python 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 Python:

• Waktu CPU
• Waktu proses (thread utama)

Versi bahasa Python yang didukung:

• Python 3.6 atau yang lebih tinggi.

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 Python 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 lingkungan runtime Python 3)
• Di luar Google Cloud (Untuk informasi tentang persyaratan konfigurasi tambahan, lihat Membuat profil aplikasi yang berjalan di luar Google Cloud.)

Mengaktifkan Profiler API

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

Menggunakan Cloud Profiler

Untuk praktik terbaik menggunakan Python, buka Menyiapkan lingkungan pengembangan Python.

Compute Engine

Untuk Compute Engine, lakukan tindakan berikut:

1. Instal compiler dan alat pengembangan C/C++:

   sudo apt-get install -y build-essential
   

2. Instal pip:

   sudo apt-get install -y python3-pip
   

3. Instal paket Profiler:

   pip3 install google-cloud-profiler
   

4. Impor modul googlecloudprofiler dan panggil fungsi googlecloudprofiler.start sedini mungkin dalam kode inisialisasi Anda:

   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

   Anda harus menentukan parameter service dalam fungsi start. Untuk memfilter menurut versi aplikasi di antarmuka Profiler, tentukan parameter service_version. Untuk informasi pemecahan masalah dan pengecualian, lihat Pemecahan masalah.

GKE

Untuk GKE, lakukan hal berikut:

1. Ubah Dockerfile Anda untuk menginstal paket Profiler:

   FROM python:3
   ...
   RUN apt-get update && apt-get install -y build-essential python3-pip
   RUN pip3 install google-cloud-profiler
   

2. Impor modul googlecloudprofiler dan panggil fungsi googlecloudprofiler.start sedini mungkin dalam kode inisialisasi Anda:

   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

   Anda harus menentukan parameter service dalam fungsi start. Untuk memfilter menurut versi aplikasi di antarmuka Profiler, tentukan parameter service_version. Untuk informasi pemecahan masalah dan pengecualian, lihat Pemecahan masalah.

Lingkungan Fleksibel

Untuk lingkungan fleksibel App Engine, lakukan langkah berikut:

1. Tambahkan google-cloud-profiler ke file requirements.txt Anda.

2. Impor modul googlecloudprofiler dan panggil fungsi googlecloudprofiler.start sedini mungkin dalam kode inisialisasi Anda.

Untuk App Engine, service dan service_version berasal dari lingkungan operasi Anda. Untuk informasi pemecahan masalah dan pengecualian, lihat Pemecahan masalah.

Lingkungan Standar

Untuk lingkungan standar App Engine, yang mengharuskan Anda menggunakan lingkungan runtime Python 3, lakukan hal berikut:

1. Tambahkan google-cloud-profiler ke file requirements.txt Anda.

2. Impor modul googlecloudprofiler dan panggil fungsi googlecloudprofiler.start sedini mungkin dalam kode inisialisasi Anda.

Untuk App Engine, service dan service_version berasal dari lingkungan operasi Anda. Untuk informasi pemecahan masalah dan pengecualian, lihat Pemecahan masalah.

start fungsi

Fungsi googlecloudprofiler.start membuat thread daemon yang terus mengumpulkan dan mengupload profil. Anda harus memanggil start satu kali, dan sedini mungkin dalam aplikasi Anda.

Parameter	Deskripsi
service^1	(Wajib) Nama untuk layanan yang dibuat profilnya. Untuk mengetahui batasan nama layanan, lihat Argumen nama dan versi layanan.
service_version^1	(Opsional) Versi layanan yang dibuat profilnya. Untuk mengetahui batasan pada versi layanan, lihat Argumen nama dan versi layanan.
verbose	(Opsional) Level logging. Untuk mengetahui detail tentang level logging, lihat Logging agen. Nilai defaultnya adalah 0 (Error).
project_id^2	(Opsional) ID project Google Cloud Anda.
disable_cpu_profiling	(Opsional) Untuk menonaktifkan pembuatan profil waktu CPU, tetapkan disable_cpu_profiling=True. Parameter ini hanya didukung untuk Python versi 3.2 dan yang lebih tinggi. Untuk semua versi Python lainnya, pembuatan profil waktu CPU tidak didukung dan parameter ini diabaikan. Nilai defaultnya adalah False.
disable_wall_profiling	(Opsional) Untuk menonaktifkan pembuatan profil Wall, tetapkan disable_wall_profiling=True. Parameter ini didukung untuk Python 3.6 dan yang lebih tinggi. Untuk semua versi Python lainnya, pembuatan profil Wall tidak didukung dan parameter ini diabaikan. Untuk mengetahui batasan pada fungsi start saat pembuatan profil Layar diaktifkan, lihat Batasan. Nilai defaultnya adalah False.

¹ Khusus untuk Compute Engine dan GKE. Untuk App Engine, nilai berasal dari lingkungan.
² Untuk Google Cloud, nilai berasal dari lingkungan. Untuk lingkungan non-Google Cloud, Anda harus memberikan nilai. Untuk informasi, lihat Membuat profil aplikasi yang berjalan di luar Google Cloud.

Menganalisis data

Setelah Profiler mengumpulkan data, Anda dapat melihat dan menganalisis data ini menggunakan antarmuka Profiler.

Di konsol Google Cloud, buka halaman Profiler:

Buka Profiler

Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

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

Logging agen

Secara default, agen pembuatan profil mencatat pesan dengan tingkat keparahan error. Untuk mengonfigurasi agen agar mencatat pesan dengan level keparahan yang lebih rendah, tentukan parameter verbose saat memulai agen. Ada empat nilai yang didukung untuk verbose:

• 0 : Error
• 1 : Warning
• 2 : Informasi
• 3 : Debug

Jika Anda menetapkan parameter verbose ke 1 dalam panggilan ke start, pesan dengan tingkat keparahan Warning atau Error akan dicatat ke dalam log, sedangkan pesan Informational dan Debug akan diabaikan.

Untuk mencatat semua pesan ke dalam log, tetapkan verbose ke 3 saat memulai agen:

googlecloudprofiler.start(service='service_name', verbose=3)

Pemecahan masalah

Bagian ini mencantumkan batasan, pengecualian, dan masalah umum yang khusus untuk membuat profil aplikasi Python. Lihat Pemecahan masalah untuk mendapatkan bantuan terkait masalah umum.

Batasan

Jenis profil

Batas dan pembatasan

Waktu proses

Khusus pembuatan profil thread utama. Fungsi start profil harus dipanggil dari thread utama. Pengendali sinyal Profiler hanya dijalankan di thread utama. Jika thread utama tidak dapat dieksekusi, tidak ada data pembuatan profil yang diambil. Catatan: Jangan aktifkan pembuatan profil Wall jika aplikasi Anda berisi sejumlah besar thread. Penggunaan profil Wall dalam konfigurasi ini akan menghasilkan performa lambat dan tidak ada data profil.

Pengecualian

Error	Penyebab	Solusi
NotImplementedError ditampilkan selama start	Aplikasi yang dijalankan di lingkungan non-Linux.	Jalankan aplikasi Anda di lingkungan Linux.
ValueError ditampilkan selama start	Argumen fungsi start tidak valid, informasi yang diperlukan tidak dapat ditentukan dari variabel dan argumen lingkungan, atau pembuatan profil jika pembuatan profil waktu CPU dan pembuatan profil waktu Wall dinonaktifkan.	Pastikan nama dan versi layanan memenuhi persyaratan yang ditentukan dalam Argumen nama dan versi layanan. Jika pembuatan profil Wall diaktifkan, pastikan start dipanggil dari thread utama. Pastikan Anda menggunakan versi Python yang didukung dan bahwa pembuatan profil waktu CPU atau Waktu berjalan diaktifkan. Untuk informasi selengkapnya, lihat fungsi start. Pastikan Anda telah menentukan parameter project_id ke start jika Anda menjalankannya di luar Google Cloud. Untuk mengetahui informasi selengkapnya, lihat fungsi start.

Masalah umum

Perilaku	Penyebab	Solusi
Anda tidak memiliki data profil atau Anda mengaktifkan jenis profil baru dan tidak memiliki data profil.	Penyebab umum terkait dengan konfigurasi.	Lihat Pemecahan masalah.
Anda menggunakan uWSGI dan tidak memiliki data profil CPU dan Wall untuk semua proses.	Saat uWSGI menggunakan beberapa pekerja untuk menangani permintaan, perilaku default-nya adalah melakukan inisialisasi aplikasi hanya dalam proses utama ("master"). Proses yang di-fork tidak melakukan urutan inisialisasi. Jika Anda mengonfigurasi agen pembuatan profil dalam urutan inisialisasi aplikasi, misalnya, di AppConfig.ready() dalam aplikasi Django, efeknya adalah agen pembuatan profil tidak dikonfigurasi untuk proses yang di-fork.	Untuk melakukan inisialisasi aplikasi di semua proses pekerja, tetapkan tanda lazy-apps ke true. Lihat topik berikutnya dalam tabel ini untuk mengetahui masalah terkait.
Anda menggunakan uWSGI dan tidak memiliki data profil Wall, tetapi memiliki data profil waktu CPU.	Wall profiler bergantung pada modul sinyal Python. Saat penafsir Python dikompilasi dengan dukungan thread, konfigurasi default akan menonaktifkan penanganan sinyal kustom untuk proses yang di-fork.	Untuk aplikasi uWSGI, aktifkan penanganan sinyal kustom dengan menetapkan tanda py-call-osafterfork ke true. Lihat topik sebelumnya dalam tabel ini untuk mengetahui masalah terkait.
Setelah mengaktifkan profiler, log error akan berisi entri baru: BlockingIOError: [Errno 11] Resource temporarily unavailable Exception ignored when trying to write to the signal wakeup fd Masalah GitHub	Aplikasi Anda terdaftar dengan deskripsi file bangun sinyal, signal.set_wakeup_fd. Secara default, jika buffer deskripsi file terisi, peringatan akan dicatat ke stderr. Saat mengumpulkan profil, Cloud Profiler akan memicu sinyal dengan frekuensi tinggi. Perilaku ini dapat menyebabkan buffering deskripsi file menjadi penuh.	Jika aplikasi Anda dapat berjalan dengan aman saat sinyal hilang, Anda dapat menggunakan Cloud Profiler. Jika Anda menggunakan Python 3.7 atau yang lebih baru dan ingin menonaktifkan pesan peringatan, teruskan warn_on_full_buffer=False sebagai parameter ke signal.set_wakeup_fd. Jika aplikasi Anda tidak dapat berjalan dengan aman saat sinyal hilang, sebaiknya berhenti menggunakan Cloud Profiler. Penggunaan yang terus-menerus dapat menyebabkan hilangnya nomor sinyal dan entri yang berlebihan dalam log error.

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 Python untuk Linux Alpine hanya didukung untuk konfigurasi Google Kubernetes Engine.

Untuk mem-build agen pembuatan profil Python, Anda harus menginstal paket build-base. Untuk menggunakan agen pembuatan profil Python di Alpine tanpa menginstal dependensi tambahan ke image Alpine akhir, Anda dapat menggunakan build dua tahap dan mengompilasi agen pembuatan profil Python di tahap pertama. Misalnya, image Docker berikut menggunakan build multi-tahap untuk mengompilasi dan menginstal agen pembuatan profil 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

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