JLab Alarm Warning System (JAWS) Admin Scripts
Project description
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
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
Data
Plugins
- jaws-epics2kafka: Connects EPICS alarms to JAWS
- registrations2epics: Notifies epics2kafka of EPICS alarm registration updates
Quick Start with Compose
- Grab project
git clone https://github.com/JeffersonLab/jaws
cd jaws
- Launch Docker
docker compose up
- Monitor active alarms
docker exec -it jaws /scripts/client/list-activations.py --monitor
- 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: 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
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jaws_scripts-4.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ad9e699259b94a95d31f686ede0977d06355c56244dff9d0fddecc7070e0f487 |
|
MD5 | e5d02da7be81144a970e03430ea9500c |
|
BLAKE2b-256 | 57ef0bf459f7d11cb02b1d84a78b4878312030f01de0bb1b19938efe6cfc97bd |