jaws-scripts 3.7.1

JLab Alarm Warning System (JAWS) Admin Scripts

JLab Alarm Warning System (JAWS)

"Don't get bit!"

An alarm system built on Kafka that supports pluggable alarm sources. This project defines Kafka topics and AVRO schemas, ties together the message pipeline services that make up the core alarm system in a docker-compose file, and provides Python scripts for configuring and interacting with the system. JAWS attempts to comply with ANSI/ISA 18.2-2016 where appropriate.

---

• Overview
• Quick Start with Compose
• Install
• Scripts
• Configure
• Build
• See Also

---

Overview

The JAWS alarm system is composed primarily of two subsystems: registrations and activations.

The inventory of all possible alarms (the master alarm database) are stored in Kafka as alarm instances, and these instances are organized into classes so that some properties are inherited from their assigned alarm class. The alarm instances are maintained on the alarm-instances topic. Alarm classes define group-shared properties such as corrective action and rationale and are persisted on the alarm-classes topic. The JAWS effective processor joins classes to instances to form effective alarm registrations on the effective-registrations topic.

Activations indicate an alarm is annunciating (active), and timely operator action is required. Alarms are triggered active by producing messages on the alarm-activations topic. An alarm can be overridden to either suppress or incite the active state by placing a message on the alarm-overrides topic. The effective activation state considering both actual activations and overrides is calculated by JAWS from activations and overrides and made available on the effective-activations topic.

Both effective registrations and effective activations are combined by the JAWS effective processor on the effective-alarms topic.

Services

• jaws-effective-processor: Process classes and overrides and provide effective state on the effective-registrations, effective-activations, and effective-alarms topics
• jaws-admin-gui: GUI for managing alarm registrations
• jaws-operator-gui: GUI for monitoring alarms and managing overrides

APIs

• jaws-libj: Java API library for JAWS
• jaws-libp: Python API library for JAWS

Data

• JLab Alarms

Plugins

• jaws-epics2kafka: Connects EPICS alarms to JAWS
• registrations2epics: Notifies epics2kafka of EPICS alarm registration updates

Quick Start with Compose

1. Grab project

git clone https://github.com/JeffersonLab/jaws
cd jaws

2. Launch Docker

docker compose up

3. Monitor active alarms

docker exec -it jaws /scripts/client/list-activations.py --monitor

4. Trip an alarm

docker exec jaws /scripts/client/set-activation.py alarm1

Note: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.

See: Docker Compose Strategy

See: More Usage Examples

Install

Requires Python 3.9+

pip install jaws-scripts

Note: It's generally recommended to use a Python virtual environment to avoid dependency conflicts (else a dedicated Docker container can be used).

Scripts

Scripts Reference

To see all options use the --help option.

Configure

The following environment variables are required by the scripts:

Name	Description
BOOTSTRAP_SERVER	Host and port pair pointing to a Kafka server to bootstrap the client connection to a Kafka Cluster; example: kafka:9092
SCHEMA_REGISTRY	URL to Confluent Schema Registry; example: http://registry:8081

The Docker container requires the script environment variables, plus can optionally handle the following environment variables as well:

Name	Description
ALARM_LOCATIONS	Path to an alarm locations file to import (example file), else an https URL to a file, else a comma separated list of location definitions with fields separated by the pipe symbol. Example Inline CSV: name|parent
ALARM_CATEGORIES	Path to an alarm categories file to import (example file), else an https URL to a file, else a comma separated list of catgory definitions with fields. Example Inline CSV: name
ALARM_CLASSES	Path to an alarm classes file to import (example file), else an https URL to a file, else a comma separated list of class definitions with fields separated by the pipe symbol. Example Inline CSV: name|category|priority|rationale|correctiveaction|pointofcontactusername|latching|filterable|ondelayseconds|offdelayseconds
ALARM_INSTANCES	Path to an alarm instances file to import (example file), else an https URL to a file, else a comma separated list of instance definitions with fields separated by the pipe symbol. Leave epicspv field empty for SimpleProducer. Example Inline CSV: name|class|epicspv|location|maskedby|screencommand

Build

This Python 3.9+ project is built with setuptools and may be run using either the Python virtual environment feature or a dedicated Docker container to isolate dependencies. The pip tool can be used to download dependencies. Docker was used extensively for development due to the dependency on the Kafka ecosystem.

git clone https://github.com/JeffersonLab/jaws
cd jaws
python -m build

Note for JLab On-Site Users: Jefferson Lab has an intercepting proxy

See: Docker Development Quick Reference

See Also

• Overrides and Effective State
• Software Design
• Developer Notes