Provides public APIs to the Fermilab control system. This service exposes several GraphQL endpoints for various, logical APIs that clients may use to retrieve control system data and, in some cases, make changes to the control system. This service is currently running on acsys-proxy.fnal.gov on port 8000 with the development instance on port 8001.
The middle layer of the control system uses gRPCs for communications. The GraphQL resolvers of this service use various gRPC services to obtain the information that is returned. This uses the async-graphql and warp crates to provide GraphQL over http support. The resolvers use the tonic crate for gRPC client support.
This service uses rdkafka (librdkafka bindings) for Kafka pub/sub.
If you are building locally (outside the devcontainer/Docker image), you may need native dependencies installed.
Debian/Ubuntu packages typically required:
libsasl2-devlibcurl4-openssl-dev
Depending on your environment, you may also need a C toolchain and build tooling (e.g. cmake, pkg-config).
The following variables exist for configuring the service at runtime:
ALARMS_KAFKA_HOST-> Hostname for the Kafka instance that supports the alarms serviceALARMS_KAFKA_TOPIC-> Topic name for alarms in KafkaCLOCK_GRPC_HOST-> Hostname for the clock gRPC serviceDEVDB_GRPC_HOST-> Hostname for the DevDB gRPC serviceDPM_GRPC_HOST-> Hostname for the DPM gRPC serviceGRAPHQL_PORT-> Port for clients to connect via GraphQL to this serviceGRPC_ALARMS_DB_HOST-> Hostname for the Alarms DB Access gRPC serviceKAFKA_CONNECTION_SECONDS-> Kafka operation timeout (seconds) used by the pub/sub layer (connect/send/etc.). This also affects test runs via.cargo/config.toml.RUST_LOG-> The default logging environment variable from Rust. Can be configured to log specific crates/modules at different levels from the global default.SCANNER_GRPC_HOST-> Hostname for the wire scanner gRPC serviceTLG_GRPC_HOST-> Hostname for the TLG gRPC service
Alarms requests intentionally return a generic error message that includes an Error ID (a UUID). The underlying error details are logged server-side.
To debug an issue reported by a client:
- Copy the Error ID from the client-visible message.
- Search the server logs for that UUID to find the corresponding detailed error entry.
$ git clone --recurse-submodules https://github.com/fermi-ad/extapi-acsys.git
$ cd extapi-acsysThe main branch is used for deployment; developers cannot commit directly to the main branch. Create a development branch which will host your changes. Once you're ready to release them, create a pull request.
$ git checkout -b develMake changes and commit them to this branch.
$ git push origin develGo to GitHub and make a pull request using this branch.