Package: jaws-scripts
JLab Alarm Warning System (JAWS)"Don't get bit!"An alarm system built onKafkathat supports pluggable alarm sources.  This project defines Kafka topics andAVROschemas, 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 withANSI/ISA 18.2-2016where appropriate.OverviewQuick Start with ComposeInstallAPIConfigureBuildTestReleaseSee AlsoOverviewThe 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 thealarm-instancestopic.  Alarm classes define group-shared properties such as corrective action and rationale and are persisted on thealarm-classestopic.   The JAWS effective processor joins classes to instances to form effective alarm registrations on theeffective-registrationstopic.Activations indicate an alarm is annunciating (active), and timely operator action is required.  Alarms are triggered active by producing messages on thealarm-activationstopic.  An alarm can be overridden to either suppress or incite the active state by placing a message on thealarm-overridestopic.  The effective notification state considering both activations and overrides is calculated by JAWS fromactivationsandoverridesand made available on theeffective-notificationstopic.Both effective registrations and effective notifications are combined by the JAWS effective processor on theeffective-alarmstopic.Servicesjaws-effective-processor: Process classes and overrides and provide effective state on theeffective-registrations,effective-notifications, andeffective-alarmstopicsjaws-admin-gui: GUI for managing alarm registrationsjaws-operator-gui: GUI for monitoring alarms and managing overridesAPIsjaws-libj: Java API library for JAWSjaws-libp: Python API library for JAWSDataJLab AlarmsPluginsjaws-epics2kafka: Connects EPICS alarms to JAWSregistrations2epics: Notifies epics2kafka of EPICS alarm registration updatesQuick Start with ComposeGrab projectgit clone https://github.com/JeffersonLab/jaws
cd jawsLaunch Dockerdocker compose upMonitor active alarmsdocker exec -it jaws /scripts/client/list_activations.py --monitorTrip an alarmdocker exec jaws /scripts/client/set_activation.py alarm1Note: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.See:Docker Compose StrategySee: MoreUsage ExamplesInstallCore scriptsRequiresPython 3.9+pip install jaws-scriptsNote: It's generally recommended to use a Python virtual environment to avoid dependency conflicts (else a dedicated Docker container can be used).Entire applicationThe entire JAWS application consists of multiple microservices and each one has a separate installation.  However, you can launch them all using the docker composehere.   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 leveragingsystemctl --hostto Ansible/Chef/Puppet/Whatever, or perhaps Kubernetes + tooling.APIAdmin Scripts APISphinx DocsConfigureThe following environment variables are required by the scripts:NameDescriptionBOOTSTRAP_SERVERHost and port pair pointing to a Kafka server to bootstrap the client connection to a Kafka Cluster; example:kafka:9092SCHEMA_REGISTRYURL to Confluent Schema Registry; example:http://registry:8081The Docker container requires the script environment variables, plus can optionally handle the following environment variables as well:NameDescriptionALARM_LOCATIONSPath 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|parentALARM_CATEGORIESPath 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:nameALARM_CLASSESPath 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|offdelaysecondsALARM_INSTANCESPath 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|screencommandBuildThisPython 3.9+project is built withsetuptoolsand may be run using either the Pythonvirtual environmentfeature or a dedicated Docker container to isolate dependencies.   Thepiptool 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 buildNote for JLab On-Site Users: Jefferson Lab has an interceptingproxySee:Python Development NotesandDocker Development Quick ReferenceTestThe 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:Start Docker Test environmentdocker compose -f test.yml upExecute Testsdocker 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:9094andSCHEMA_REGISTRY=http://localhost:8081ReleaseBump the version number in setup.cfg and commit and push to GitHub (usingSemantic Versioning).Create a new release on the GitHubReleasespage corresponding to same version in setup.cfg (Enumerate changes and link issues)Clean build by removingbuild,dist, anddocsrc/source/_autosummarydirectoriesActivatevirtual envFrom 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/*Build and pushDocker imageUpdate Sphinx docs by copying them from build dir into gh-pages branch and updating index.html (commit, push).See AlsoOverrides and Effective StateSoftware DesignDeveloper Notes