Membuat profil aplikasi Python

Halaman ini menjelaskan cara mengubah aplikasi Python untuk mengambil data pembuatan profil dan mengirimkan data tersebut ke project Google Cloud Anda. Untuk mengetahui 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 atau yang lebih tinggi.

Versi agen pembuatan profil yang didukung:

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

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 Berjalan di Linux Alpine.

Lingkungan yang didukung:

Mengaktifkan Profiler API

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

gcloud CLI

  1. Jika 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. Di panel navigasi Konsol Google Cloud, pilih APIs & Services, klik Enable APIs and Services, lalu aktifkan Cloud Profiler API:

    Buka setelan Profiler API

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

Menggunakan Cloud Profiler

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

Compute Engine

Untuk Compute Engine, lakukan hal berikut:

  1. Instal alat compiler dan 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 berdasarkan 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 berdasarkan 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 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.

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
service1 (Wajib) Nama layanan yang sedang dibuat profilnya. Untuk batasan nama layanan, lihat Argumen nama dan versi layanan.
service_version1 (Opsional) Versi layanan yang sedang dibuat profilnya. Untuk batasan pada versi layanan, lihat Argumen nama dan versi layanan.
verbose (Opsional) Level logging. Untuk mengetahui detail tentang tingkat logging, lihat Logging agen.

Nilai defaultnya adalah 0 (Error).
project_id2 (Opsional) Project ID Google Cloud Anda.
disable_cpu_profiling (Opsional) Untuk menonaktifkan pembuatan profil waktu CPU, setel 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 akan diabaikan.

Nilai defaultnya adalah False.
disable_wall_profiling (Opsional) Untuk menonaktifkan Pembuatan profil dinding, tetapkan disable_wall_profiling=True.

Parameter ini didukung untuk Python 3.6 dan yang lebih tinggi. Untuk semua versi Python lainnya, Pembuatan profil dinding tidak didukung dan parameter ini akan diabaikan.

Untuk batasan pada fungsi start saat Pembuatan profil dinding diaktifkan, lihat Batasan.

Nilai defaultnya adalah False.

1 Hanya untuk Compute Engine dan GKE. Untuk App Engine, nilai tersebut berasal dari lingkungan.
2 Untuk Google Cloud, nilai tersebut 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.

Pada panel navigasi konsol Google Cloud, pilih Profiler:

Buka Profiler

Argumen nama dan versi layanan

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

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

Misalnya, jika Anda memiliki layanan dengan dua versi yang berjalan di 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 sebetulnya lebih tinggi.

Saat memilih nama layanan:

  • Pilih nama yang secara jelas menggambarkan layanan dalam arsitektur aplikasi Anda. Pilihan nama layanan tidak begitu penting jika Anda hanya menjalankan satu layanan atau aplikasi. Akan lebih penting lagi jika aplikasi Anda berjalan sebagai sekumpulan layanan mikro.

  • Pastikan untuk tidak menggunakan nilai khusus proses apa pun, 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])?$

Panduan 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. Layanan ini dapat digunakan untuk menandai versi layanan Anda yang berbeda saat di-deploy. UI Profiler memungkinkan Anda memfilter data berdasarkan 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 guna mencatat pesan ke dalam log 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 : Men-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 spesifik untuk pembuatan 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 pada thread utama. Jika thread utama tidak dapat dijalankan, tidak ada data pembuatan profil yang akan diambil.

Pengecualian

Error Penyebab Solusi
NotImplementedError ditampilkan selama start Aplikasi dijalankan dalam 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 profiling waktu CPU dan pembuatan profil waktu dinding dinonaktifkan.
  • Pastikan nama dan versi layanan memenuhi persyaratan yang ditentukan dalam Argumen nama dan versi layanan.
  • Jika Wall profiling diaktifkan, pastikan start dipanggil dari thread utama.
  • Pastikan Anda menggunakan versi Python yang didukung dan bahwa profil waktu CPU atau Waktu proses aktif diaktifkan. Untuk mengetahui 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 mengaktifkan jenis profil baru dan tidak memiliki data profil. Penyebab umumnya terkait dengan konfigurasi. Lihat Pemecahan masalah.
Anda menggunakan uWSGI dan tidak memiliki waktu CPU serta data Profil dinding untuk semua proses.

Jika uWSGI menggunakan beberapa pekerja untuk menangani permintaan, perilaku defaultnya adalah melakukan inisialisasi aplikasi hanya dalam proses utama ("master"). Proses yang bercabang tidak melakukan urutan inisialisasi.

Jika Anda mengonfigurasi agen pembuatan profil dalam urutan inisialisasi aplikasi, misalnya, dalam AppConfig.ready() dalam aplikasi Django, efeknya adalah agen pembuatan profil tidak dikonfigurasi untuk proses yang bercabang.

Untuk melakukan inisialisasi aplikasi di semua proses pekerja, setel flag lazy-apps ke true.

Lihat topik berikutnya dalam tabel ini untuk masalah terkait.
Anda menggunakan uWSGI dan tidak memiliki data profil Dinding, 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 bercabang.

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 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 deskriptor file bangun sinyal, signal.set_wakeup_fd. Secara default, jika buffer deskriptor file terisi, peringatan akan dicatat ke dalam log ke stderr.

Saat mengumpulkan profil, Cloud Profiler memicu sinyal dengan frekuensi yang tinggi. Perilaku ini bisa menyebabkan buffer deskriptor 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 jumlah sinyal dan entri berlebihan di log error.

Berjalan dengan Linux Alpine

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

Untuk membangun agen pembuatan profil Python, Anda harus menginstal paket build-base. Untuk menggunakan agen pembuatan profil Python di Alpine tanpa menginstal dependensi tambahan pada 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 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 harus membangun ulang dan men-deploy ulang aplikasi Anda.

Langkah selanjutnya