Gocart Plugins ∞
gocart has the ability to run ‘plugins’. These are Python scripts gocart can trigger every time a message is read from the GCN Kafka stream. To run gocart with plugins, pass the --plugins, -p
flag to any of the commands. For example:
gocart -p listen
or
gocart -p echo 0.3
In ~/.config/gocart/plugins
you will find a template plugin script called gp_template.py
which can be run as a stand-alone script like so:
python ~/.config/gocart/plugins/gp_template.py <pathToAlertDirectory>
For example, if you run:
python ~/.config/gocart/plugins/gp_template.py ~/lvk_events/mockevents/MS230423x/20230424T000204_initial/
the template script prints the following to the command line:
Here are the alert files generated from INITIAL alert of event MS230423x:
bayestar.multiorder.fits
skymap.csv
meta.yaml
skymap.png
MS230423x-initial.json
Create Your Own Plugin ∞
The quickest way to create your own plugin is to copy the template script and modify it:
cd ~/.config/gocart/plugins/
cp gp_template.py gp_sound_the_alarm.py
Open the new script in your favourite text editor and edit the code within the plugin
function:
def plugin(
log,
settings,
alertFiles,
alertMeta):
"""*this is the gocart plugin function that will be run when an alert is read*
**Key Arguments:**
- ``log`` -- logger
- ``settings`` -- these are the gocart settings, you can add extra settings to the gocart.yaml settings file and they will be read here.
- ``alertFiles`` -- a list of all the files generated by gocart for the alert
- ``alertMeta`` -- a dictionary of the alert metadata from the json alert, FITS Header and gocart generated extras.
"""
log.debug('starting the ``plugin`` function')
alertType = alertMeta["ALERT"]["alert_type"]
evertId = alertMeta["ALERT"]["superevent_id"]
print(f"Here are the alert files generated from {alertType} alert of event {evertId}:")
for f in alertFiles:
print(f)
log.debug('completed the ``plugin`` function')
return None
Before you start developing the script, make sure to generate a few alert directories to test on with (with parse_mock_events
setting set to True):
gocart echo 1
Now you can test your script with something similar to this (just make sure you are pointing to an alert directory that exists):
python ~/.config/gocart/plugins/gp_sound_the_alarm.py ~/lvk_events/mockevents/MS230423x/20230424T000204_initial/
Happy hacking!