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. viztracer my_script.py # OR python3 -m viztracer my_script.py
which will generate a
result.json file in the directory you run this command. You can open it with
If your script needs arguments like
python3 my_script.py arg1 arg2
Just feed it as it is to
viztracer my_script.py arg1 arg2
It’s possible that there’s a conflict or an ambiguity.
-- as a separator between arguments to
positional arguments to your script.
viztracer -o result.json -- my_script.py -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
--output_file argument. The default output file is
Three types of files are supported, html, json and gz(gzip of json file).
viztracer -o other_name.html my_script.py viztracer -o other_name.json my_script.py viztracer -o other_name.json.gz my_script.py
You can also show flamegraph from
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 the
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
tracer = VizTracer() tracer.start() # Something happens here tracer.stop() tracer.save() # 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
%%viztracer # Your code after
Show VizTracer Report button will appear after the cell and you can click it to view the results
VizTracer will generate a
result.json by default, which could be opened with
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
vizviewer in the background and browse your reports with pure browser.
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 serving the trace file
vizviewer --once result.json
You can serve your HTTP server on a different port with
--port or its equivalent
vizviewer --port 10000 result.json
You can also show flamegraph of the result
vizviewer --flamegraph result.json
You can use the external trace processor with
--use_external_processor, which does not have the
RAM limits as the browser. This is helpful when you try to open a large trace file.
vizviewer --use_external_processor result.json
vizviewer can also show standalone html report - it just host a simple HTTP server for the file
Or, you can use
viztracer, it will then open the report after it generates it
viztracer --open my_script.py viztracer -o result.html --open my_script.py
Circular Buffer Size¶
VizTracer uses a 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 a
Notice it also takes a 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 my_script.py
tracer = VizTracer(tracer_entries=500000)
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
[default] 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 the key is the argument name(without
--) and the 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
use space to separate the parameters like you do in cmdline interface.
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.
This feature will be removed from 0.16.0
For detailed commands, please refer to Virtual Debug
Compress Your Report¶
VizTracer supports compressing your json report. The general compression ratio is about 50:1 to 100:1 for a large report.
You can compress your report with
viztracer --compress result.json -o result.cvf
You can also decompress your report with
viztracer --decompress result.cvf -o result.json