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
• API
• Configure
• Build
• Test
• Release
• See Also

Overview

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

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 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.

Services

• 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

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

Core scripts

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).

Entire application

The entire JAWS application consists of multiple microservices and each one has a separate installation. However, you can launch them all using the docker compose here. This 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 literally anything from bash scripts leveraging systemctl --host to Ansible/Chef/Puppet/Whatever, or perhaps Kubernetes + tooling.

API

Admin Scripts API

Sphinx Docs

Configure

The following environment variables are required by the scripts:

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

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: Python Development Notes and Docker Development Quick Reference

Test

The integration tests require a docker container environment and are run automatically as a GitHub Action on git push. You can also run tests from a local workstation using the following instructions:

1. Start Docker Test environment

docker compose -f test.yml up

2. Execute Tests

docker exec -i jaws bash -c "cd /tests; pytest -p no:cacheprovider"

Note: You can also run tests directly on the host (instead of inside the jaws container) if you set the environment variables as: BOOTSTRAP_SERVERS=localhost:9094 and SCHEMA_REGISTRY=http://localhost:8081

Release

1. Bump the version number in setup.cfg and commit and push to GitHub (using Semantic Versioning).
2. Create a new release on the GitHub Releases page corresponding to same version in setup.cfg (Enumerate changes and link issues)
3. Clean build by removing build, dist, and docsrc/source/_autosummary directories
4. Activate virtual env
5. From venv build package, build docs, lint, test, and publish new artifact to PyPi with:

python -m build
sphinx-build -b html docsrc/source build/docs
pylint src/jaws_scripts
python -m twine upload --repository pypi dist/*

6. Build and push Docker image
7. Update Sphinx docs by copying them from build dir into gh-pages branch and updating index.html (commit, push).

See Also

• Overrides and Effective State
• Software Design
• Developer Notes