Extra Log
VizTracer features with many extra log possibilities without even changing your source code. You can start VizTracer from command line and use command line arguments to control what you need to log.
Log Variable
You can log any variable using regex matching to the variable name.
This is like adding print
after assigning the variable without actually writing the code.
The log will appear in the report as an Instant Event, and the variables repr
will be showed
viztracer --log_var <var_name> -- my_script.py
--
is added to resolve the ambiguity. Every time a variable matches regex <var_name>
is assigned a value, it will be logged.
If you don’t know what regex is, simply using the full name of the variable as <var_name>
will allow you to log the variable
Log Number
Similar to Log Variable, you can log any variable as a number, which will be logged as Counter Event.
The report will visualize the number through time as a separate signal like VizCounter
did.
viztracer --log_number <var_name> -- my_script.py
--
is added to resolve the ambiguity. Every time a variable matches regex <var_name>
is assigned a value, it will be logged.
If you don’t know what regex is, simply using the full name of the variable as <var_name>
will allow you to log the variable
Using --log_number
on non-numeric variables will raise an exception.
Log Attribute
You can log writes to attributes based on the name of the attribute. This is useful when you want to track an attribute of
an object, but there are just too many entries to it. It could be self.attr_name
, obj.attr_name
or even
obj_list[0].attr_name
. With log_attr
you can log the attributes matching the regex as an Instant Event.
viztracer --log_attr <attr_name> -- my_script.py
--
is added to resolve the ambiguity. Every time an attribute matches regex <attr_name>
is assigned a value, it will be logged.
If you don’t know what regex is, simply using the full name of the attribute as <attr_name>
will allow you to log the attribute
Log Function Entry
You can log when a function is called. This is helpful to label the timeline for some crucial function. The log will be displayed as an Instant Event.
viztracer --log_func_entry <func_name> -- my_script.py
--
is added to resolve the ambiguity. Every time an function matches regex <func_name>
is called, it will be logged.
If you don’t know what regex is, simply using the full name of the function as <func_name>
will allow you to log the function
Log Function Execution
You can log function execution details. VizTracer will record all the assignments in specified functions and display
them in the detailed information of the generated report. The log will be showed in function entry’s args
list.
viztracer --log_func_exec <func_name> -- my_script.py
--
is added to resolve the ambiguity. Every time an function matches regex <func_name>
is called, its execution will be logged.
If you don’t know what regex is, simply using the full name of the function as <func_name>
will allow you to log the function
Log Audit
You can log audit events introduced since python 3.8. The audit events will be logged as instant events.
# -- is added to resolve ambiguity
viztracer --log_audit import builtins.input -- my_script.py
# regex is supported
viztracer --log_audit os.* -- my_script.py
# If no argument is given, log every audit
viztracer --log_audit -- my_script.py
# You sometimes need to quote the regex to avoid command line ambiguity
# (Linux terminal would think that you are passing files starts with '.')
viztracer --log_audit ".*" -- my_script.py
Log Exception
You can log raised exceptions. All raised exceptions, whether caught or not, will be displayed as an Instant Event in the report.
viztracer --log_exception my_script.py
Log Function Arguments
You can log every function’s arguments as string
, aka their __repr__
. The arguments will be stored in each python function entry
under args["func_args"]
. You can overwrite the object’s __repr__
function to log the object as you need.
You can enable this feature in command line or using inline.
viztracer --log_func_args my_script.py
tracer = VizTracer(log_func_args=True)
This feature will introduce a very large overhead(depends on your argument list), so be aware of it
You can log additional arbitrary (key, value) pairs for your function entry using add_func_args()
. Refer to VizTracer for it’s usage
Log Function Return Value
VizTracer can log every function’s return value as string
, aka it’s __repr__
. The return value will be stored in each python function entry
under args["return_value"]
. You can overwrite the object’s __repr__
function to log the object as you need.
You can enable this feature in command line or using inline.
viztracer --log_func_retval my_script.py
tracer = VizTracer(log_func_retval=True)
Log Print
You can intercept print()
function and record the data it prints to the report as an Instant Event. This is like doing print debug on timeline.
You can do this simply by:
viztracer --log_print my_script.py
OR
tracer = VizTracer(log_print=True)
Log Garbage Collector
You can log the optional garbage collector module in Python. Notice that in CPython, most garbage collection is done using reference count. The garbage collector module is only responsible for the cycle reference. So this feature is mainly used to detect cycle reference collection status, and the time consumed by running the optional garbage collector.
You can do this simply by:
viztracer --log_gc my_script.py
OR
tracer = VizTracer(log_gc=True)
Log Exit data
Normally VizTracer only logs the executed code in “execution phase”, or “within exec() function”. You can, however, log functions
in atexit
or other on-exit hooks.
viztracer --log_exit my_script.py
Work with logging
module
VizTracer can work with python builtin logging
module by adding a handler to it. The report will show logging
data as Instant Events.
from viztracer import VizTracer, VizLoggingHandler
tracer = VizTracer()
handler = VizLoggingHandler()
handler.setTracer(tracer)
# A handler is added to logging so logging will dump data to VizTracer
logging.basicConfig(handlers = [handler])