viztracer

ular piton

VizTracer 1.0.0 Release

Unduh

VizTracer

VizTracer adalah alat logging/debugging/profiling dengan overhead rendah yang dapat melacak dan memvisualisasikan eksekusi kode python Anda.

UI front-end didukung oleh Perfetto. Gunakan "AWSD" untuk memperbesar/menavigasi . Bantuan lebih lanjut dapat ditemukan di "Dukungan - Kontrol".

contoh_img

Highlight

Informasi masuk/keluar fungsi terperinci di timeline dengan kode sumber
Sangat mudah digunakan, tidak ada perubahan kode sumber untuk sebagian besar fitur, tidak ada ketergantungan paket
Overhead rendah, mungkin pelacak tercepat di pasar
Mendukung threading, multiprosesing, subproses, async, dan PyTorch
Front-end yang kuat, mampu merender jejak tingkat GB dengan lancar
Bekerja di Linux/MacOS/Windows

Memasang

Cara yang lebih disukai untuk menginstal VizTracer adalah melalui pip

pip install viztracer

Penggunaan Dasar

Baris Perintah

 # Instead of "python3 my_script.py arg1 arg2"
viztracer my_script.py arg1 arg2

File result.json akan dibuat, yang dapat Anda buka dengan vizviewer

 # You can display all the files in a directory and open them in browser too
vizviewer ./
# For very large trace files, try external trace processor
vizviewer --use_external_processor result.json

vizviewer akan meng-host server HTTP di http://localhost:9001 . Anda juga dapat membuka browser Anda dan menggunakan alamat itu.

Jika Anda tidak ingin vizviewer membuka browser web secara otomatis, Anda dapat menggunakan

vizviewer --server_only result.json

Jika Anda hanya perlu menampilkan laporan pelacakan satu kali, dan tidak menginginkan server persisten, gunakan

vizviewer --once result.json

vizviewer result.json

Ekstensi VS Code tersedia untuk membuat hidup Anda lebih mudah.

Tambahkan --open untuk membuka laporan tepat setelah penelusuran

viztracer --open my_script.py arg1 arg2
viztracer -o result.html --open my_script.py arg1 arg2

modul dan skrip konsol (seperti flask ) juga didukung

viztracer -m your_module

viztracer flask run

sebaris

Anda juga dapat memulai/menghentikan VizTracer secara manual di skrip Anda.

 from viztracer import VizTracer

tracer = VizTracer ()
tracer . start ()
# Something happens here
tracer . stop ()
tracer . save () # also takes output_file as an optional argument

Atau, Anda dapat melakukannya dengan pernyataan with

 with VizTracer ( output_file = "optional.json" ) as tracer :
    # Something happens here

Jupyter

Jika Anda menggunakan Jupyter, Anda dapat menggunakan sihir sel viztracer.

 # You need to load the extension first
% load_ext viztracer

 % % viztracer
# Your code after

Tombol VizTracer Report akan muncul setelah sel dan Anda dapat mengkliknya untuk melihat hasilnya

PyTorch

VizTracer dapat mencatat panggilan asli dan peristiwa GPU PyTorch (berdasarkan torch.profiler ) dengan --log_torch .

 with VizTracer ( log_torch = True ) as tracer :
    # Your torch code

viztracer --log_torch your_model.py

Penggunaan Tingkat Lanjut

Filter Jejak

VizTracer dapat memfilter data yang tidak ingin Anda kurangi overhead dan menyimpan informasi dalam jangka waktu yang lebih lama sebelum Anda membuang log.

Durasi Minimal
Kedalaman Tumpukan Maks
Sertakan File
Kecualikan File
Abaikan Fungsi C
Log Jarang

Log Ekstra tanpa Perubahan Kode

VizTracer dapat mencatat informasi tambahan tanpa mengubah kode sumber Anda

Variabel/Atribut apa pun dengan RegEx
Entri Fungsi
Variabel dalam Fungsi Tertentu
Operasi Pengumpul Sampah
Argumen Masukan Fungsi
Nilai Pengembalian Fungsi
Acara Audit
Pengecualian yang Dimunculkan

Tambahkan Acara Khusus

VizTracer mendukung penyisipan acara khusus saat program sedang berjalan. Ini berfungsi seperti debug pencetakan, namun Anda dapat mengetahui kapan pencetakan ini terjadi sambil melihat data jejak.

