Custom Event

_EventBase is the base class of VizCounter and VizObject. It should never be used directly.

class _EventBase(tracer, name=None, trigger_on_change=True        include_attributes=[]        exclude_attributes=[])
tracer: VizTracer

an object of VizTracer

tracer can be set to None so the logging operation will be NOP. Your program will run normally with the instrumented code even when you are not using viztracer.

name: string = None

name of the event which will show on trace viewer. If not specified, class name will be used

trigger_on_change: boolean = True

whether to trigger log every time a public attribute is changed

include_attributes: list of string = []

a list of attributes that will trigger the log and be included in the report. If not empty, _EventBase will behave like whitelist

exclude_attributes: list of string = []

a list of attributes that will not trigger the log and not be included in the report. If not empty, _EventBase will behave like blacklist


manually log the current attributes

_viztracer_set_config(key, value)
  • key (str) – "trigger_on_change", "include_attributes" or "exclude_attribtues"

  • value – the value you want to set on corresponding config


when (str) – "after", "before" or "both" to specify when the log() function is called

triggerlog is a decorator for class methods to do auto-log when the method is called.

class VizCounter(_EventBase)

VizCounter should be used to track a numeric variable through time. You can track CPU usage, memory usage, or any numeric variable you are interested in using VizCounter

from viztraer import VizTracer, VizCounter
tracer = VizTracer()
counter = VizCounter(tracer, "counter name")

Because VizCounter has trigger_on_change on by default, any writes to its public attributes(does not start with _) will be automatically logged

counter.a = 2
counter.b = 1.2

You can turn trigger_on_change off and manually decide when to log

counter = VizCounter(tracer, "counter name", trigger_on_change=False)
# OR
counter = VizCounter(tracer, "counter name")
counter.config("trigger_on_change", False)
counter.a = 1
counter.b = 1
# Until here, nothing happens
counter.log() # trigger the log
class VizObject(_EventBase)

VizObject is almost exactly the same as VizCounter, with the exception that VizObject can log jsonifiable objects(dict, list, string, int, float)


In practice, you can inherit from VizCounter or VizObject class and build your own class so it will be much easier to track the data in your class. Remember you need to do __init__ function of the base class! If your class has a lot of attributes and they are frequently being written to, it is wise to turn off trigger_on_change

class MyClass(VizObject):
    def __init__(self, tracer):
        super().__init__(tracer, "my name", trigger_on_change=False)

You can manually do log by

obj = MyClass(tracer)

or you can decorate your class method with triggerlog to trigger log on function call

class MyClass(VizObject):
    def log_on_this_function():