Membuat profil aplikasi Python

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

Jenis profil untuk Python:

  • Waktu CPU
  • Waktu proses (thread utama)

Versi bahasa Python yang didukung:

  • Python 3.6 hingga 3.11.0.

Versi agen pembuatan profil yang didukung:

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

Sistem operasi yang didukung:

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

Lingkungan yang didukung:

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.

Google Cloud console

  1. Enable the required API.

    Enable the API

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

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 hal 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 workload identity, berikan peran Cloud Profiler Agent ke akun layanan Kubernetes.

Anda dapat memberikan peran IAM ke akun layanan menggunakan konsolGoogle 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.

Menggunakan Cloud Profiler

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

Compute Engine

Untuk Compute Engine, lakukan hal 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 mengetahui 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 mengetahui informasi pemecahan masalah dan pengecualian, lihat Pemecahan masalah.

Lingkungan Fleksibel

Untuk lingkungan fleksibel App Engine, 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 mengetahui 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 mengetahui 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 di aplikasi Anda.

Parameter Deskripsi
service1 (Wajib) Nama untuk layanan yang sedang dibuat profilnya. Untuk mengetahui batasan pada nama layanan, lihat Argumen nama dan versi layanan.
service_version1 (Opsional) Versi layanan yang sedang diprofilkan. Untuk mengetahui batasan pada versi layanan, lihat Argumen nama dan versi layanan.
verbose (Opsional) Tingkat logging. Untuk mengetahui detail tentang level logging, lihat Logging agen.

Nilai defaultnya adalah 0 (Error).
project_id2 (Opsional) ID project Google Cloud Anda.
disable_cpu_profiling (Opsional) Untuk menonaktifkan pembuatan profil waktu CPU, setel disable_cpu_profiling=True.

Parameter ini didukung untuk Python versi 3.2 hingga 3.11.0. 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 Pemrofilan dinding, tetapkan disable_wall_profiling=True.

Parameter ini didukung untuk Python versi 3.6 hingga 3.11.0. Untuk semua versi Python lainnya, pembuatan profil Wall tidak didukung dan parameter ini diabaikan.

Untuk mengetahui batasan pada fungsi start saat Profiling aktivitas diaktifkan, lihat Batasan.

Nilai defaultnya adalah False.

1 Hanya untuk Compute Engine dan GKE. Untuk App Engine, nilai berasal dari lingkungan.
2 Untuk Google Cloud, nilai berasal dari lingkungan. Untuk lingkungan non-Google Cloud , Anda harus memberikan nilai. Untuk mengetahui informasinya, 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 dengan menggunakan kotak penelusuran.

Argumen nama dan versi layanan

Saat memuat agen Profiler, Anda menentukan argumen service-name dan argumen service-version opsional untuk mengonfigurasinya.

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

Misalnya, jika Anda memiliki layanan dengan dua versi yang berjalan di seluruh replika dalam 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 diprofilkan lebih sering daripada yang diperlukan, dengan overhead yang lebih tinggi.

Saat memilih nama layanan:

  • Pilih nama yang 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 serangkaian microservice, misalnya.

  • Pastikan untuk tidak menggunakan nilai khusus proses, seperti ID proses, dalam string service-name.

  • String service-name 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. Tag ini dapat digunakan untuk menandai berbagai versi layanan Anda saat layanan tersebut di-deploy. UI Profiler memungkinkan Anda memfilter data menurut versi layanan; dengan begitu, Anda dapat membandingkan performa versi kode yang lebih lama dan lebih baru.

Nilai argumen service-version 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 tingkat keparahan yang lebih rendah, tentukan parameter verbose saat memulai agen. Ada empat nilai yang didukung untuk verbose:

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

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

Untuk mencatat semua pesan, 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 pembuatan profil aplikasi Python. Lihat Pemecahan masalah untuk mendapatkan bantuan terkait masalah umum.

Batasan

Jenis profil Batas dan pembatasan
Waktu proses
  • Hanya pembuatan profil thread utama.
  • Fungsi start profil harus dipanggil dari thread utama.
  • Handler sinyal Profiler hanya dijalankan di thread utama. Jika thread utama tidak dapat dieksekusi, tidak ada data profiling yang diambil.

Pengecualian

Error Penyebab Solusi
NotImplementedError yang dilempar selama start Aplikasi dijalankan di lingkungan non-Linux.
  • Jalankan aplikasi Anda di lingkungan Linux.
ValueError yang dilempar 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 Dinding dinonaktifkan.
  • Pastikan nama dan versi layanan memenuhi persyaratan yang ditentukan dalam Argumen nama dan versi layanan.
  • Jika Profiling dinding diaktifkan, pastikan start dipanggil dari thread utama.
  • Pastikan Anda menggunakan versi Python yang didukung dan profiling Waktu CPU atau Waktu nyata diaktifkan. Untuk mengetahui informasi selengkapnya, lihat fungsi start.
  • Pastikan Anda telah menentukan parameter project_id ke start jika Anda menjalankan 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 Anda tidak memiliki data profil CPU time dan Wall untuk semua proses.

Saat uWSGI menggunakan beberapa pekerja untuk menangani permintaan, perilaku defaultnya 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, maka agen pembuatan profil tidak akan 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.

Profiler Wall bergantung pada modul sinyal Python. Jika interpreter 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 flag py-call-osafterfork ke true.

Lihat topik sebelumnya dalam tabel ini untuk masalah terkait.
Setelah mengaktifkan profiler, log error 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 deskriptor file bangun sinyal, signal.set_wakeup_fd. Secara default, jika buffer deskriptor file terisi, peringatan akan dicatat ke stderr.

Saat mengumpulkan profil, Cloud Profiler memicu sinyal dengan frekuensi tinggi. Perilaku ini dapat menyebabkan buffer deskriptor file menjadi penuh.

Jika aplikasi Anda dapat berjalan dengan aman saat sinyal hilang, maka 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 Anda berhenti menggunakan Cloud Profiler. Penggunaan yang terus-menerus dapat menyebabkan hilangnya nomor sinyal dan entri yang berlebihan dalam log error.

Menjalankan dengan Linux Alpine

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

Untuk membuat 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 pada 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 Anda 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 API profiler. Untuk mengatasi error ini, tambahkan perintah apk berikut ke Dockerfile Anda:

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

Kemudian, Anda perlu membangun ulang dan men-deploy ulang aplikasi.

Langkah berikutnya