VizTracer

class VizTracer(self, tracer_entries=1000000, verbose=1, max_stack_depth=- 1, include_files=None, exclude_files=None, ignore_c_function=False, ignore_frozen=False, log_func_retval=False, log_func_args=False, log_print=False, log_gc=False, log_async=False, vdb=False, pid_suffix=False, register_global=True, min_duration=0, output_file='result.json')
tracer_entries: integer = 1000000

Size of circular buffer. The user can only specify this value when instantiate VizTracer object or if they use command line

Please be aware that a larger number of entries also means more disk space, RAM usage and loading time. Be familiar with your computer’s limit.

tracer_entries means how many entries VizTracer can store. It’s not a byte number.

viztracer --tracer_entries 500000
verbose: integer = 1

Verbose level of VizTracer. Can be set to 0 so it won’t print anything while tracing

Setting it to 0 is equivalent to

viztracer --quiet
max_stack_depth: integer = -1

Specify the maximum stack depth VizTracer will trace. -1 means infinite.

Equivalent to

viztracer --max_stack_depth <val>
include_files: list of string or None = None

Specify the files or folders that VizTracer will trace. If it’s not empty, VizTracer will function in whitelist mode, any files/folders not included will be ignored.

Because converting code filename in tracer is too expensive, we will only compare the input and its absolute path against code filename, which could be a relative path. That means, if you run your program using relative path, but gives the include_files an absolute path, it will not be able to detect.

Can’t be set with exclude_files

Equivalent to

viztracer --include_files file1[ file2 [file3 ...]]

NOTICE

In command line, --include_files takes multiple arguments, which will be ambiguous about the command that actually needs to run, so you need to explicitly specify comand using --

viztracer --include_files file1 file2 -- my_scrpit.py
exclude_files: list of string or None = None

Specify the files or folders that VizTracer will not trace. If it’s not empty, VizTracer will function in blacklist mode, any files/folders not included will be ignored.

Because converting code filename in tracer is too expensive, we will only compare the input and its absolute path against code filename, which could be a relative path. That means, if you run your program using relative path, but gives the exclude_files an absolute path, it will not be able to detect.

Can’t be set with include_files

Equivalent to

viztracer --exclude_files file1[ file2 [file3 ...]]

NOTICE

In command line, --exclude_files takes multiple arguments, which will be ambiguous about the command that actually needs to run, so you need to explicitly specify comand using --

viztracer --exclude_files file1 file2 -- my_scrpit.py
ignore_c_function: boolean = False

Whether trace c function

Setting it to True is equivalent to

viztracer --ignore_c_function
ignore_frozen: boolean = False

Whether trace functions from frozen functions(mostly import stuff)

Setting it to True is equivalent to

viztracer --ignore_frozen
log_func_retval: boolean = False

Whether log the return value of the function as string in report entry

Setting it to True is equivalent to

viztracer --log_func_retval
log_func_args: boolean = False

Whether log the arguments of the function as string in report entry

Setting it to True is equivalent to

viztracer --log_func_args
log_print: boolean = False

Whether replace the print function to log in VizTracer report

Setting it to True is equivalent to

viztracer --log_print
log_gc: boolean = False

Whether log garbage collector

Setting it to True is equivalent to

viztracer --log_gc
log_async: boolean = False

Whether log async tasks as separate “thread” in vizviewer

Setting it to True is equivalent to

viztracer --log_async
vdb: boolean = False

whether make viztracer instrument for vdb, which would affect the overhead and the file size a bit

Setting it to True is equivalent to

viztracer --vdb
register_global: boolean = True

whether register the tracer globally, so every file can use get_tracer() to get this tracer. When command line entry is used, the tracer will be automatically registered. When VizTracer() is manually instantiated, it will be registered as well by default.

Some functions may require a globally registered tracer to work.

This attribute will only be effective when the object is initialized:

tracer = VizTracer(register_global=False)
min_duration: float = 0

Minimum duration of a function to be logged. The value is in unit of us.

output_file: string = "result.json"

Default file path to write report

Equivalent to

viztracer -o <filepath>
run(command, output_file=None)

run command and save report to output_file

save(output_file=None)

parse data and save report to output_file. If output_file is None, save to default path.

start()

start tracing

stop()

start tracing

clear()

clear all the data

cleanup()

clear all the data and free the memory allocated

parse()

parse the data collected, return number of total entries

enable_thread_tracing()

enable tracing in the current thread, useful when you use multi-thread without builtin threading module

add_instant(name, scope='g')
Parameters
  • name (str) – name of this instant event

  • scope (str) – one of g, p or t for global, process or thread level event

Add instant event to the report.

add_func_args(name, key, value)
Parameters
  • key (str) – key to display in the report

  • value (object) – a jsonifiable object

This method allows you to attach args to the current function, which will show in the report when you click on the function

log_event(event_name)
Parameters

event_name (str) – name of this event that will appear in the result

Returns

VizEvent object that should only be used with with statement

Return type

VizEvent

with get_tracer().log_event("event name"):
    # some code here
set_afterfork(callback, *args, **kwargs)
Parameters
  • callback (callable) – the callback function after fork, should take a VizTracer object as the first argument

  • args (list) – positional arguments to callback

  • kwargs (dict) – keyword arguments to callback

This method will register a callback function after the process is forked. If you want different behavior on child processes with multiprocessing, you can utilize this method

Notice that the callback argument should be a callable that takes a VizTracer object as the first argument

from viztracer import get_tracer

def afterfork_callback(tracer):
    tracer.max_stack_depth = 10

get_tracer().set_afterfork(afterfork_callback)