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. The UI is powered by Chrome Trace Viewer. Use "AWSD" to zoom/navigate. More help can be found by clicking "?" on the top right corner.
- 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
The prefered way to install VizTracer is via pip
pip install viztracer
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
which will generate a
result.html file in the directory you run this command, which you can open with Chrome.
viztracer -o result.json my_script.py arg1 arg2 viztracer -o result.json.gz my_script.py arg1 arg2
vizviewer to open the reports to save trouble
# Open with chrome trace viewer that shows source code vizviewer result.html # Open with perfetto vizviewer result.json vizviewer result.json.gz
--open to open the reports right after tracing
# Open with chrome trace viewer that shows source code viztracer --open my_scripy.py arg1 arg2 # Open with perfetto viztracer -o result.json --open my_script.py arg1 arg2 viztracer -o result.json.gz --open my_script.py arg1 arg2
As Chrome Trace Viewer is already deprecated, we will gradually lean towards perfetto which is
much faster when loading large trace files.
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 VizTracer(output_file="optional.html") as tracer: # Something happens here
If you are using Jupyter, you can use viztracer cell magics.
# You need to load the extension first %load_ext viztracer
%%viztracer # Your code after
Show VizTracer Report button will appear after the cell and you can click it to view the results
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
For more general multi-process cases, VizTracer can support with some extra steps.
Refer to multi process docs for details
asyncio natively, but could enhance the report by using
Refer to async docs for details
VizTracer supports remote attach to a process as long as you installed VizTracer on that process.
Refer to remote attach docs
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.
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.
Refer to the docs for detailed commands
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]