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 linePlease 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 entriesVizTracer
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 tracingSetting it to
0
is equivalent toviztracer --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 toviztracer --ignore_c_function
- ignore_frozen: bool = False
Whether trace functions from frozen functions(mostly import stuff)
Setting it to
True
is equivalent toviztracer --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 toviztracer --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 toviztracer --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 beTrue
iflog_func_repr
is given.Setting it to
True
is equivalent toviztracer --log_func_with_objprint
- log_print: bool = False
Whether replace the
print
function to log in VizTracer reportSetting it to
True
is equivalent toviztracer --log_print
- log_gc: bool = False
Whether log garbage collector
Setting it to
True
is equivalent toviztracer --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 toviztracer --log_async
- log_torch: bool = False
Whether log native torch events
Setting it to
True
is equivalent toviztracer --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. WhenVizTracer()
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 tooutput_file
- save(output_file=None, file_info=None, verbose=None)
parse data and save report to
output_file
. Ifoutput_file
isNone
, 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
orcounter
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 argumentargs (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 methodNotice that the
callback
argument should be acallable
that takes aVizTracer
object as the first argumentfrom 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