igwn-alert Users Guide

The International Gravitational Wave Network Alert System (igwn-alert) is a notification service built on the Apache Kafka protocol and the pubsub extension. It provides a basic notification tool which allows multiple producers and consumers of notifications.

The igwn-alert client code a version of the generalized Kakfa client code, hop-client. It has been modified to streamline ingestion of alerts from GraceDB, and to provide continuity with the previous-generation LVAlert service and client code, which made use use of the XMPP protocol.

The server backend infrastructure is built and maintained by SCiMMA, as is the authentication and identity access management.

First Steps

To begin to use the service, you must first create an account on the SCiMMA Auth account management portal (https://my.hop.scimma.org/).

Create an account using LIGO, Virgo, or KAGRA credentials by choosing one of the respective organizations as your identity provider. Note: at this time, access to igwn-alert is limited to LIGO, Virgo, and KAGRA members.

SCiMMA Identity Providers.

Next, you must join the lvk-users group to subscribe to topics from GraceDB. Please submit your request as a new issue on the igwn-alert Gitlab project page by following this link. Be sure to include your newly-created SCiMMA ID (SCiMMA1000XXXX), as well as your name and email address that you used to register with SCiMMA. By authenticating through Gitlab, you are confirming that you have valid LVK credentials, and are authorized to receive alerts from GraceDB via membership in the lvk-users group. Within a short period of time, you will receive a confirmation through Gitlab that your request was approved, and you will see the change reflected on the Auth account management screen.

To repeat, before creating credentials and subscribing to topics, please fill out the request form to be added to the lvk-users group.

Managing Credentials and Topics

Unlike the XMPP code, subscriptions to topics is handled by a credential, which is managed through the SCiMMA Auth web portal. Users can have multiple credentials associated with their account, each with their unique credential names and passwords.

To create a credential, use the following prompt in the web interface:

Prompt to create a credential.

Record the password and credential name, as there is no ability to change or recall passwords at this time.

Subscriptions to topics are managed through credential permissions. Adding a “Read” permission is analogous to subscribing to receiving alerts. The lvk-users group has read-only access to topics from GraceDB. Topic names are of the format: group.topic, where group refers to which instance of GraceDB to which the user’s process is listening (gracedb, gracedb-playground, gracedb-test). And the topic follows the existing group_pipeline_search schema.

Note, adding the permission to read a topic is a required step to receive alerts from the topic. A topic will not appear in the client.get_topics() method if the read permission has not been added. Attempting to listen or publish to a topic whose permission has not been added will return an error.

Adding Authentication

At the current time, authentication for the igwn-alert client code is added using the tools provided with hop-client. Please refer to the hop-client authentication guide for more information. The easiest way to start to is to run the following command:

hop auth add

And enter the username and password provided when you create a credential. By default, the authentication credentials are stored in a file, ~/.config/hop/auth.toml.

Other means of authentication include support for .netrc and inputting a credential’s name and password directly when instantiating a igwn_alert.client class.

igwn-alert How To

igwn-alert uses the Publish-Subscribe (PubSub) model to create and distribute alerts to users. An entity (most commonly, GraceDB) publishes an alert to a topic (think of it like a channel). Other entities subscribe to that topic (channel) and then listen for content published on the channel.

Alerts from GraceDB take the form of JSON-formatted strings, whose contents depend on the action from GraceDB (e.g.: new event upload, new label applied, etc.). A description of igwn-alert message contents from GraceDB is available for events and superevents.

Note that GraceDB sends alerts to topics according to the Group, Pipeline, and Search of the candidate event in question. The topic name is constructed by lower-casing each element and joining with underscores. Thus, an alert for an event from the CBC group, gstlal pipeline, and ‘LowMass’ search would be sent out over the topic cbc_gstlal_lowmass. The Search element at the end is optional (i.e., the same alert will also be sent to the cbc_gstlal topic).

The listener can be configured to take an action upon receipt of an alert.

Topics and Read/Write Permissions

The topics above are designated to publish alerts from GraceDB only. This is a conscious design choice to avoid scenarios where unauthorized users mimic alerts from GraceDB and misdirect follow-up processes and observers. As such, members of the lvk-users group on SCIMMA only have read access to these topics. Attempting to publish to these topics by a non-GraceDB credential will result in an error.

Responding to igwn-alert Messages

The command-line tools, described on the main page allow users to quickly and easily interact wih the igwn-alert service, such as subscribing to and listing topics, listening and displaying alerts via stdout, etc.

The API tools allow users to specify actions to be taken upon receipt of an igwn-alert message. The action can be dependent on the topic which issues the message, as well as the type and contents of the message.

Please see the following example in the igwn-alert gitlab repository as a place to start to write your own igwn-alert listener. The first block of code allows the user to hard-code the value of the server, username, and topics to use to interact with the service. The comments should be self-explanatory.

The relevant block to respond to alerts begins in the process_alert callback function. This function is called when an alert comes in, and returns a string value topic, which is the name of the topic from which the message was received, and a JSON packet that contains the alert contents. Note, the contents of an alert for different alert types can be found on the GraceDB documentation linked previously on this page. In this block, users can call any imported Python module to take a unique action upon receiving an alert.

Please contact computing-help@igwn.org with further questions.