diff --git a/doc/source/lvalert.rst b/doc/source/lvalert.rst
index 42e0c7952cce41019549cd48e6579adbd0b80b7e..4e497f6917055b5418921f51bd9aa670f660ceca 100644
--- a/doc/source/lvalert.rst
+++ b/doc/source/lvalert.rst
@@ -6,7 +6,7 @@ Introduction
===============================================
GraceDB uses `LVAlert
-<https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`__ to send
+<https://wiki.ligo.org/DASWG/LVAlert>`__ to send
alerts to listeners within the LVC. The content of the LVAlert message is
designed to convey actionable information about a state change in GraceDB,
whether it involves the creation of a new event, or the updating or labeling of
@@ -41,7 +41,7 @@ specifying different LVAlert processing scripts for different nodes.
To see the names of all available nodes, simply execute::
- lvalert_admin -a username -b password -i
+ lvalert_admin -a username -i
LVAlert message contents
================================================
@@ -203,7 +203,7 @@ Receiving and Parsing LVAlert messages
The LVAlert client tools include the ``lvalert_listen`` executable, which can be used to
receive and respond to LVAlert messages::
- lvalert_listen -a username -b password -c /path/to/lvalert_config.ini
+ lvalert_listen -a username -c /path/to/lvalert_config.ini
The ``-c`` (configuration file) option allows you to specify an executable script to be called
each time a message arrives over a particular node. Suppose you are only interested in
@@ -238,5 +238,5 @@ Further reading on LVAlert
=====================================================
Further information on using LVAlert can be found on the
-`LVAlert Project Page <https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`__
-and the `LVAlert Howto <https://www.lsc-group.phys.uwm.edu/daswg/docs/howto/lvalert-howto.html>`__.
+`LVAlert Project Page <https://wiki.ligo.org/DASWG/LVAlert>`__
+and the `LVAlert Howto <https://wiki.ligo.org/DASWG/LVAlertHowto>`__.
diff --git a/doc/source/lvem.rst b/doc/source/lvem.rst
index b381e6c8dbf398b56aca58096b41e0d76fb525ce..c9025a10985233a7c63b3425b0afe1c133bad1ea 100644
--- a/doc/source/lvem.rst
+++ b/doc/source/lvem.rst
@@ -165,7 +165,7 @@ observation records:
consider sending us your script or posting it in the LV-EM wiki Technical Info
page for the benefit of other users. See :ref:`coding_against_api`.
-- by email (not yet availabe, but in the works)
+- by email (not yet available, but in the works)
If you discover a mistake in your observation record, the best way to correct
it is to submit a new observation record with corrected values and request that
@@ -174,7 +174,7 @@ something like "delete GraceDB EMObservation" in the subject line. Tell us
which entry you'd like deleted, and we'll take care of it. In the future, we
are hoping to make these observation records editable by the submitter.
-For more on the GraceBD event page and creating EM observation records, see
+For more on the GraceDB event page and creating EM observation records, see
`this <https://www.youtube.com/watch?v=oIJE4dTISs4>`__ helpful video
by Roy Williams. There is a companion video on the SkymapViewer
`here <https://www.youtube.com/watch?v=ydXUD9KIN98>`__.
diff --git a/doc/source/models.rst b/doc/source/models.rst
index 5b621cc0d383633c2eb87b7f46968ff367129b28..5014581cccc0fdd031f1d39f13c24942d692d1d7 100644
--- a/doc/source/models.rst
+++ b/doc/source/models.rst
@@ -12,7 +12,7 @@ The different types of events in GraceDB are distinguished by the following para
- ``Pipeline``: the data analysis software tool used make the detection
- values: ``MBTAOnline``, ``CWB``, ``gstlal``, ``gstlal-spiir``, ``HardwareInjection``, ``Fermi``, ``Swift``, ``SNEWS``, ``LIB``
- ``Search``: the search activity which led to the detection
- - values: ``AllSky``, ``LowMass``, ``HighMass``, ``GRB``, ``Supernova``, ``MDC``
+ - values: ``AllSky``, ``AllSkyLong``, ``LowMass``, ``HighMass``, ``GRB``, ``Supernova``, ``MDC``
An individual "event stream" is specified by setting the values of these three
parameters. For example, choosing ``Group=CBC, Pipeline=gstlal, and Search=LowMass``
diff --git a/doc/source/responding_to_lvalert.rst b/doc/source/responding_to_lvalert.rst
index f78bcbf17130cc2d4b693bf3a46c1b998c130214..f64abda973d75a353a5ba61b0376ef4d42c7c7d0 100644
--- a/doc/source/responding_to_lvalert.rst
+++ b/doc/source/responding_to_lvalert.rst
@@ -53,36 +53,44 @@ those events in GraceDB.
Fill out the form and follow all instructions to create an account attached to
your "user.name". For the rest of this tutorial, I will refer to the username
-as "user.name" and the password as "passw0rd", but you should replace these
-with your own account's information.
+as "user.name", but you should replace this with your own account's information.
+You'll be prompted for your password after each command.
+
+*Note: To bypass this, create a .netrc file in your home directory and enter your
+authentication information*::
+
+ machine lvalert.cgca.uwm.edu login user.name password passw0rd
+
+*With this setup, you won't need to include the* ``-a`` *flag for your username,
+or enter your password.*
To actually subscribe to a pubsub node, we use ``lvalert_admin``
which allows you to manage your subscriptions. This includes subscribing to new
nodes, unsubscribing from nodes and viewing your current subscriptions. We will
now subscribe your account to ``cbc_gstlal_lowmass``. Run::
- lvalert_admin -a user.name -b passw0rd --subscribe --node cbc_gstlal_lowmass
+ lvalert_admin -a user.name --subscribe --node cbc_gstlal_lowmass
You can confirm that your account is successfully subscribed to this node by
running::
- lvalert_admin -a user.name -b passw0rd --subscriptions
+ lvalert_admin -a user.name --subscriptions
which will list your account's subscriptions. You should see
``cbc_gstlal_lowmass`` in the resulting list. To unsubscribe from a node, use::
- lvalert_admin -a user.name -b passw0rd --unsubscribe --node cbc_gstlal_lowmass
+ lvalert_admin -a user.name --unsubscribe --node cbc_gstlal_lowmass
but for now we'll leave our subscription in place. If you'd like to subscribe
to other nodes, simply repeat the subscription command and replace
``cbc_gstlal_lowmass`` with the name of the node to which you'd like to
subscribe. A complete list of nodes is available by running::
- lvalert_admin -a user.name -b passw0rd --get-nodes
+ lvalert_admin -a user.name --get-nodes
For this tutorial, let's subscribe to another node to show how things scale. Run::
- lvalert_admin -a user.name -b passw0rd --subscribe --node cbc_gstlal_highmass
+ lvalert_admin -a user.name --subscribe --node cbc_gstlal_highmass
Creating an LVAlert node
========================
@@ -90,23 +98,23 @@ Creating an LVAlert node
Users can create their own LVAlert pubsub nodes as well. Unsurprisingly, this
is also straightforward. Simply run::
- lvalert_admin -a user.name -b passw0rd --create --node user.name-TestNode
+ lvalert_admin -a user.name --create --node user.name-TestNode
to create a node called ``user.name-TestNode``. Of course, you'll want to change
"user.name" to your account's name. Go ahead and create this node. If you need
to delete it at any time, you can with::
- lvalert_admin -a user.name -b passw0rd --delete --node user.name-TestNode
+ lvalert_admin -a user.name --delete --node user.name-TestNode
but leave it be for the moment. You now have a node owned by your account to
which you can publish alerts. We'll come back to this when we test our set-up.
You will also need to subscribe to this node with::
- lvalert_admin -a user.name -b passw0rd --subscribe --node user.name-TestNode
+ lvalert_admin -a user.name --subscribe --node user.name-TestNode
Run::
- lvalert_admin -a user.name -b passw0rd --subscriptions
+ lvalert_admin -a user.name --subscriptions
and make sure you see::
@@ -136,14 +144,14 @@ create a file called ``myLVAlertListen.ini`` with the following as its contents:
Now run::
- lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini > myLVAlertListen.out &
+ lvalert_listen -a user.name -c myLVAlertListen.ini > myLVAlertListen.out &
Congratulations! You've set up an ``lvalert_listen`` instance which reacts to
announcements published to the ``cbc_gstlal_lowmass``, ``cbc_gstlal_highmass`` and
``user.name-TestNode`` nodes.
Here's what's happening: ``lvalert_listen`` hears announcements made to any node to
-which the user.name/passw0rd combination is subscribed. When an alert is
+which your account is subscribed. When an alert is
received, it looks in the config file (loaded into memory) for the associated
section. Importantly, if there is no section in the config file corresponding
to the pubsub node's name (an exact match is required), ``lvalert_listen`` ignores
@@ -211,26 +219,27 @@ paths.
Now, because you have modified the ``lvalert_listen.ini`` file, you'll need to
restart your ``lvalert_listen`` instance. Find the PID in the process table, kill
the existing process, and restart the listener using the command from above.
-Alternatively, if you simply launch another instance of ``lvalert_listen`` with the
-same command line as before, the existing process will die and this one will
-take its place (with the new config file loading in memory). This is because
-only one listener can exist for any (user.name, passw0rd,
-resource.name) triple *anywhere in the network*. When you launch the second
-process, one of the processes is killed automatically (although which process
+
+You can also specify a resource name in your call to ``lvalert_listen``
+using the ``-r`` flag::
+
+ lvalert_listen -a user.name -c myLVAlertListen.ini -r listener1 &
+
+If you don't specify this parameter, a random UUID is generated for the resource name.
+The important point to consider is that only one listener can exist for any
+(user.name, passw0rd, resource.name) triple *anywhere in the network*.
+If you launch a second process with matching values of this triple,
+one of the processes is killed automatically (although which process
dies may not be deterministic). Thus, I can kill processes running at CIT by
creating processes at UWM with the same resource name. This can be extremely
-dangerous and annoying, so please be careful. It's generally best to specify a
-resource name for each listener, even if you expect to only have one, to ensure
-that you've thought through this. If you want to have multiple processes
-running under the same (user.name, passw0rd) pair, you will need to specify
-different resource.name options for each instance with the ``-r`` command line
-option. For example::
-
- lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini -r oneInstance &
- lvalert_listen -a user.name -b passw0rd -c myLVAlertListen.ini -r twoInstance &
-
-will launch two instances of ``lvalert_listen`` (both using the same config file)
-with different resource names. They will both react to alerts and fork
+dangerous and annoying, so please be careful. If you want to directly specify
+resource names for all of your listener processes, you can do something like::
+
+ lvalert_listen -a user.name -c myLVAlertListen.ini -r oneInstance &
+ lvalert_listen -a user.name -c myLVAlertListen.ini -r twoInstance &
+
+This will launch two instances of ``lvalert_listen`` (both using the same
+config file) with different resource names. They will both react to alerts and fork
processes. If each points to a different config file, I can then get multiple
types of follow-up processes forked for the same announcement through a single
pubsub node.
@@ -249,7 +258,7 @@ pubsub node. Create a file called ``test.txt`` and fill it with some text like::
Then run::
- lvalert_send -a user.name -b passw0rd -n user.name-TestNode --file test.txt
+ lvalert_send -a user.name -n user.name-TestNode --file test.txt
This publishes the contents of test.txt as a string to the node
``user.name-TestNode``. If your listener is running in the
@@ -307,7 +316,7 @@ Create a Python executable ``iReact.py`` and fill it with the following::
import sys
alert = json.loads(sys.stdin.read())
- print 'uid : '+alert['uid']
+ print 'uid : ' + alert['uid']
Don't forget to give this executable permissions with::
@@ -326,11 +335,11 @@ don't have to restart the ``lvalert_listen`` instance because that still points
Let's go ahead and send a test message in JSON format. Edit ``test.txt`` so it
reads::
- {'uid':'G12345'}
+ {"uid": "G12345"}
and run::
- lvalert_send -a user.name -b passw0rd --node user.name-TestNode --file test.txt
+ lvalert_send -a user.name --node user.name-TestNode --file test.txt
You should see a new line in ``lvalert_user.name-TestNode.out`` which reads::
@@ -355,7 +364,7 @@ Open ``iReact.py`` and modify it so it reads::
from ligo.gracedb.rest import GraceDb
alert = json.loads(sys.stdin.read())
- print 'uid : '+alert['uid']
+ print 'uid : ' + alert['uid']
gdb = GraceDb() ### instantiate a GraceDB object which connects to the default server
@@ -367,7 +376,7 @@ Open ``iReact.py`` and modify it so it reads::
Now, if we modify ``test.txt`` to::
- {'uid':'G12345','alert_type':'new','far':1e-8}
+ {"uid": "G12345", "alert_type": "new", "far": 1e-8}
and send it, ``iReact.py`` will try to write a log entry in GraceDB for event
G12345. It's easy to see that you can filter alerts out (e.g.: only react to
diff --git a/doc/source/rest.rst b/doc/source/rest.rst
index aeb803078a815938da6d29532da58990ceab59e3..dfa1f8b366b5c4d8f5022af98ed990f49932a347 100644
--- a/doc/source/rest.rst
+++ b/doc/source/rest.rst
@@ -40,6 +40,7 @@ It is also available through SSH::
git clone git@git.ligo.org:lscsoft/gracedb-client.git
In order to submit patches, you should fork the repository, implement your changes, and submit a merge request.
+Patches should also be documented on the GraceDB Redmine `page <https://bugs.ligo.org/redmine/projects/gracedb>`__.
.. _rest_client_basic_usage: