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

Help

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

API

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

Parameters

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

Example

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)

connect(topics)[source]

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.

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

delete()[source]: Delete a pubsub topic

disconnect(topics=None)[source]

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

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

get_subscriptions()[source]: Get a list of your subscriptions.

get_topics(group=None)[source]

Get a list of all available pubsub topics.

Parameters: 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.

Parameters

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.

Parameters

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()

Parameters

topic (str) – Topic name to publish to
msg (str) – A message to publish to a topic

subscribe(*topics)[source]: Subscribe to one or more pubsub topics.

unsubscribe(*topics)[source]: 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

action

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

sub-command help

Named Arguments

--no-auth

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

Sub-commands:

listen

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

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

Positional Arguments

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

subscriptions

List your subscriptions

igwn-alert subscriptions [-h]

topics

List available pubsub topics

igwn-alert topics [-h]

unsubscribe

Unsubscribe from one or more topics

igwn-alert unsubscribe [-h]

send

publish contents of a file to a pubsub topic

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

Positional Arguments

topic: a pubsub topic (e.g. cbc_gstlal)
alertfile: name of the file with the alert to send