Basic Usage

Command Line

The easiest way to use VizTracer is through command line. Assume you have a python script to profile and the normal way to run it is:


You can simply use VizTracer by

# These two commands are equivalent.
# In this docs, they might both be used, but you can choose either one that you prefer.
# OR
python3 -m viztracer

which will generate a result.json file in the directory you run this command. You can open it with vizviewer

vizviewer result.json

If your script needs arguments like

python3 arg1 arg2

Just feed it as it is to viztracer

viztracer arg1 arg2

It’s possible that there’s a conflict or an ambiguity. viztracer takes -- as a separator between arguments to viztracer and positional arguments to your script.

viztracer -o result.json -- -o output_for_my_script.json

You can also run a module with VizTracer

viztracer -m your_module

You can specify the output file using -o or --output_file argument. The default output file is result.json. Three types of files are supported, html, json and gz(gzip of json file).

viztracer -o other_name.html
viztracer -o other_name.json
viztracer -o other_name.json.gz

You can also show flamegraph from result.json file

vizviewer --flamegraph result.json


Sometimes the command line may not work as you expected, or you do not want to profile the whole script. You can manually start/stop the profiling in your script as well.

First of all, you need to import VizTracer class from the package

from viztracer import VizTracer

You can trace code with with statement

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

Or you can create a VizTracer object and manually enable/disable the profile using start() and stop() function.

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


If you are using Jupyter, you can use viztracer cell magics.

# You need to load the extension first
%load_ext viztracer
# Your code after

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

Display Report

VizTracer will generate a result.json by default, which could be opened with vizviewer

vizviewer result.json

You can also display all the files in a directory and open the reports in browser too. This is helpful when you have many files in one directory and want to check some or all of them.

This could also be used when you have a report directory where reports are frequently added. You can leave vizviewer in the background and browse your reports with pure browser.

vizviewer your_directory/

vizviewer will bring up webbrowser and open the report by default. You can disable this feature and only host an HTTP server on localhost:9001, which you can access through your browser

vizviewer --server_only result.json

If you do not want to host the HTTP server forever, you can use --once so the server will shut down after serve the trace file

vizviewer --once result.json

You can also show flamegraph of the result

vizviewer --flamegraph result.json

vizviewer can also show standalone html report - it just host a simple HTTP server for the file

vizviewer result.html

Or, you can use --open for viztracer, it will then open the report after it generates it

viztracer --open
viztracer -o result.html --open

Circular Buffer Size

VizTracer used circular buffer to store the entries. When there are too many entries, it will only store the latest ones so you know what happened recently. The default buffer size is 1,000,000(number of entries), which takes about 150MiB disk space. You can specify this when you instantiate VizTracer object

Notice it also takes significant amount of RAM when VizTracer is tracing the program.

VizTracer will preallocate about tracer_entries * 100B RAM for circular buffer. It also requires about 1-2MB per 10k entries to dump the json file.

viztracer --tracer_entries 500000


tracer = VizTracer(tracer_entries=500000)

Configuration file

You can use a configuration file to set the default options for viztracer, which could help you avoid typing the same arguments for multiple runs.

The default filename for viztracer configuration file is .viztracerrc. viztracer will try to find .viztracerrc in current working directory. You can also specify your own configuration file with viztracer --rcfile <your_config_file>. The format of the configuration file is very similar to ini file, which could be parsed by built in configparser.

log_var = a.* latest
ignore_c_function = True
output_file = vizreport.json
max_stack_depth = 10

[default] can’t be omitted and all the arguments should be in a key-value pair format, where key is the argument name(without --) and val is the value you need to pass in. Please notice that there are some arguments in viztracer that do not take parameters(like –ignore_c_function`), you need to pass True in the config file to make the config parser happy. If you need to pass multiple parameters to an argument(like log_var), just use space to separate the parameters like you do in cmdline interface.

Combine Reports

VizTracer can put multiple json reports together and generate a new trace file. This is especially helpful when you have multiple trace generators, for example, running multiple processes with VizTracer. As VizTracer uses Monotonic Clock, you can save reports with different VizTracer instances without worrying about timestamp alignment issue. You can even generate your own data and combine with VizTracer reports, like VizPlugins does.

viztracer --combine process1.json process2.json -o full_report.json

Another usage of combining reports would be to compare between different runs of the same program. Unlike combining from multiple sources, this requires a pre-alignment of all the trace data. VizTracer also provides a way to align the start of all reports for this usage.

viztracer --align_combine run1.json run2.json -o compare_report.json

Debug Your Saved Report

VizTracer allows you to debug your json report just like pdb. You can understand how your program is executed by interact with it. Even better, you can go back in time because you know what happened before.

vdb <your_json_report>

For detailed commands, please refer to Virtual Debug