VizTracer
VizTracer is a low-overhead logging/debugging/profiling tool that can trace and visualize your python code execution.
You can take a look at the demo result of multiple example programs. Use "AWSD" to zoom/navigate. More help can be found by clicking "?" on the top right corner.
trace viewer is used to display the stand alone html data.
Highlights
- Detailed function entry/exit information on timeline with source code
- Super easy to use, no source code change for most features, no package dependency
- Optional function filter to ignore functions you are not interested
- Custom events to log and track arbitrary data through time
- Log arbitrary function/variable using RegEx without code change
- Stand alone HTML report with powerful front-end, or chrome-compatible json
- Works on Linux/MacOS/Windows
Install
The prefered way to install VizTracer is via pip
pip install viztracer
Basic Usage
Command Line
Assume you have a python script to run:
python3 my_script.py arg1 arg2
You can simply use VizTracer by
viztracer my_script.py arg1 arg2
# OR
python3 -m viztracer my_script.py arg1 arg2
which will generate a result.html file in the directory you run this command, which you can open with Chrome(use AWSD to navigate/zoom).
You can also generate json file or gz file and load it with chrome://tracing/ or perfetto. gz file is especially helpful when your trace file is large
viztracer -o result.json my_script.py arg1 arg2
viztracer -o result.json.gz my_script.py arg1 arg2
Inline
You can also manually start/stop VizTracer in your script as well.
from viztracer import VizTracer
tracer = VizTracer()
tracer.start()
# Something happens here
tracer.stop()
tracer.save() # also takes output_file as an optional argument
Or, you can do it with with statement
with VizTracer(output_file="optional.html") as tracer:
# Something happens here
Display Result
By default, VizTracer will generate a stand alone HTML file which you can simply open with Chrome.
However, you can generate json file as well, which complies to the chrome trace event format. You can load the json file on perfetto or chrome://tracing.
When you are dealing with big traces, a stand alone HTML file might be very large and hard to load. You should try to dump a compressed filename.json.gz file
Advanced Usage
Trace Filter
VizTracer can filter out the data you don't want to reduce overhead and keep info of a longer time period before you dump the log.
Extra Logs without Code Change
VizTracer can log extra information without changing your source code
print()function- Garbage Collector Operation
- Function Input Arguments
- Function Return Value
- Function Entry
- Any Variable/Attribute with RegEx
- Variables in Specified Function
- Raised Exceptions
Add Custom Event
VizTracer supports inserting custom events while the program is running. This works like a print debug, but you can know when this print happens while looking at trace data.
Check more advanced usage for more features
Misc
Multi Thread Support
VizTracer supports python native threading module without the need to do any modification to your code. Just start VizTracer before you create threads and it will just work.
Multi Process Support
VizTracer supports subprocess with --log_subprocess and multiprocessing or os.fork() with --log_multiprocess.
For more general multi-process cases, VizTracer can support with some extra steps.
Refer to multi process docs for details
JSON alternative
VizTracer needs to dump the internal data to json format. It is recommended for the users to install orjson, which is much faster than the builtin json library. VizTracer will try to import orjson and fall back to the builtin json library if orjson does not exist.
Virtual Debug
You can virtually debug your program with you saved json report. The interface is very similar to pdb. Even better, you can go back in time
because VizTracer has all the info recorded for you.
vdb <your_json_report>
Refer to the docs for detailed commands
Performance
VizTracer will introduce 2x to 3x overhead in the worst case. The overhead is much better if there are less function calls or if filters are applied correctly.
An example run for test_performance with Python 3.8 / Ubuntu 18.04.4 on Github VM
fib:
0.000678067(1.00)[origin]
0.019880272(29.32)[py] 0.011103901(16.38)[parse] 0.021165599(31.21)[json]
0.001344933(1.98)[c] 0.008181911(12.07)[parse] 0.015789866(23.29)[json]
0.001472846(2.17)[cProfile]
hanoi (6148, 4100):
0.000550255(1.00)[origin]
0.016343521(29.70)[py] 0.007299123(13.26)[parse] 0.016779364(30.49)[json]
0.001062505(1.93)[c] 0.006416136(11.66)[parse] 0.011463236(20.83)[json]
0.001144914(2.08)[cProfile]
qsort (8289, 5377):
0.002817679(1.00)[origin]
0.052747431(18.72)[py] 0.011339725(4.02)[parse] 0.023644345(8.39)[json]
0.004767673(1.69)[c] 0.008735166(3.10)[parse] 0.017173703(6.09)[json]
0.007248019(2.57)[cProfile]
slow_fib (1135, 758):
0.028759652(1.00)[origin]
0.033994071(1.18)[py] 0.001630461(0.06)[parse] 0.003386635(0.12)[json]
0.029481623(1.03)[c] 0.001152415(0.04)[parse] 0.002191417(0.08)[json]
0.028289305(0.98)[cProfile]
Documentation
For full documentation, please see https://viztracer.readthedocs.io/en/stable
Bugs/Requests
Please send bug reports and feature requests through github issue tracker. VizTracer is currently under development now and it's open to any constructive suggestions.
License
Copyright Tian Gao, 2020.
Distributed under the terms of the Apache 2.0 license.
1 maintainer
Release files for viztracer 0.9.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| viztracer-0.9.5.tar.gz | 678.3 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| viztracer-0.9.5-cp39-cp39-win_amd64.whl | CPython 3.9 | CPython 3.9 | Windows x86-64 | Details |
| viztracer-0.9.5-cp39-cp39-manylinux2014_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.17+ x86-64 | Details |
| viztracer-0.9.5-cp39-cp39-macosx_10_14_x86_64.whl | CPython 3.9 | CPython 3.9 | macOS 10.14+ x86-64 | Details |
| viztracer-0.9.5-cp38-cp38-win_amd64.whl | CPython 3.8 | CPython 3.8 | Windows x86-64 | Details |
| viztracer-0.9.5-cp38-cp38-manylinux2014_x86_64.whl | CPython 3.8 | CPython 3.8 | Linux glibc 2.17+ x86-64 | Details |
| viztracer-0.9.5-cp38-cp38-macosx_10_14_x86_64.whl | CPython 3.8 | CPython 3.8 | macOS 10.14+ x86-64 | Details |
| viztracer-0.9.5-cp37-cp37m-win_amd64.whl | CPython 3.7 | CPython 3.7 pymalloc | Windows x86-64 | Details |
| viztracer-0.9.5-cp37-cp37m-manylinux2014_x86_64.whl | CPython 3.7 | CPython 3.7 pymalloc | Linux glibc 2.17+ x86-64 | Details |
| viztracer-0.9.5-cp37-cp37m-macosx_10_14_x86_64.whl | CPython 3.7 | CPython 3.7 pymalloc | macOS 10.14+ x86-64 | Details |
| viztracer-0.9.5-cp36-cp36m-win_amd64.whl | CPython 3.6 | CPython 3.6 pymalloc | Windows x86-64 | Details |
| viztracer-0.9.5-cp36-cp36m-manylinux2014_x86_64.whl | CPython 3.6 | CPython 3.6 pymalloc | Linux glibc 2.17+ x86-64 | Details |
| viztracer-0.9.5-cp36-cp36m-macosx_10_14_x86_64.whl | CPython 3.6 | CPython 3.6 pymalloc | macOS 10.14+ x86-64 | Details |
Total release size: 9.1 MB
Release files / viztracer-0.9.5.tar.gz
| Download URL | viztracer-0.9.5.tar.gz |
|---|---|
| Size | 678.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e6afc7e928e257a9bdf9eb48604ac1b4102ee2db1113a9fcad5d327aba191f0
|
|
BLAKE2b-256 checksum How to use checksums |
b877f17217f051f1e17025aed6107194c557a1796d6a58e2045c8710a0f154fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp39-cp39-win_amd64.whl
| Download URL | viztracer-0.9.5-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 688.5 kB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
25e771785d70819e3d63bb708123bd541475b679614c5c1250c1923cdb122870
|
|
BLAKE2b-256 checksum How to use checksums |
3f38fa1de31f1304bae8d2bb104e02181b955d56eb2e16d1670897e7220af29b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.9.0
|
Release files / viztracer-0.9.5-cp39-cp39-manylinux2014_x86_64.whl
| Download URL | viztracer-0.9.5-cp39-cp39-manylinux2014_x86_64.whl |
|---|---|
| Size | 725.8 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
87d639d27fa3d4ebfd013772d2094d1e644c589599740071bf945d0ab8459640
|
|
BLAKE2b-256 checksum How to use checksums |
960670745d9a74ad67de1e0fd585a900f71f11225f4e461336fa3a1026df7161
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp39-cp39-macosx_10_14_x86_64.whl
| Download URL | viztracer-0.9.5-cp39-cp39-macosx_10_14_x86_64.whl |
|---|---|
| Size | 684.7 kB |
| Tags | CPython 3.9 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
016284e35f1512423304f9bce5cff4a95bc7b563b07f2ca962b935fc9c356169
|
|
BLAKE2b-256 checksum How to use checksums |
07feaf1f6ee09bbbed1376c6d6dfc040eb322a9aa606c36cf49e86062f464f63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.9.0
|
Release files / viztracer-0.9.5-cp38-cp38-win_amd64.whl
| Download URL | viztracer-0.9.5-cp38-cp38-win_amd64.whl |
|---|---|
| Size | 688.4 kB |
| Tags | CPython 3.8 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
1b30d6bc6c9ad1cd3da603099fb56837874c58372fabea3709c10452c733410e
|
|
BLAKE2b-256 checksum How to use checksums |
85f3b9cb280a796da3eb1a7ea5e464c5c272393eecf3054d5f7ca0c5b107e43d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp38-cp38-manylinux2014_x86_64.whl
| Download URL | viztracer-0.9.5-cp38-cp38-manylinux2014_x86_64.whl |
|---|---|
| Size | 732.2 kB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
7dad6dc7dd6fe6b7a49f0dd6617fcb57d8e64a2f912c3a8213def8d8b26e8d5a
|
|
BLAKE2b-256 checksum How to use checksums |
b7953dd120e4c96646d665b4706968a4d4045b9ea1c03ef0f435c75edb9f3277
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp38-cp38-macosx_10_14_x86_64.whl
| Download URL | viztracer-0.9.5-cp38-cp38-macosx_10_14_x86_64.whl |
|---|---|
| Size | 684.7 kB |
| Tags | CPython 3.8 macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
d0698873e5c98b5c5ae38ddbb61ef11002188778940d660e0bc01319c914c555
|
|
BLAKE2b-256 checksum How to use checksums |
963846032adde13ffdb5a26abb468426faa75499f1381c206963e2349c9479a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp37-cp37m-win_amd64.whl
| Download URL | viztracer-0.9.5-cp37-cp37m-win_amd64.whl |
|---|---|
| Size | 688.3 kB |
| Tags | CPython 3.7 CPython 3.7 pymalloc Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6087a2ce1ad26503b608704094196245604d8659d2c794c41d840e5f0a4129a3
|
|
BLAKE2b-256 checksum How to use checksums |
6f7e18664ccbe2a48b337493c8acdb5a267a7047fefc194e5d9f7d8f84f78a20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/47.1.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.7.9
|
Release files / viztracer-0.9.5-cp37-cp37m-manylinux2014_x86_64.whl
| Download URL | viztracer-0.9.5-cp37-cp37m-manylinux2014_x86_64.whl |
|---|---|
| Size | 722.1 kB |
| Tags | CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
c6347f33dbe82c6edf46bdcd6b6590e1ba5c233f3538d7d8a41409a7ef8f236f
|
|
BLAKE2b-256 checksum How to use checksums |
551270e309f98484c69060060f6f2d8b1ede6ad72e24d26a68a123291cdaa52c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp37-cp37m-macosx_10_14_x86_64.whl
| Download URL | viztracer-0.9.5-cp37-cp37m-macosx_10_14_x86_64.whl |
|---|---|
| Size | 684.6 kB |
| Tags | CPython 3.7 CPython 3.7 pymalloc macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
1a91ac75054b3f8d7d4732e70b68a8fcd0534385449ec7151114c3795ed13101
|
|
BLAKE2b-256 checksum How to use checksums |
88474fe9cc8cee7ca089ab90d21b96d286aafb0de9d7bdb87ce6ba6023d5d18c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/47.1.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.7.9
|
Release files / viztracer-0.9.5-cp36-cp36m-win_amd64.whl
| Download URL | viztracer-0.9.5-cp36-cp36m-win_amd64.whl |
|---|---|
| Size | 688.3 kB |
| Tags | CPython 3.6 CPython 3.6 pymalloc Windows x86-64 |
|
SHA-256 checksum How to use checksums |
3f729ec462af196c5a1167210e370a67466e65474f57c00b905ca640d0bc0351
|
|
BLAKE2b-256 checksum How to use checksums |
06e72afa924ef418d6e66042894c6c90b2099ed0218770aea0abc88f1d8e3451
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.6.8
|
Release files / viztracer-0.9.5-cp36-cp36m-manylinux2014_x86_64.whl
| Download URL | viztracer-0.9.5-cp36-cp36m-manylinux2014_x86_64.whl |
|---|---|
| Size | 721.1 kB |
| Tags | CPython 3.6 CPython 3.6 pymalloc Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
6a79d807ea7bdabed33e609f01f66411131f19f4e834ca6500c033e5a6be1300
|
|
BLAKE2b-256 checksum How to use checksums |
e2f8650405ece8abfc4eaf96d751852bd742ab0cf39562c3b269613969281d1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6
|
Release files / viztracer-0.9.5-cp36-cp36m-macosx_10_14_x86_64.whl
| Download URL | viztracer-0.9.5-cp36-cp36m-macosx_10_14_x86_64.whl |
|---|---|
| Size | 684.6 kB |
| Tags | CPython 3.6 CPython 3.6 pymalloc macOS 10.14+ x86-64 |
|
SHA-256 checksum How to use checksums |
88846aa01798e514e213c04f04a302a270a6f614c60e2665b2e3d5ca62f58e7c
|
|
BLAKE2b-256 checksum How to use checksums |
f85aab41b65950f8ece2d845425ba1a936d4101514c80e3cc38129b9d8bd1d68
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.6.12
|
