Skip to main content
Golain gives you four ways to quiet alarms. They differ in what they quiet and for how long:
  • Shelve parks one alarm instance until a time you choose.
  • A silence holds back notifications for every alarm whose labels match, for a time window.
  • An inhibition holds back notifications for target alarms while a related source alarm is firing.
  • Deactivating a definition stops the rule from being evaluated at all.

​
Compare the options

Silences and inhibitions never stop an alarm from opening. The alarm opens, its history is recorded, and it appears on the Board — only the notification is held back. Use shelving when you want an instance to stop changing state.

​
Shelve an alarm instance

Shelve an instance when you know about the problem and are working on it, and you do not want reminders or state changes in the meantime. While an instance is shelved:
  • Golain does not evaluate it, so it does not fire, resolve, or change state.
  • Re-notify reminders pause. They resume on the next interval after the shelf ends. See Notifications.
  • The instance stays open and appears on the Board with a Shelved badge.
  • Its acknowledgement state does not change. An unacknowledged alarm stays unacknowledged.
You can shelve only an open, alarming instance — one that is pending or firing. Closed or resolved instances return only active alarm instances can be shelved.

​
Shelve from the Console

1

Open the alarm

Go to Alarms → Board. Click Shelve on the alarm’s row, or open the instance and click Shelve in the header.
2

Pick a duration

In Shelve this alarm, choose 30 min, 1 h, 4 h, End of shift, or Custom (minutes). Presets longer than the definition’s limit are hidden. The dialog shows This alarm allows up to … with the limit.
3

Add a reason

Enter a Reason so the next person knows what is being done. It is recorded on the instance with your name.
4

Confirm

Click Shelve for …. If the alarm is still unacknowledged, you can click Acknowledge and shelve instead to do both.
To end a shelf early, click Unshelve on the Board row or the instance page.

​
Shelve with the API

The response is the updated instance under data.item, with shelved_at, shelved_until, shelved_by, and shelve_reason set. To unshelve, send an empty POST:
Unshelving clears all four shelve fields. Unshelving an instance that is not shelved returns alarm instance is not shelved.

​
Shelve limit and auto-unshelve

​
Silences

A silence holds back notifications for every alarm whose labels match a set of matchers, during a time window. Use silences for planned maintenance, commissioning, or any known period when alarms are expected.

​
How silences apply

  • A silence applies when it is enabled (is_active is true) and the current time is between starts_at and ends_at, inclusive.
  • Golain checks silences when an alarm fires and when it resolves. If any active silence matches, that notification is not delivered.
  • Golain also checks silences before each re-notify reminder. A silenced reminder is skipped, and reminders resume once the silence ends.
  • A silence created after an alarm has already fired does not recall the notification that was already sent. It does stop later reminders.
  • A new or edited silence can take up to about 15 seconds to take effect.

​
Matcher syntax

A matcher set is a JSON array of objects. Every matcher must match (AND).
Rules to remember:
  • Regular expressions are fully anchored. prod matches only prod, not production. Use prod.* to match both.
  • A missing label counts as an empty string. site="" matches alarms with no site label, and site!=pune-2 also matches alarms with no site label.
  • Label values are compared as text. Numbers and booleans in an instance’s labels are matched by their string form, for example "42" or "true".
  • An invalid operator or regular expression is rejected when you save, with invalid matchers: ….
An empty matcher array ([]) matches every alarm in the Project. The Console requires at least one matcher, but the API accepts an empty array. Double-check API requests before you create a silence.

​
Labels you can match on

Matchers test the instance’s labels — the same key/value pairs returned in the instance’s labels field and shown under Labels on the instance page. They do not include the definition’s key, name, kind, or priority. If you are unsure, the instance’s labels field is always the source of truth.
To target alarms by site, line, or gateway, include those columns in the rule’s labels_by so they become labels. Before creating a silence, open a matching instance and copy the exact keys and values from its Labels. See Kinds and conditions.
The Console pre-fills new silence and inhibition forms with example matcher rows such as alarm or kind. Replace them with label keys your instances actually carry, or the silence will not match.

​
Manage silences in the Console

1

Open Silences

Go to Alarms → Silences. The page lists Silences and Inhibitions.
2

Create a silence

Click New silence. Add one or more Matchers, then set Starts and Ends (the window defaults to now plus four hours).
3

Add a reason

Enter a Reason (required). Optionally fill Approved by.
4

Save

Click Create silence.
Each silence row shows its matchers, window, reason, author, and a state badge: Use Edit, Disable / Enable, and Delete on each row. After you delete a silence, notifications it was holding back resume on the next evaluation.

​
Manage silences with the API

All paths are under https://api.ilyama.golain.io/core/api/v1. Reads need can_read_assets on the Project. Create, update, and delete need can_manage_assets. Create body:
The response returns the stored silence under data.item:
Update sends only the fields you want to change, and lists their names in _keys (required). For example, to end a silence early by disabling it:
Updatable keys: matchers, starts_at, ends_at, reason, approved_by, is_active, metadata. Delete returns {"ok": 1}:

​
Inhibitions

An inhibition holds back notifications for target alarms while a related source alarm is firing. Use it to cut cascade noise — for example, when a gateway goes down, mute the alarms from every sensor behind that gateway.

​
How inhibitions apply

When a target alarm fires or resolves, Golain mutes its notification if all of these are true:
  1. The inhibition is enabled (is_active is true).
  2. The target alarm’s labels match target_matchers.
  3. At least one other alarm in the Project is currently firing and its labels match source_matchers.
  4. The source and target have the same value for every label in equal_labels. A label missing from both counts as equal. If equal_labels is empty, any matching source mutes any matching target.
Keep these behaviors in mind:
  • The source must be firing at the moment the target fires or resolves. If the target fires first, its notification is sent.
  • An alarm never inhibits itself or a peer through a symmetric rule. If a target also matches the source side, sources that also match the target side are ignored.
  • Inhibitions apply to the fire and resolve notifications. They do not pause re-notify reminders — use a silence or shelve the instance for that.
  • Inhibitions have no time window. They stay in effect until you disable or delete them.

​
Manage inhibitions in the Console

Inhibitions live on the same page as silences.
1

Open Silences

Go to Alarms → Silences and click New inhibition.
2

Set the source

Under While a source fires, add matchers for the alarm that indicates the root cause.
3

Set the targets

Under Mute targets, add matchers for the alarms to mute.
4

Join on labels

In When these labels match, enter comma-separated label keys, for example gateway_id, site. Leave it empty to let any source mute any target.
5

Save

Optionally add a Reason, then click Create inhibition.
Each inhibition row shows While, Mute, and When these match, with an Armed or Disabled badge. Use Edit, Disable / Enable, and Delete on each row.

​
Manage inhibitions with the API

Permissions match silences: can_read_assets to read, can_manage_assets to change. Create body:
The response returns the stored rule under data.item. Updates use PATCH with _keys, and the updatable keys are source_matchers, target_matchers, equal_labels, reason, is_active, and metadata. DELETE returns {"ok": 1}. In this example, while the gateway’s device offline alarm is firing, notifications are muted for alarms labeled site=pune-2 (for example, a threshold rule with site in its labels_by).
equal_labels joins source and target only on label keys they both carry. A device offline alarm carries only device_id, so when the source is a device offline rule, scope the targets with matchers, as in the example, rather than equal_labels.

​
Acknowledge versus shelve

Acknowledging and shelving do different jobs. You often want both.
Shelving does not acknowledge an alarm. An unacknowledged alarm stays counted as unacknowledged on the Board and in its history while shelved. Use Acknowledge and shelve in the Console, or call both endpoints, when you want both.

​
Next steps