Alarms overview

Alarms let you define rules in a Project that watch your dataspace data or your devices’ connectivity. When a rule’s condition is met, Golain opens an alarm instance, tracks whether someone has acknowledged it, notifies the people who subscribed, and can open a work order. The model follows ISA-18.2 alarm-management concepts: every alarm has a priority, operators acknowledge alarms they have seen, and they can shelve a nuisance alarm for a bounded time.

Who this is for

Role	Start here
Operator / control-room user	Console guide → Silences and shelving
Process or reliability engineer authoring rules	Your first alarm → Kinds and conditions → Notifications
Integrator / backend developer	Kinds and conditions → API reference
Platform admin	Notifications → Troubleshooting

At a glance

Core concepts

Concept	What it is
Alarm definition	The rule. It has a `key` (unique in the Project), a `name`, a `kind`, a `priority`, a condition, and timing settings such as `eval_interval_seconds`, `for_seconds`, and `keep_firing_for_seconds`. In the Console, definitions live under Alarms → Definitions.
Alarm instance	One occurrence of a definition firing for one identity (labelset). A definition can have many open instances at once — for example, one per device or one per value combination of the columns in `labels_by`. In the Console, open instances appear on Alarms → Board.
Labels	The key/value pairs that identify an instance, returned in the instance’s `labels` field. For threshold rules, they come from the result columns you list in `labels_by`. Device offline rules key on `device_id`. If you set no `labels_by`, the rule has a single instance.
Priority	A number from `1` to `4`: `1` Critical, `2` High, `3` Medium, `4` Low. The default is `3`. Priority drives sort order on the Board.
Active / inactive	`is_active` turns a definition on or off. An inactive definition is not evaluated. Use the activate and deactivate actions to toggle it without deleting it. Golain can also deactivate a rule automatically if its query repeatedly runs past its time budget; reactivating it clears that state.
Shelving	An operator hides one instance until a chosen time (`shelved_until`). While shelved, the instance is not re-evaluated. A definition’s `shelve_max_hours` (default `24`) caps how far ahead you can shelve.
Silence	A time window with label matchers. Matching instances still open, but their notifications are suppressed. Manage silences under Alarms → Silences.
Inhibition	A rule that suppresses notifications for target alarms while a matching source alarm is firing — for example, mute per-sensor alarms while a gateway-down alarm is active. Instances still open.

See Silences and shelving for details on all three suppression tools.

Alarm kinds

Kind	Fires when	Instance identity
`event`	With a query: a scheduled SQL query (`query_spec.sql`) returns at least one row. Without a query: a row in a `state` dataspace changes and your CEL condition is true for it.	With a query, one instance for the rule (or its asset). Without, one per dataspace row.
`threshold`	A scheduled SQL query returns rows, and your CEL condition is evaluated per row and labelset. Each row’s columns are available as `event.<column>`.	One instance per `labels_by` combination
`staleness`	An MQTT device has been offline longer than `staleness_window_seconds`. Golain checks every minute; a reconnect resolves the instance immediately.	One instance per device

For query, CEL, timing, and no-data settings, see Kinds and conditions.

Device offline (staleness) rules apply only to devices that hold an MQTT connection. For devices that send data another way, use a threshold rule that checks when data last arrived in the dataspace.

Lifecycle

Every instance moves along two independent axes:

Axis	API field	Values
Condition	`condition_state`	`pending`, `firing`, `resolved`, `latched`
Acknowledgement	`ack_state`	`unacknowledged`, `acknowledged`

“Inactive” means there is no open instance for that labelset. Instances also carry a coarser process_state of active (pending or firing) or normal (resolved, latched, or closed). Timestamps such as opened_at, cleared_at, and closed_at record each step.

Setting	Effect
`for_seconds`	How long the condition must hold before a Pending instance becomes Firing. With `0`, the instance fires on the first evaluation that meets the condition.
`keep_firing_for_seconds`	How long the condition must stay clear before a Firing instance resolves. Use it to stop a value that hovers around the limit from flapping.
`latching`	When `true`, a cleared instance moves to Latched instead of Resolved and stays open. The Console calls this Stay open until acknowledged.

Key behaviors:

A pending instance that clears never alarmed. It closes without moving to Firing.
Resolved but unacknowledged instances stay open for review. A resolved instance closes only after someone acknowledges it. If the condition returns first, it goes straight back to Firing.
Acknowledging does not clear the condition. It records who saw the alarm (ack_state becomes acknowledged) and stops repeat notifications.
Latched instances stay open. Acknowledging a latched instance records the acknowledgement but does not close it, and the API and Console have no reset action yet. Turn on latching only where you want an alarm to stay visible after it clears.
Shelved instances skip evaluation. Their state does not change until shelved_until passes or someone unshelves them.

The Console shows condition states as Pending, Firing, Resolved, and Latched, and acknowledgement as Acked or Unacked.

Permissions

Action	Permission
List and view definitions, instances, silences, and inhibitions	Project access
Create, edit, delete, activate, or deactivate definitions	Project manage assets permission
Create, edit, or delete silences and inhibitions	Project manage assets permission
Acknowledge, shelve, or unshelve an instance	Project access — no extra permission

Next steps

Your first alarm

Create a rule, watch it fire, and acknowledge it end to end.

Console guide

Use Board, Definitions, and Silences in the Console.

Kinds and conditions

Write SQL queries and CEL conditions, and tune timing and no-data handling.

Notifications

Subscribe people to alarm events, set re-notify and escalation, and open work orders.

API reference

Every HTTP endpoint for definitions, instances, silences, and inhibitions.

Getting started

Dataspaces

Console

Dashboards

Alarms

Ticketing

Alarms overview

Who this is for

At a glance

Core concepts

Alarm kinds

Lifecycle

Permissions

Next steps

Your first alarm

Console guide

Kinds and conditions

Notifications

API reference

​Who this is for

​At a glance

​Core concepts

​Alarm kinds

​Lifecycle

​Permissions

​Next steps

Your first alarm

Console guide

Kinds and conditions

Notifications

API reference

Who this is for

At a glance

Core concepts

Alarm kinds

Lifecycle

Permissions

Next steps