ligo-lvalert Documentation

ligo-lvalert is a client for the LIGO/Virgo LVAlert pubsub infrastructure that is powered by SleekXMPP.

The CLI and API are compatible with Python 3. For backwards compatibility, legacy Python clients powered by PyXMPP are included in the package, but are slated to be removed from a future release of ligo-lvalert.

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

Note that the pip installation requires the installation of libxml2, and swig to support the legacy clients.

Put your username and password in your netrc file in ~/.netrc:

echo 'machine lvalert-test.cgca.uwm.edu login albert.einstein password gravity' >> ~/.netrc
chmod 0600 ~/.netrc

Subscribe to some nodes:

lvalert subscribe cbc_gstlal cbc_pycbc cbc_mbtaonline

Listen for LVAlert messages:

lvalert listen

API

class ligo.lvalert.LVAlertClient(username=None, password=None, resource=None, netrc=None, interactive=False, server='lvalert.cgca.uwm.edu')[source]

Bases: sleekxmpp.clientxmpp.ClientXMPP

An XMPP client configured for LVAlert.

Parameters
  • username (str (optional)) – The XMPP username, or None to look up from the netrc file.

  • password (str (optional)) – The XMPP password, or None to look up from the netrc file.

  • resource (str (optional)) – The XMPP resource ID, or None to generate a random one.

  • netrc (str (optional)) – The netrc file. The default is to consult the NETRC environment variable or use the default path of ~/.netrc.

  • interactive (bool (optional)) – If True, then fall back to asking for the password on the command line if necessary.

  • server (str (optional)) – The LVAlert server hostname.

Example

Here is an example for performing administrative actions.

client = LVAlertClient()
client.connect()
client.process(block=False)
client.subscribe('cbc_gstlal', 'cbc_pycbc')
client.abort()

Here is an example for running a listener.

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

client = LVAlertClient()
client.listen(process_alert)
client.connect()
client.process(block=True)
get_nodes()[source]

Get a list of all available pubsub nodes.

get_subscriptions()[source]

Get a list of your subscriptions.

listen(callback)[source]

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

Parameters

callback (callable) – A function of two arguments: the node and the alert payload.

publish(node, msg=None)[source]

Publish a message to one or more pubsub nodes.

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] [-l {critical,error,warning,info,debug}] [-n NETRC]
               [-r RESOURCE] [-s SERVER] [-u USERNAME]
               {listen,subscriptions,nodes,subscribe,unsubscribe,send} ...

Positional Arguments

action

Possible choices: listen, subscriptions, nodes, subscribe, unsubscribe, send

sub-command help

Named Arguments

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

-r, --resource

XMPP resource (default: random)

-s, --server

LVAlert server hostname

Default: “lvalert.cgca.uwm.edu”

-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]

subscriptions

List your subscriptions

lvalert subscriptions [-h]

nodes

List available pubsub nodes

lvalert nodes [-h]

subscribe

Subscribe to one or more nodes

lvalert subscribe [-h] node [node ...]
Positional Arguments
node

a pubsub node (e.g. cbc_gstlal)

unsubscribe

Unsubscribe from one or more nodes

lvalert unsubscribe [-h] node [node ...]
Positional Arguments
node

a pubsub node (e.g. cbc_gstlal)

send

publish contents of a file to a pubsub node

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

a pubsub node (e.g. cbc_gstlal)

eventfile

name of the file with the event to send