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