LVAlert Users Guide
The LIGO-Virgo Alert System (LVAlert) 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 LVAlert 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 LVAlert is limited to LIGO, Virgo, or KAGRA members.
Next, please email your SCiMMA ID (SCiMMA1000XXXX) and username (your email used to register the account) to email@example.com and request to join the “LVK Users” group in order to receive LVAlerts. Within short time, you will be added to the appropriate group, and after receiving an email confirmation, will see the change reflected on the Auth account management screen.
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 not the ability to change or recall passwords at a later date.
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 the GraceDB/LVAlert system
the user’s process is listening to (
lvalert-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
LVAlertClient.get_topics() method. Attempting to
listen or publish to a topic whose permission has not been added will return
At the curent time, authentication for the LVAlert 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 folling 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
LVAlert How To
LVAlert 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 node (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 LVAlert message contents from GraceDB is available for events and superevents.
Note that GraceDB sends alerts to nodes according to the Group, Pipeline,
and Search of the candidate event in question. The node 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 node
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.
Responding to LVAlert Messages
The command-line tools, described on the main page allow users to quickly
and easily interact wih the LVAlert service, such as subscribing to and listing nodes,
listening and displaying alerts via
The API tools allow users to specify actions to be taken upon receipt of an LVAlert message. The action can be dependent on the node which issues the message, as well as the type and contents of the message.
Please see the following example in the LVAlert gitlab repository as a place to start to write your own LVALert listener. The first block of code allows the user to hard-code the value of the server, username, and nodes to use to interact with the service. The comments should be self-explanatory.
The relevant block to respond to LVAlerts begins in the process_alert
callback function. This function is called when an alert comes in, and returns a
node, which is the name of the node 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 contain Alexander Pace with further questions.