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


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

  • 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


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)

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 nodes.


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.

  • 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.

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

  • topic (str) – Topic name to publish to

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


Subscribe to one or more pubsub nodes.


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


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://”

-u, --username

User name (default: look up in netrc file)



Listen for LVAlert messages and print them to stdout.

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

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


List your subscriptions

lvalert subscriptions [-h]


List available pubsub topics

lvalert topics [-h]


Unsubscribe from one or more topics

lvalert unsubscribe [-h]


publish contents of a file to a pubsub topic

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

a pubsub topic (e.g. cbc_gstlal)


name of the file with the event to send