VizPlugin
In this doc, we will show how to build your own plugin for VizTracer.
Every plugin should inherit VizPluginBase
from viztracer.vizplugin
- class VizPluginBase(self)
- support_version(self)
- Returns:
the string for the latest version of viztracer supported to have API compatibility
- Return type:
dict
You must have this method overloaded and return the version, otherwise viztracer will raise an exception
def support_version(self): return "0.11.0"
- message(self, m_type, payload)
- Parameters:
m_type (str) – type of message
payload (dict) – a very flexible payload with the message
- Returns:
the corresponding return value. Could be an action, or a respond.
- Return type:
dict
As of now,
message()
only supports two kinds ofm_type
-"event"
and"command"
."event"
has apayload
that has key"when"
, to indicate when the event happens."when"
could beinitialize
,pre-start
,post-stop
orpre-save
.When
"event"
type message is received, the plugin can return an action, with key"action"
set to the action it needs. For now the only one supported is"handle_data"
, with which you also needs to provide a data handler"handler"
return
{}
if you don’t want to do anything"command"
has a payload that has key"cmd_type"
, to indicate what VizTracer expects the plugin to do."cmd_type"
could only be"terminate"
for now."terminate"
command is guaranteed before viztracer exits when commandline interface is used. However, if you are using viztracer inline, you will have to explicitly runtracer.terminate()
unless you are usingwith VizTracer()
.When
"command"
type message is received, the plugin has to return a dict like{"success": True}
to inform VizTracer that the plugin received the command and did what it asked.
Possible Actions
This sections lists all the possible actions you can take after you received an event. You should
return {"action": "the action name" ...}
with specific payload for each action
"handle_data"
When you want to modify the data, which is a common way to change the result viztracer has, you need
to use "handle_data"
action.
You should return {"action": "handle_data", "handler": my_handler}
where my_handler
should be
a function with a prototype def my_handler(data)
. VizTracer will call this handler to modify the
original data before it saves the report
Make Your Plugin Accessible
You will also need a magic function defined to enable VizTracer to load your plugins from command line.
The function has to be named `get_vizplugin(arg)`
, which will return an instance of your plugin object
based on the arg given when it’s called. You also need to put this function in the module that you want
your use to use on command line.
For example, if I want my user to use my plugin as viztracer --plugins vizplugins -- my_script.py
, I
should put get_vizplugin()
function in vizplugins/__init__.py
. Or if I want them to use as
viztracer --plugins vizplugins.cpu_usage -- my_script.py
, I should put the function in
vizplugins/cpu_usage.py
Be aware that arg is an unparsed string like “vizplugins.cpu_time f 100”. You can split it yourself and parse it the way you like. Or you can specify something special for your own plugin