Acara Instan
Peristiwa Variabel
Durasi Acara

Lain-lain

Dukungan Multi Benang

Untuk Python3.12+, VizTracer mendukung penelusuran multi-thread tingkat Python tanpa perlu melakukan modifikasi apa pun pada kode Anda.

Untuk versi sebelum 3.12, VizTracer mendukung modul threading asli python. Jalankan saja VizTracer sebelum Anda membuat thread dan itu akan berfungsi.

Untuk skenario multi-thread lainnya, Anda dapat menggunakan enable_thread_tracing() untuk memperhatikan VizTracer tentang thread untuk melacaknya.

contoh_img

Lihat dokumen multi-utas untuk detailnya

Dukungan Multi Proses

VizTracer mendukung subprocess , multiprocessing , os.fork() , concurrent.futures , dan loky out of the box.

Untuk kasus multi-proses yang lebih umum, VizTracer dapat mendukung dengan beberapa langkah tambahan.

contoh_img

Lihat dokumen multi proses untuk detailnya

Dukungan Asinkron

VizTracer mendukung asyncio secara asli, tetapi dapat menyempurnakan laporan dengan menggunakan --log_async .

contoh_img

Lihat dokumen async untuk detailnya

grafik api

Perfetto mendukung flamegraph asli, cukup pilih irisan di UI dan pilih "Slice Flamegraph".

contoh_img

Lampirkan jarak jauh

VizTracer mendukung lampiran jarak jauh ke proses Python sewenang-wenang untuk melacaknya, selama viztracer dapat diimpor

Lihat dokumen lampiran jarak jauh

Alternatif JSON

VizTracer perlu membuang data internal ke format json. Disarankan bagi pengguna untuk menginstal orjson , yang jauh lebih cepat daripada perpustakaan json bawaan. VizTracer akan mencoba mengimpor orjson dan kembali ke perpustakaan json bawaan jika orjson tidak ada.

Pertunjukan

VizTracer berupaya keras untuk mencapai overhead yang rendah. Dampak kinerja sebenarnya sangat bergantung pada aplikasi Anda. Untuk basis kode pada umumnya, overhead diharapkan berada di bawah 1x. Jika kode Anda memiliki pemanggilan fungsi yang jarang, biaya overhead mungkin minimal.

Penjelasan rinci

Overhead yang diperkenalkan oleh VizTracer pada dasarnya adalah jumlah waktu tetap selama masuk dan keluar fungsi, sehingga semakin banyak waktu yang dihabiskan untuk masuk dan keluar fungsi, semakin banyak overhead yang akan diamati. Fungsi fib rekursif murni dapat mengalami overhead 3x-4x pada Python3.11+ (saat panggilan Python dioptimalkan, sebelumnya panggilan Python lebih lambat sehingga rasio overhead akan lebih kecil).

Dalam skenario kehidupan nyata, kode Anda tidak boleh menghabiskan terlalu banyak waktu pada pemanggilan fungsi (mereka tidak melakukan sesuatu yang berguna), sehingga overhead akan jauh lebih kecil.

Banyak teknik yang diterapkan untuk meminimalkan keseluruhan overhead selama eksekusi kode untuk mengurangi kemiringan yang tak terhindarkan yang disebabkan oleh VizTracer (bagian penyimpanan laporan tidak begitu penting). Misalnya, VizTracer mencoba menggunakan penghitung stempel waktu CPU alih-alih syscall untuk mendapatkan waktu bila tersedia. Pada Python 3.12+, VizTracer menggunakan sys.monitoring yang memiliki overhead lebih sedikit dibandingkan sys.setprofile . Semua upaya membuatnya jauh lebih cepat daripada cProfile , profiler stdlib Python.

Namun, VizTracer adalah pelacak, yang berarti ia harus mencatat setiap masuk dan keluarnya fungsi, sehingga tidak bisa secepat profiler pengambilan sampel - keduanya tidak sama. Dengan overhead ekstra, VizTracer memberikan lebih banyak informasi dibandingkan profiler pengambilan sampel biasa.

Dokumentasi

Untuk dokumentasi lengkap, silakan lihat https://viztracer.readthedocs.io/en/stable

Bug/Permintaan

Silakan kirim laporan bug dan permintaan fitur melalui pelacak masalah github. VizTracer saat ini sedang dalam pengembangan dan terbuka untuk saran konstruktif apa pun.