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!