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, 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 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: integer = 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: 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 command 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 command using--
viztracer --exclude_files file1 file2 -- my_scrpit.py
- ignore_c_function: boolean = False
Whether trace c function
Setting it to
True
is equivalent toviztracer --ignore_c_function
- ignore_frozen: boolean = False
Whether trace functions from frozen functions(mostly import stuff)
Setting it to
True
is equivalent toviztracer --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 toviztracer --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 toviztracer --log_func_args
- log_print: boolean = False
Whether replace the
print
function to log in VizTracer reportSetting it to
True
is equivalent toviztracer --log_print
- log_gc: boolean = False
Whether log garbage collector
Setting it to
True
is equivalent toviztracer --log_gc
- log_async: boolean = False
Whether log async tasks as separate “thread” in vizviewer
Setting it to
True
is equivalent toviztracer --log_async
- 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. 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)
- 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 tooutput_file
- save(output_file=None)
parse data and save report to
output_file
. Ifoutput_file
isNone
, save to default path.
- start()
start tracing
- stop()
stop 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
ort
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 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)