You may want to insert custom events to the report while you are tracing the program.
VizTracer supports three kinds of custom events:
Instant Event is a log at a specific timestamp, showing as an arrow. It’s useful
to log a transient event. You need to give it a
name which is a string and an
args. They will be displayed in the report
args has to be a jsonifiable object, normally a string, or a combination
of dict, list, string and number.
scope can be set to
t``(default), ``p or
g, for thread, process and
tracer.log_instant(f"Event1", args=args, scope="p")
Variable Event is a way to log a specific variable in your program and display it in the report.
If the variable you log is a number, VizTracer will use a counter event to display it, otherwise instant event will be used.
name should be given for the variable, then the variable itself
trace.log_var("name for the var", var)
You can use magic comment to log instant events and variable events.
In this way, you’ll have 0 overhead and side effect when you run your program normally, and log the events when you use viztracer to trace it
# !viztracer: log_instant("start logging") a = 3 # !viztracer: log_var("a", a)
Or you can use inline magic comment
# !viztracer: log, which will log the assigned value if the statement is an assign
or it will log an instant event indicating this line is executed
# This will log an instant event with name "f()" f() # !viztracer: log # This will log the variable a a = 3 # !viztracer: log
You can also do conditional log with
# This will log the variable a a = 3 # !viztracer: log if a == 3 # This has the same effect # !viztracer: log_var("a", a)
--magic_comment option for
viztracer to trigger the magic comment
viztracer --magic_comment your_program.py
Duration Event is almost the same as function call event that normally being logged automatically, with the only exception that it does not have to be a function.
You can log any piece of code using duration event and it would look like a function call event in your final report.
from viztracer import get_tracer with get_tracer().log_event("my event name"): # some code running here
You should use
log_event method of your tracer, which is accessible through
function when you are using CLI, or just pass the tracer if you are using inline.
This feature is especially helpful when you are using Log Sparse.