igwn-alert Documentation

igwn-alert is a client for the LIGO/Virgo/KAGRA alert infrastructure that is powered by Apache Kafka. igwn-alert uses a publish-subcsribe (pubsub) model to alert users and follow-up processes to state changes in GraceDB. It is a high-level extension of the generalized hop-client pubsub tool intended as a replacement of the legacy XMPP LVAlert service.

User Guide

Please visit the igwn-alert User Guide for a brief overview and starter for the igwn-alert client code and service.

Existing LVAlert Users are encouraged to read the LVAlert to igwn-alert Transition Guide to learn the latest on the rollout schedule and to see the differences between LVAlert and igwn-alert.

Quick Start

The latest version of igwn-alert is available in the igwn-py38 and igwn-py39 conda environments.

The latest version is also available on pip:

pip install igwn-alert

For custom conda environments where conda-forge is enabled:

conda install igwn-alert

Next, see the User Guide on topics and credentials for instructions on how to enable your account and credentials.

Finally, listen for messages:

igwn-alert -g gracedb-playground listen


Users with questions can email computing-help@igwn.org. LVK members can reach out for support on the igwn-alert Mattermost channel.


class igwn_alert.client.client(username=None, password=None, auth=None, authfile=None, noauth=False, group=None, consumer_group=None, server=None, port=None, batch_size=None, batch_timeout=None)[source]

A hop-scotch client configured for igwn_alerts from GraceDB

  • username (str (optional)) – The SCIMMA username, or None to look up with hop auth or netrc.

  • password (str (optional)) – The SCIMMA password, or None to look up with hop auth or netrc

  • auth (Auth (optional)) – A hop.auth.Auth object.

  • authfile (str (optional)) – Path to hop auth.toml

  • noauth (bool (optional)) – Set to True for unauthenticated session

  • group (str (optional)) – GraceDB group (e.g., gracedb, gracedb-playground)

  • consumer_group (str (optional)) – The consumer group ID to use for consuming messages. This can be used across sessions to avoid missed messages as well as allowing load-balancing of messages across multiple consumers assigned to the same consumer group. If not set, one will be randomly generated.

  • server (str (optional)) – The server host (i.e., kafka://…..)

  • port (int (optional)) – The server port

  • batch_size (int (optional)) – The number of messages to request per batch. Higher values may be more efficient, but may add latency

  • batch_timeout (timedelta (optional)) – How long the client waits to gather a full batch of messages. Higher values may be more efficient, but may add latency


Here is an example for listing topics:

alert_client = client(group='gracedb-test')
topics = alert_client.get_topics()

Here is an example for running a listener.

def process_alert(topic, payload):
    if topic == 'cbc_gstlal':
        alert = json.loads(payload)

client = IGWNAlertClient(group='gracedb-test')
topics = ['superevent', 'cbc_gstlal']
client.listen(process_alert, topics)

Takes in a topic or list of topics. Create writable stream objects for each of the topics in the list.

Must have publish rights on topic.


topic (str, or list of str) – Topic or list of topics to publish to


Delete a pubsub topic


Close all the current stream, or optionally close a single or list of topics


topic (str, or list of str (optional)) – Topic or list of topics to disconnect from. If None, then disconnect from all topics.


Get a list of your subscriptions.


Get a list of all available pubsub topics.


group (str (optional)) – Group prefix (e.g., “gracedb”, “gracedb-playground”) to show topics for. If None, list topics for the current group.

listen(callback=None, topic=None)[source]

Set a callback to be executed for each pubsub item received.

  • callback (callable (optional)) – A function of two arguments: the topic and the alert payload. When set to None, print out alert payload.

  • topic (str, or list of str (optional)) – Topic or list of topics to listen to. When set to None, then listen to all topics connected to user’s credential.

publish(topic, msg=None)[source]

Send an alert without pre-establishing a session.

  • topic (str, or list of str (optional)) – Topic or list of topics to publish to.

  • msg (str) – A message to publish to a topic

publish_to_topic(topic, msg)[source]

Publish to a specific topic after a session has been connected with client.connect()

  • topic (str) – Topic name to publish to

  • msg (str) – A message to publish to a topic


Subscribe to one or more pubsub topics.


Unsubscribe from one or more pubsub topics.

Command Line Interface

usage: igwn-alert [-h] [--no-auth] [-g GROUP] [-c CONSUMER_GROUP]
                  [-l {critical,error,warning,info,debug}] [-n NETRC]
                  [-s SERVER] [-u USERNAME] [-V]
                  {listen,subscriptions,topics,unsubscribe,send} ...

Positional Arguments


Possible choices: listen, subscriptions, topics, unsubscribe, send

sub-command help

Named Arguments


If set, disable authentication.

Default: False

-g, --group

GraceDB group name (e.g., gracedb, gracedb-playground)

Default: “gracedb”

-c, --consumer-group

Consumer group ID to use for consuming messages across sessions

-l, --log

Possible choices: critical, error, warning, info, debug

Log level

Default: “error”

-n, --netrc

netrc file (default: read from NETRC environment variable or ~/.netrc)

-s, --server

igwn-alert server hostname

Default: “kafka://kafka.scimma.org/”

-u, --username

User name (default: look up in auth.toml or .netrc)

-V, --version

show program’s version number and exit



Listen for igwn-alert messages and print them to stdout.

igwn-alert listen [-h] [topics ...]
Positional Arguments

a pubsub topic or list of topics (e.g. cbc_gstlal)


List your subscriptions

igwn-alert subscriptions [-h]


List available pubsub topics

igwn-alert topics [-h]


Unsubscribe from one or more topics

igwn-alert unsubscribe [-h]


publish contents of a file to a pubsub topic

igwn-alert send [-h] topic [topic ...] alertfile [alertfile ...]
Positional Arguments

a pubsub topic (e.g. cbc_gstlal)


name of the file with the alert to send