ligo-lvalert Documentation

ligo-lvalert is a client for the LIGO/Virgo/KAGRA LVAlert pubsub infrastructure that is powered by Apache Kafka. It is a version of the generalized hop-client pubsub tool to respond to alerts from GraceDB.

The CLI and API are compatible with Python 3.

User Guide

Please visit the LVAlert User Guide for a brief overview and starter for the LVAlert client and service.

Quick Start

Install from the lscsoft yum repository:

yum install ligo-lvalert

Install from the lscsoft debian repository:

apt install ligo-lvalert

Install with pip:

pip install ligo-lvalert

Subscribe to some topics. See User Guide on topics and credentials

Listen for LVAlert messages:

lvalert listen

API

class ligo.lvalert.client.LVAlertClient(username=None, password=None, auth=None, authfile=None, noauth=False, group=None, server=None, port=None)[source]

A hop-scotch client configured for LVAlert

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)) – LVAlert group (e.g., lvalert, lvalert-playground)
server (str (optional)) – The LVAlert server hostname.
port (int (optional)) – The LVAlert server port

Example

Here is an example for listing topics:

client = LVAlertClient(group='lvalert-dev')
topics = 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 = LVAlertClient(group='lvalert-dev')
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 nodes.

Parameters: group (str (optional)) – Group prefix (e.g., “lvalert”, “lvalert-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 LVAlert 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 (node) after a session has been connected with LVAlertClient.connect()

Parameters

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

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

unsubscribe(*nodes)[source]: Unsubscribe from one or more pubsub nodes.

Command Line Interface

usage: lvalert [-h] [-g GROUP] [-l {critical,error,warning,info,debug}]
               [-n NETRC] [-s SERVER] [-u USERNAME]
               {listen,subscriptions,topics,unsubscribe,send} ...

Positional Arguments

action

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

sub-command help

Named Arguments

-g, --group

LVAlert group name (e.g., lvalert, lvalert-playground)

Default: “lvalert”

-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

LVAlert server hostname

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

-u, --username

User name (default: look up in netrc file)

Sub-commands:

listen

Listen for LVAlert messages and print them to stdout.

lvalert listen [-h] [topics [topics ...]]

Positional Arguments

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

subscriptions

List your subscriptions

lvalert subscriptions [-h]

topics

List available pubsub topics

lvalert topics [-h]

unsubscribe

Unsubscribe from one or more topics

lvalert unsubscribe [-h]

send

publish contents of a file to a pubsub topic

lvalert send [-h] topic [topic ...] eventfile [eventfile ...]

Positional Arguments

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