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
• Supports threading, multiprocessing, subprocess and async
• Logs 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

A result.html file will be generated, 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

# Open with chrome trace viewer that shows source code
vizviewer result.html
# Open with perfetto
vizviewer result.json
vizviewer result.json.gz

# 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 statement

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

A Show VizTracer Report button will appear after the cell and you can click it to view the results

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.

• Max Stack Depth
• Include Files
• Exclude Files
• Ignore C Function
• Sparse Log

VizTracer can log extra information without changing your source code

• Any Variable/Attribute with RegEx
• Function Entry
• Variables in Specified Function
• Garbage Collector Operation
• Function Input Arguments
• Function Return Value
• Raised Exceptions

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.

• Instant Event
• Counter Event
• Object Event
• Duration Event

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.

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

VizTracer supports asyncio natively, but could enhance the report by using --log_async.

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.

vdb <your_json_report>

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.

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]

For full documentation, please see https://viztracer.readthedocs.io/en/stable

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.

Copyright Tian Gao, 2020.

Distributed under the terms of the Apache 2.0 license.