DQRAlert

DQRAlert listens for igwn-alert messages from GraceDB and launches an external processing command (such as the DQR task manager) when an appropriate gravitational-wave candidate alert is received.

Overview

When GraceDB issues a superevent alert, DQRAlert:

1. Receives the alert payload via the IGWN Kafka/hop-client infrastructure
2. Filters it by alert type and false-alarm rate (FAR)
3. Writes the event JSON to a configured output directory
4. Optionally saves all received alerts (including filtered ones) to a separate archive directory
5. Launches a user-supplied shell command to process the accepted event

Installation

pip install dqralert

Quick Start

1. Set up SCIMMA / hop credentials

hop auth add
# follow the prompts to enter your SCIMMA username and password

Verify the connection:

igwn-alert topics

2. Create a configuration file

[alerts]
# Kafka topic(s) to subscribe to (space-separated)
topics = mdc_superevent

# GraceDB server group: gracedb (production), gracedb-playground, gracedb-test
group = gracedb-playground

# Alert types to process (space-separated); omit or set to 'any' for all
type = new

# False-alarm rate threshold [Hz] — alerts with FAR above this are ignored
max_far = 1.57e-5

# Directory to write the accepted event JSON payload
json_dir = /path/to/json

# Command to run for each accepted alert
# Variables: ${json} = path to the JSON file, ${graceid} = GraceDB S-event ID
run = /path/to/my-processing-script.sh ${json} ${graceid}

# Maximum runtime [seconds] for the processing command
timeout = 1800

# Optional: save ALL received alerts (including filtered ones) here
# saveall_dir = /path/to/archive

3. Run the listener

dqralert -v -c /path/to/dqr-alert.ini -l /path/to/dqralert.log

Command-Line Reference

usage: dqralert [-h] [-v] [-V] [-q] [-u USER] [-c CONFIG] [-l LOG_FILE] [-f] [--memstat MEMSTAT]

Accept an igwn-alert, call dqr-create-dag

options:
  -h, --help            show this help message and exit
  -v, --verbose         increase verbose output (repeat for more detail)
  -V, --version         show program's version number and exit
  -q, --quiet           show only fatal errors
  -u USER, --user USER  igwn-alert username
  -c CONFIG, --config CONFIG
                        path to configuration file
  -l LOG_FILE, --log-file LOG_FILE
                        save log messages to this file
  -f, --full-payload    store the full alert payload (default: store only the
                        'object' field, compatible with a GraceDB query)
  --memstat MEMSTAT     record memory statistics to this file

dqralert-latency

A utility to compute processing latencies from saved event JSON files:

dqralert-latency event1.json event2.json ...

Prints a CSV table with the GraceDB ID, event time, superevent creation time, and the time the JSON file was written.

Configuration Reference

License

DQRAlert is distributed under the GNU General Public License v3 or later.