igwn-alert notifications (LVK users only)

Introduction

igwn-alert is a Kafka-based messaging platform used within the LVK. This document will describe how GraceDB uses igwn-alert, which topics it manages and publishes to, and the content of igwn-alert messages sent by GraceDB. GraceDB uses igwn-alert to send alerts to listeners within the LVK when.

Some helpful resources for installing and configuring igwn-alert are:

Main igwn-alert client
igwn-alert user guide
Tutorial on setting up igwn-alert and configuring your listener.

igwn-alert and GraceDB

Generally speaking, GraceDB uses igwn-alert to send “push” notifications about different actions that may be taken on the service. Users can subscribe to different topics (more below) to receive these notifications, filter their content, and optionally trigger follow-up processes, like data quality checks, parameter estimation, and more. The content of an igwn-alert message is designed to convey actionable information about a state change in GraceDB, including event creation, annotation, and other actions.

Note

An igwn-alert message is sent out for any new event or annotation that arrives in the GraceDB database. This means that message volumes may be very high under certain circumstances, and listeners should be constructed to appropriately filter the messages.

igwn-alert topics managed by GraceDB

By running the igwn-alert command-line tool, you will receive messages over all topics to which you have a listen permission, analogous to a subscription. There are two types of topics to which GraceDB broadcasts alerts: event topics and superevent topics.

Instance Groups

The following topic names are universal across each instance of GraceDB (production, playground, test). However, each instance’s topics names are prepended by the instance name (gracedb, gracedb-playground, gracedb-test) and a “.”. For example, the cbc_gstlal topic for GraceDB Playground is listed in the subscription interface as:

gracedb-playground.cbc_gstlal

And can be evoked in the command line tool by specifying the instance with the optional group flag as in the following command:

igwn-alert -g gracedb-playground listen cbc_gstlal

Event topics

Event topic names consist of at least two elements:

<group_name>_<pipeline_name>

In other words, the (lower-cased) names of the Group and Pipeline separated by an underscore. For example, the topic cbc_gstlal would catch all messages relating to events in the CBC group from the gstlal pipeline. One can also specify the search name:

<group_name>_<pipeline_name>_<search_name>

which has the effect of narrowing down the messages to only those related to a specific search. For example, the topic cbc_gstlal_allsky will contain messages relating to the AllSky search, but not the MDC search.

It is important to note that GraceDB will send an igwn-alert to all topics which match the parameters of the event in question. For example, the creation of a Burst-cWB-AllSky event will result in messages being sent to the burst_cwb_allsky topic, as well as the more generic burst_cwb topic. This feature allows the user to filter according to search by specifying different igwn-alert processing scripts for different topics.

Superevent topics

There are only three superevent topics; one for each category of superevent:

superevent
test_superevent
mdc_superevent

Most users will be interested in the superevent topic in order to receive igwn-alerts about real GW candidates.

Contents of igwn-alerts sent by GraceDB

GraceDB sends igwn-alert messages as a JSON-encoded dictionary. This dictionary contains the following keys:

alert_type: short string representing the action which triggered the alert. Examples: new, update, label_added, etc. All alert types are shown in the tables below.
data: a dictionary representing the relevant object (label, log message, etc.)
object: a dictionary representing the corresponding “parent” object (i.e., the event or superevent which a log, label, etc. is attached to).
uid: the unique ID of the relevant event or superevent

Below, we describe the alert contents in more detail. Examples of the various data/object dictionaries are available in Data Models. See below for one additional example (list of permissions).

Event alerts

For alerts related to events, the following things are always true:

uid is always the event’s graceid (example: G123456).
object is always a dictionary corresponding to the event which is affected by the label, log, VOEvent, etc.

The following table shows the alert_type and data for different actions:

`alert_type`	`data`	Occurs when
added_to_superevent	event dictionary	event is added to a superevent
embb_event_log	EMBB event log dictionary	EM bulletin board event log is created for event
emobservation	emobservation dictionary	EM observation is created for event
exposed	list of permission dictionaries	internal-only event is exposed to LV-EM
hidden	list of permission dictionaries	LV-EM viewable event is marked as internal-only
label_added	label dictionary	label is added to event
label_removed	label dictionary	label is removed from event
log	log dictionary	log message is added to event (may include file upload)
new	event dictionary	event is created
removed_as_preferred	event dictionary	event is no longer the preferred event for a superevent
removed_from_superevent	event dictionary	event is removed from a superevent
selected_as_preferred	event dictionary	event is selected as preferred event for a superevent
signoff_created	signoff dictionary	signoff is created for event
signoff_deleted	signoff dictionary	event signoff is deleted
signoff_updated	signoff dictionary	event signoff is updated
update	event dictionary	event is “replaced” by upload of a new event file
voevent	VOEvent dictionary	VOEvent is created for event

Superevent alerts

For alerts related to superevents, the following things are always true:

uid is always the superevent’s superevent_id (example: S800106D).
object is always a dictionary corresponding to the superevent which is affected by the label, log, VOEvent, etc.

The following table shows the alert_type and data for different actions:

`alert_type`	`data`	Occurs when
confirmed_as_gw	superevent dictionary	superevent is upgraded to GW status
embb_event_log	EMBB event log dictionary	EM bulletin board event log is created for event
emobservation	emobservation dictionary	EM observation is created for superevent
event_added	superevent dictionary	an event is added to superevent
event_removed	superevent dictionary	an event is removed from superevent
exposed	list of permission dictionaries	internal-only superevent is exposed to LV-EM and public
hidden	list of permission dictionaries	public superevent is marked as internal-only
label_added	label dictionary	label is added to superevent
label_removed	label dictionary	label is removed from superevent
log	log dictionary	log message is added to superevent (may include file upload)
new	superevent dictionary	superevent is created
signoff_created	signoff dictionary	signoff is created for superevent
signoff_deleted	signoff dictionary	superevent signoff is deleted
signoff_updated	signoff dictionary	superevent signoff is updated
update	superevent dictionary	superevent is updated (`t_start`, `t_0`, `t_end`, or `preferred_event` are changed)
voevent	VOEvent dictionary	VOEvent is created for superevent

Example: list of permission dictionaries

[
    {
        "group": "gw-astronomy:LV-EM:Observers",
        "permission": "view_superevent"
    },
    {
        "group": "gw-astronomy:LV-EM:Observers",
        "permission": "annotate_superevent"
    },
    {
        "group": "public_users",
        "permission": "view_superevent"
    }
]