Skip to main content

Jefferson Lab Alarm Warning System API

Project description

jaws-libp CI PyPI Docker

Reusable Python classes for JAWS plus admin scripts to setup and manage a deployment.



Quick Start with Compose

  1. Grab project
git clone https://github.com/JeffersonLab/jaws-libp
cd jaws-libp
  1. Launch Compose
docker compose up
  1. Monitor active alarms
docker exec -it cli list_activations --monitor
  1. 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: Docker Compose Strategy

Install

Requires Python 3.9+

pip install jaws-libp

Note: Using newer versions of Python may be problematic because the dependency confluent-kafka uses librdkafka, which often does not have a wheel file prepared for later versions of Python, meaning setuptools will attempt to compile it for you, and that often doesn't work (especially on Windows). Python 3.9 does have a wheel file for confluent-kafka so that's your safest bet. Wheel files also generally only are prepared for Windows, MacOS, and Linux. Plus only for architectures x86_64 and arm64, also only for glibc. If you use with musl libc or linux-aarch64 then you'll likely have to compile librdkafka yourself from source.

API

Sphinx Docs

Configure

Environment variables are used to configure jaws-libp:

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 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_SYSTEMS Path to an alarm categories file to import (example file), else an https URL to a file, else a comma separated list of system definitions with fields. Example Inline CSV: name
ALARM_ACTIONS 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|latching|filterable|ondelayseconds|offdelayseconds
ALARMS Path to an alarm registration 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|action|epicspv|location|maskedby|screencommand
ALARMS_URL_CSV If provided, is a comma separated list of file names to append to ALARMS; ignored if ALARMS doesn't start with https; Example.
ALARM_OVERRIDES Path to an alarm overrides file to import (example file), else an https URL to a file.

Build

This Python 3.9+ project is built with setuptools and may be run using the Python virtual environment feature to isolate dependencies. The pip tool can be used to download dependencies.

git clone https://github.com/JeffersonLab/jaws-libp
cd jaws-libp
python -m venv .venv_dev --upgrade-deps

Activate the virtual env using your shell specific command, then install in editable mode with dev deps and run build:

# Windows
.venv_dev\Scripts\activate.bat
# UNIX (SH Shell)
source .venv_dev/bin/activate
# UNIX (CSH Shell)
source .venv_dev/bin/activate.csh


pip install -e ."[dev]"
python -m build
pylint --recursive=y src/*

Note for JLab On-Site Users: Jefferson Lab has an intercepting proxy

See: Python Development Notes

Develop

Set up the build environment following the Build instructions.

In order to iterate rapidly when making changes it's often useful to run the Python scripts directly on the local workstation, perhaps leveraging an IDE. In this scenario run the service dependencies with Docker Compose:

docker compose -f deps.yaml up

Note: The environment variable defaults work in this scenario and are defined as: BOOTSTRAP_SERVERS=localhost:9094 and SCHEMA_REGISTRY=http://localhost:8081

Test

The integration tests depend on a running Kafka instance, generally in Docker. The tests run automatically via the CI GitHub Action on every commit (unless [no ci] is included in the commit message). The tests can be run locally during development. Set up the development environment following the Develop instructions. Then with the deps.yaml Docker containers running and the build virtual environment activated run:

pytest

Release

  1. Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning).
  2. The CD GitHub Action should run automatically invoking:
    • The Create release GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
    • The Publish artifact GitHub Action to create a deployment artifact on PyPi.
    • The Publish docs GitHub Action to create Sphinx docs.
    • The Publish docker image GitHub Action to create a new demo Docker image.

See Also

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jaws-libp-5.0.0.tar.gz (41.8 kB view details)

Uploaded Source

Built Distribution

jaws_libp-5.0.0-py3-none-any.whl (63.6 kB view details)

Uploaded Python 3

File details

Details for the file jaws-libp-5.0.0.tar.gz.

File metadata

  • Download URL: jaws-libp-5.0.0.tar.gz
  • Upload date:
  • Size: 41.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.5

File hashes

Hashes for jaws-libp-5.0.0.tar.gz
Algorithm Hash digest
SHA256 e0369f0b39fc6406f9d9ed1eb3300c0c907d41f8813ff2f0ff91bc6fee76c364
MD5 e65f911f4e3ddab7c1bee112874385b1
BLAKE2b-256 c44418e476b4072dac63eab32ffdb9181e823368fc2d0783dcb99e960d7a98bc

See more details on using hashes here.

File details

Details for the file jaws_libp-5.0.0-py3-none-any.whl.

File metadata

  • Download URL: jaws_libp-5.0.0-py3-none-any.whl
  • Upload date:
  • Size: 63.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.5

File hashes

Hashes for jaws_libp-5.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 870aca10b280f870be03d756640759aa3efbc31a123728adc60b20a99e55c63a
MD5 4dea8983f733030d2fb0e750ccdc937c
BLAKE2b-256 1bca53db17e5e7448bcdb65b7ae3f3a77d9d3d48e56182b7c63f5e511730e70b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page