Introduction

• LIGO-Virgo Alert System (LVAlert) igwn-alert(old repo) igwn-alert(git)

  • The International Gravitational Wave Network Alert System (igwn-alert) is a notification service built on the Apache Kafka protocol and the pubsub extension.
  • It is a higher-level modification of SCIMMA's hop-client to streamline receiving and responding to alerts from GraceDB.
  • This package replaces the legacy LIGO LVAlert XMPP-based alert system.
  • The API are compatible with Python 3
• Retirement of existing LVAlert service targeted for ~April 2022.
  • In O4, we will use igwn-alert.

Install

• The latest version is 0.7.0 (2025/07/22)

  conda install igwn-alert==0.7.0

• help

  % igwn-alert -h
  usage: igwn-alert [-h] [--no-auth] [-g GROUP] [-c CONSUMER_GROUP] [-j] [-l {critical,error,warning,info,debug}] [-n NETRC] [-p PORT] [-r] [-s SERVER]
                    [-t LISTEN_RETRIES] [-u USERNAME] [-w RETRY_WAIT] [-V]
                    {listen,subscriptions,topics,unsubscribe,send} ...
  
  positional arguments:
    {listen,subscriptions,topics,unsubscribe,send}
                          sub-command help
      listen              Listen for igwn-alert messages and print them to stdout.
      subscriptions       List your subscriptions
      topics              List available pubsub topics
      unsubscribe         Unsubscribe from one or more topics
      send                publish contents of a file to a pubsub topic
  
  options:
    -h, --help            show this help message and exit
    --no-auth             If set, disable authentication.
    -g GROUP, --group GROUP
                          GraceDB group name (e.g., gracedb, gracedb-playground)
    -c CONSUMER_GROUP, --consumer-group CONSUMER_GROUP
                          Consumer group ID to use for consuming messages across sessions
    -j, --jsonpp          Output pretty print json
    -l {critical,error,warning,info,debug}, --log {critical,error,warning,info,debug}
                          Log level
    -n NETRC, --netrc NETRC
                          netrc file (default: read from NETRC environment variable or ~/.netrc)
    -p PORT, --port PORT  igwn-alert server port
    -r, --retry-on-fatal  reconnect listener on fatal exceptions
    -s SERVER, --server SERVER
                          igwn-alert server hostname
    -t LISTEN_RETRIES, --listen_retries LISTEN_RETRIES
                          fatal reconnect retry attempts
    -u USERNAME, --username USERNAME
                          User name (default: look up in auth.toml or .netrc)
    -w RETRY_WAIT, --retry_wait RETRY_WAIT
                          fatal reconnect retry attempts
    -V, --version         show program's version number and exit

Setting in advance on web

• The authentification between the client and the server is managed by SciMMA.

• The first step is to make a SCiMMa account by visiting https://my.hop.scimma.org/.

  • At this time, access to igwn-alert is limited to LIGO, Virgo, or KAGRA members.

• After log-in https://my.hop.scimma.org/, by clicking Hopskotch and Create new credentials, the password for your account will be shown just once.

Adding Authentication in local

• Run the hop command and enter the username and the password.

  • Empty Hostname is fine.

  hop auth add

• Once you entered, the authentification credential is stored in ~/.config/hop/auth.toml .

• Note that in the authentification credential is connected to conda environment. You can see the environment name in ~/.config/hop/auth.toml.

  • If you make new conda environment, you should run

    hop auth add --force

Usage in local

• Initially, no topic (you can consider channel) is registered to your account.

  • From https://my.hop.scimma.org/, please add channel (they call Add permission).

• This doesn't show anything.

  % igwn-alert topics
  Topics for group gracedb associated with the current credential:

Receive alert from MDC (Mock Data Challenge) analysis

• Follow instruction by Joe.

• If you set up properly, check the topics which you are subscribing.

  % igwn-alert --group gracedb-playground topics
  Topics for group gracedb-playground associated with the current credential:
  mdc_superevent
  cbc_pycbc

• Launch the igwn-alert

  % igwn-alert --g gracedb-playground listen

• To see the MDC alert on gracedb (2022/02/09), visit gracedb-playground (Require log-in).

Links

• git repo, igwn-alert

• igwn-alert, documentation outlining API

• igwn-alert, user guide for how to get started

• LVAlert instruction for python2 (out of date)

• Tutorial GraceDB

• LIGO/Virgo Public Alerts User Guide (not igwn-alert)