alarms

Alarms

The Alarms service stores, manages and exposes alarms raised by rules and device activity. It consumes alarm events from the message broker, persists them to PostgreSQL, and provides an HTTP API for listing, viewing, updating, and deleting alarms with full authn/authz, metrics, and tracing support.

Configuration

The service is configured using the following environment variables (values shown are from docker/.env as consumed by docker/docker-compose.yaml):

Features

• Alarm ingestion: Consumes alarms from the message broker and persists them to PostgreSQL.
• Stateful updates: Updates assignee, acknowledgment, resolution, and metadata fields.
• Filtering and paging: Lists alarms by domain, rule, channel, client, subtopic, status, severity, and time range.
• Observability: /metrics Prometheus endpoint and Jaeger tracing support.
• Auth and authorization: Authn/authz enforced via gRPC auth and domains services.

Architecture

Runtime flow

1. The message broker publishes alarm events under the alarms.> subject.
2. The Alarms consumer decodes the event payload, enriches it with message metadata, validates it, and calls CreateAlarm.
3. The repository writes to PostgreSQL while deduplicating repeated active alarms with the same severity.
4. The HTTP API exposes list/view/update/delete operations with authn/authz, metrics, and tracing middleware.

Components

• HTTP API: alarms/api exposes REST endpoints and health/metrics handlers.
• Service layer: alarms/service.go validates requests and coordinates repository operations.
• Repository: alarms/postgres/alarms.go implements persistence and filtering.
• Consumer: alarms/consumer processes broker messages and creates alarms.
• Message broker: alarms/brokers uses NATS JetStream with stream alarms and subject alarms.>.
• Migrations: alarms/postgres/init.go defines the alarms schema and indexes.

Alarms table

Defined in alarms/postgres/init.go:

Index: idx_alarms_state (domain_id, rule_id, channel_id, subtopic, client_id, measurement, created_at DESC)

Deployment

Build and run locally

make alarms

MG_ALARMS_LOG_LEVEL=debug \
MG_ALARMS_HTTP_PORT=8050 \
MG_ALARMS_DB_HOST=localhost \
MG_ALARMS_DB_PORT=5432 \
MG_ALARMS_DB_USER=magistrala \
MG_ALARMS_DB_PASS=magistrala \
MG_ALARMS_DB_NAME=alarms \
SMQ_MESSAGE_BROKER_URL=nats://localhost:4222 \
SMQ_AUTH_GRPC_URL=localhost:7001 \
SMQ_AUTH_GRPC_TIMEOUT=300s \
SMQ_DOMAINS_GRPC_URL=localhost:7003 \
SMQ_DOMAINS_GRPC_TIMEOUT=300s \
./build/alarms

Docker Compose

The service is available as a Docker container. Refer to docker/docker-compose.yaml for the alarms and alarms-db services and their environment variables. For a full local stack, make sure the auth, domains, and message broker services are also running.

docker compose -f docker/docker-compose.yaml up alarms alarms-db

Health check

curl -X GET http://localhost:8050/health \
  -H "accept: application/health+json"

Testing

go test ./alarms/...

Usage

The Alarms service supports the following operations:

Alarm creation is driven by message broker events and is not exposed as an HTTP endpoint.

Example: List alarms

curl -X GET "http://localhost:8050/<domainID>/alarms?limit=10&offset=0&status=active&severity=50" \
  -H "Authorization: Bearer <your_access_token>"

Example: View an alarm

curl -X GET http://localhost:8050/<domainID>/alarms/<alarmID> \
  -H "Authorization: Bearer <your_access_token>"

Example: Update an alarm

curl -X PUT http://localhost:8050/<domainID>/alarms/<alarmID> \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cleared",
    "assignee_id": "<userID>",
    "severity": 40,
    "metadata": { "note": "cleared after inspection" }
  }'

Example: Delete an alarm

curl -X DELETE http://localhost:8050/<domainID>/alarms/<alarmID> \
  -H "Authorization: Bearer <your_access_token>"

Example: Health check

curl -X GET http://localhost:8050/health \
  -H "accept: application/health+json"