"Don't get bit!"
An alarm system built on Kafka that supports pluggable alarm sources. This project integrates all the services that make up JAWS via Docker Compose. JAWS attempts to comply with ANSI/ISA 18.2-2016 where appropriate.
The JAWS alarm system is composed primarily of two subsystems: registrations and notifications.
The inventory of all possible alarms (the master alarm database) is stored in Kafka as alarm instances, and these instances are organized into classes so that some properties are provided by 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 notification state considering both activations and overrides is calculated by JAWS from activations and overrides and made available on the effective-notifications topic.
Both effective registrations and effective notifications are combined by the JAWS effective processor on the effective-alarms topic.
Apps
- jaws-effective-processor: Process classes and overrides and provide effective state on the effective-registrations, effective-notifications, 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 including Kafka topic and Registry schema setup
Data
Extensions
- jaws-epics2kafka: Connects EPICS alarms to JAWS
- jaws-registrations2epics: Notifies epics2kafka of EPICS alarm registration updates
- Grab project
git clone https://github.com/JeffersonLab/jaws
cd jaws
- Launch Compose
docker compose up
- Monitor active alarms
docker exec -it jaws list_activations --monitor
- Trip an alarm
docker exec jaws set_activation alarm1
Note: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.
See: More Usage Examples
The entire JAWS application consists of multiple microservices and each one has a separate installation. However, you can install and launch them all using the docker compose here. This Docker Compose file (and it's references) answers the question of which version of each microservice to use. In a production environment you'll likely want to use some orchestration tooling, which could be anything from bash scripts to Compose/Ansible/Chef/Puppet/Whatever, or perhaps Kubernetes + tooling. JLab is currently using Docker Compose on a beefy VM and the entire system is ephemeral, loading it's data from the alarms GitHub repo. The system can be upgraded and restarted in seconds. See internal docs.