== Introduction ==
 * LIGO-Virgo Alert System (LVAlert) [[https://git.ligo.org/lscsoft/igwn-alert|igwn-alert]] 
  * 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.1.2 (2021/12/07)
  * Available in pip and conda shortly. 
 {{{
conda install igwn-alert
 }}}

 {{{
pip install igwn-alert
 }}}

 * help
 {{{
% igwn-alert -h
usage: igwn-alert [-h] [-g GROUP] [-l {critical,error,warning,info,debug}] [-n NETRC] [-s SERVER] [-u USERNAME] {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

optional arguments:
  -h, --help            show this help message and exit
  -g GROUP, --group GROUP
                        GraceDB group name (e.g., gracedb, gracedb-playground)
  -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)
  -s SERVER, --server SERVER
                        igwn-alert server hostname
  -u USERNAME, --username USERNAME
                        User name (default: look up in auth.toml or .netrc)
}}}


== 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/|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/|https://my.hop.scimma.org/]], by clicking {{{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/|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 [[https://o4-dqr.docs.ligo.org/o4-dqr-configuration/#setting-up-igwn-alert-to-test-taskmanager|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 [[https://gracedb-playground.ligo.org/latest/?query=mdc&query_type=S|gracedb-playground]] (Require log-in).

== Links ==

 * [[https://git.ligo.org/lscsoft/igwn-alert|git repo, igwn-alert]]  
 * [[https://lscsoft.docs.ligo.org/igwn-alert/|igwn-alert, documentation outlining API]]
 * [[https://lscsoft.docs.ligo.org/igwn-alert/guide.html|igwn-alert, user guide for how to get started]]

 * [[KAGRA/Subgroups/DET/LVAlert_python2 |LVAlert instruction for python2 (out of date)]]

 * [[https://gracedb.ligo.org/documentation/responding_to_lvalert.html|Tutorial GraceDB]]

 * [[https://git.ligo.org/emfollow/userguide|LIGO/Virgo Public Alerts User Guide (not igwn-alert)]]