"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 each is assigned an alarm action. The alarm instances are maintained on the alarms topic. Alarm actions define group-shared properties such as corrective action and rationale and are persisted on the alarm-actions topic. The JAWS effective processor joins actions to alarms 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-web: Web app for managing alarm notifications and inventory
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 cli list_activations --monitor
- Trip an alarm
docker exec cli set_activation alarm1
Note: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.
See: More Usage Examples
The core JAWS application consists of a set of containerized microservices which can be launched with a container orchestration tool such as Docker Compose. The following microservices are internal to JAWS:
- Kafka
- Schema Registry
- Effective Processor
- CLI Admin Console
Optionally, the following extra containerized services are available:
- Web App
- JAWS EPICS Services
There are external services required to be available for the Web app and EPICS Services that can be optionally containerized as well, but at JLab we use separately managed shared instances. You can launch a fully containerized version of JAWS which includes containerized external dependencies in the web app project and epics2kafka project. These external services include:
- Keycloak
- Oracle RDMS
- EPICS IOCs
The core JAWS system supports import and export of data from files. The optional Web app adds support for loading and saving from an Oracle database.
Bump the version number in the jaws-version.env file and commit and push to GitHub (using Semantic Versioning). The release GitHub Action should run automatically to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
There is no code in this repo, only configuration. The primary versioned artifact of this project is a service-versions.env file that accompanies a set of Docker Compose files which answer the question of which version of each microservice to use together.
Note: You can fetch a specific tagged version by replacing main with a semver tag in the URLs above.
At JLab this app is found at ace.jlab.org/jaws and internally at acctest.acc.jlab.org/jaws. However, those servers are proxies for jaws.acc.jlab.org and jawstest.acc.jlab.org respectively. A deploy script is provided on each server to automate wget and deploy. Example:
/opt/jaws/deploy.sh v1.2.3
See: JLab internal docs