DQRAlert 0.5.0

Manage igwn-alerts for DQR

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

Key	Default	Description
topics	(required)	Space-separated list of Kafka topics to subscribe to
group	gracedb	GraceDB server group (gracedb, gracedb-playground, gracedb-test)
type	any	Space-separated alert types to process (e.g. new signoff_created); any processes all
max_far	1	Maximum false-alarm rate [Hz]; alerts above this threshold are ignored
json_dir	(required)	Directory to write accepted event JSON payloads
run	(none)	Shell command to execute for each accepted alert
timeout	600	Maximum runtime [seconds] for the processing command
saveall_dir	(none)	Directory to archive all received alerts (including filtered ones)
save_list	any	Alert types to save in saveall_dir; any saves all
save_ignore	(none)	Alert types to exclude from saveall_dir (e.g. log)
refresh_alert_counters	(disabled)	Print alert rate statistics every N seconds

License

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