Metadata-Version: 2.4
Name: DQRAlert
Version: 0.5.0
Summary: Manage igwn-alerts for DQR
Author-email: Joseph Areeda <joseph.areeda@ligo.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://git.ligo.org/dqr-builder/dqralert
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: adc-streaming
Requires-Dist: confluent-kafka
Requires-Dist: python-dateutil
Requires-Dist: gwpy
Requires-Dist: igwn-alert
Requires-Dist: psutil
Requires-Dist: pytz
Provides-Extra: test
Requires-Dist: pytest>=2.8.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: license-file

# DQRAlert

[![PyPI version](https://img.shields.io/pypi/v/DQRAlert.svg)](https://pypi.org/project/DQRAlert/)
[![License: GPL v3](https://img.shields.io/badge/License-GPL_v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docs](https://img.shields.io/badge/docs-dqr--builder.docs.ligo.org-blue.svg)](https://dqr-builder.docs.ligo.org/dqralert/)

DQRAlert listens for [igwn-alert](https://igwn-alert.readthedocs.io/) 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

```bash
pip install dqralert
```

## Quick Start

### 1. Set up SCIMMA / hop credentials

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

Verify the connection:

```bash
igwn-alert topics
```

### 2. Create a configuration file

```ini
[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

```bash
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:

```bash
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](LICENSE).
