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_func_repr=None, log_func_with_objprint=None, log_print=False, log_gc=False, log_sparse=False, log_async=False, log_torch=False, log_audit=False, pid_suffix=False, file_info=True, register_global=True, trace_self=False, min_duration=0, minimize_memory=False, dump_raw=False, sanitize_function_name=False, process_name=None, output_file='result.json', plugins=None)
tracer_entries: int = 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: int = 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: int = -1

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

Equivalent to

viztracer --max_stack_depth <val>
include_files: list[str] | 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 command using --

viztracer --include_files file1 file2 -- my_scrpit.py
exclude_files: list[str] | 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 command using --

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

Whether trace c function

Setting it to True is equivalent to

viztracer --ignore_c_function
ignore_frozen: bool = False

Whether trace functions from frozen functions(mostly import stuff)

Setting it to True is equivalent to

viztracer --ignore_frozen
log_func_retval: bool = 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: bool = 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_func_repr: Callable[..., str] | None = None

A custom repr function to log the function arguments and return value. The function should take a single argument and return a string.

log_func_with_objprint: bool = False

Whether log the arguments and return value of the function with objprint. This attribute can’t be True if log_func_repr is given.

Setting it to True is equivalent to

viztracer --log_func_with_objprint
log_print: bool = False

Whether replace the print function to log in VizTracer report

Setting it to True is equivalent to

viztracer --log_print
log_gc: bool = False

Whether log garbage collector

Setting it to True is equivalent to

viztracer --log_gc
log_sparse: bool = False

Whether initialize the tracer in log_sparse mode. In this mode, the tracer will start as a context.

This option should be used when you are using inline tracing with @log_sparse

log_async: bool = False

Whether log async tasks as separate “thread” in vizviewer

Setting it to True is equivalent to

viztracer --log_async
log_torch: bool = False

Whether log native torch events

Setting it to True is equivalent to

viztracer --log_torch
log_audit: Sequence[str] | None = None

The audit events to log.

Equivalent to

viztracer --log_audit event1[ event2 [event3 ...]]
pid_suffix: bool = False

Whether append pid to the output file name.

Equivalent to

viztracer --pid_suffix
file_info: bool = False

Whether save the file_info in the report.

register_global: bool = 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)
trace_self: bool = False

whether trace the function calls of the tracer itself.

min_duration: float = 0

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

minimize_memory: bool = False

Whether make effort to minimize the RAM usage when dumping the data.

dump_raw: bool = False

Whether use the raw dump for json report. This is usually faster because it dumps directly in C.

sanitize_function_name: bool = False

Whether check the function name before dump. This is useful for dymanically generated PyMethodDef.

process_name: str | None = None

The process name to display in the report.

output_file: string = "result.json"

Default file path to write report

Equivalent to

viztracer -o <filepath>
plugins: Sequence[VizPluginBase | str] | None = None

List of plugins to use.

run(command, output_file=None)

run command and save report to output_file

save(output_file=None, file_info=None, verbose=None)

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

start()

start tracing

stop(stop_option=None)

stop tracing. The only valid value for stop_option is "flush_as_finish". When defined, VizTracer will log all the unfinished functions.

clear()

clear all the collected data

parse()

parse the data collected, return number of total entries

enable_thread_tracing()

Not needed on Python3.12+.

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

add_variable(name, var, event='instant')
Parameters:
  • name (str) – name of this variable

  • var (object) – variable to be added

  • event (str) – one of instant or counter

Add variable to the report. event determines the logging type.

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

  • args (object) – the arguments 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_counter(name, args)
Parameters:
  • name (str) – name of this counter event

  • args (object) – the arguments of this counter event

Add counter event to the report.

add_raw(raw)
Parameters:

raw (object) – the raw chrome trace event to add to the report

Add a raw 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)
getts()
Returns:

current timestamp in us

Return type:

int

Get current timestamp in us

get_base_time()
Returns:

the base time of the tracer in ns

Return type:

int

Get the base time of the tracer