> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ilyama.golain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Alarms overview

> Watch dataspace data and device connectivity with project-scoped alarm rules, track acknowledgement, and notify the right people.

**Alarms** let you define rules in a Project that watch your [dataspace](/dataspaces/overview.md) 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](/alarms/console-guide.md) → [Silences and shelving](/alarms/silences-and-shelving.md) |
| Process or reliability engineer authoring rules | [Your first alarm](/alarms/first-alarm.md) → [Kinds and conditions](/alarms/kinds-and-conditions.md) → [Notifications](/alarms/notifications.md) |
| Integrator / backend developer | [Kinds and conditions](/alarms/kinds-and-conditions.md) → [API reference](/alarms/api-reference.md) |
| Platform admin | [Notifications](/alarms/notifications.md) → [Troubleshooting](/alarms/troubleshooting.md) |

## At a glance

```mermaid theme={null}
flowchart LR
  subgraph sources [What alarms watch]
    DS[Dataspace data]
    CONN[Device connection state]
  end
  DEF[Alarm definition<br/>evaluated on a schedule<br/>or on data change]
  INST[Alarm instance<br/>one per labelset]
  subgraph outcomes [What happens next]
    NOTIFY[Notifications]
    WO[Work orders]
    OP[Operator acknowledges<br/>or shelves]
  end
  DS --> DEF
  CONN --> DEF
  DEF -->|condition met| INST
  INST --> NOTIFY
  INST --> WO
  INST --> OP
```

## 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](/alarms/silences-and-shelving.md) 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](/alarms/kinds-and-conditions.md).

> [!NOTE]
>
> 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.

```mermaid theme={null}
stateDiagram-v2
  [*] --> Pending: condition met
  Pending --> Firing: held for for_seconds
  Pending --> [*]: condition clears (closes)
  Firing --> Resolved: clear held for keep_firing_for_seconds
  Firing --> Latched: clear held, rule has latching on
  Resolved --> Firing: condition met again
  Resolved --> [*]: acknowledged (closes)
  Latched --> Latched: stays open
```

| 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](/alarms/first-alarm.md)**
>
> Create a rule, watch it fire, and acknowledge it end to end.

> **[Console guide](/alarms/console-guide.md)**
>
> Use **Board**, **Definitions**, and **Silences** in the Console.

> **[Kinds and conditions](/alarms/kinds-and-conditions.md)**
>
> Write SQL queries and CEL conditions, and tune timing and no-data handling.

> **[Notifications](/alarms/notifications.md)**
>
> Subscribe people to alarm events, set re-notify and escalation, and open work orders.

> **[API reference](/alarms/api-reference.md)**
>
> Every HTTP endpoint for definitions, instances, silences, and inhibitions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.