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.
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.
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
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
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:
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 refers to which
instance of GraceDB to which
the user’s process is listening (
gracedb-test). And the
topic follows the existing
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
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,
Other means of authentication include support for
.netrc and inputting
a credential’s name and password directly when instantiating a
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
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
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
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 email@example.com with further questions.