# CloudWatch alarms

The **Alarms** page lists every CloudWatch alarm in a profile and region, firing ones first. Open one to see why it fired, its rule in plain words, its metric against the threshold and its state history. Separately, ARNscope can check your alarms in the background across several profiles and regions and post a Mac notification when one trips. The AWS console has nothing like either.

<figure class="doc-video">
<video controls playsinline preload="none" poster="/media/docs/alarms/alarms-explainer.webp?v=1" aria-label="CloudWatch alarms in ARNscope: a narrated tour of about a minute and a half">
<source src="/media/docs/alarms/alarms-explainer.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-explainer.mp4?v=1" type="video/mp4">
<track kind="captions" srclang="en" label="English" src="/media/docs/alarms/alarms-explainer.vtt?v=1" default>
</video>
<figcaption>A narrated tour, with captions: the alarm list and detail, background checks, notifications, muting, sign-ins, widgets and refresh. Sample data.</figcaption>
</figure>

## The alarm list

Alarms are sorted by state: **In alarm**, then **Insufficient data**, then **OK**. The state filter shows a count for each, and the search field filters by name. The list comes from one `DescribeAlarms` call for the region (metric and composite alarms).

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-list.webp?v=1" aria-label="The alarm list, firing alarms first; filtering by state and by name.">
<source src="/media/docs/alarms/alarms-list.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-list.mp4?v=1" type="video/mp4">
</video>
<figcaption>Firing alarms first; filter by state or name.</figcaption>
</figure>

## What the states mean

| State | Shown as | In plain words |
| --- | --- | --- |
| `ALARM` | **In alarm**, red | The metric crossed the threshold for enough of the recent periods (for example 3 of the last 5). This is the one that needs you. |
| `INSUFFICIENT_DATA` | **Insufficient data**, grey | CloudWatch doesn't have enough data points to decide either way. It is not a failure in itself, so ARNscope shows it in a neutral grey, not a warning colour. |
| `OK` | No chip in the list; **OK**, green, elsewhere | The metric is on the right side of the threshold. |

**Insufficient data usually means one of these:**

- The alarm or its metric is new, and CloudWatch hasn't collected enough periods yet.
- The metric only reports when something happens. Error and request counts often send nothing while there is no traffic, so a quiet service sits in insufficient data.
- The resource is stopped, idle or gone, so its metric stopped reporting.
- The alarm's metric name or dimensions don't match a real metric (a typo, or a resource that was renamed or replaced), so it never gets data.

**When to worry:** when the metric should report all the time (CPU of a running instance, a heartbeat your app sends every minute) and the alarm has dropped into insufficient data. Then data has stopped arriving, which can mean the thing it watches has stopped. Open the alarm and check the metric chart for where the line ends and the state history for when it changed. Whether missing data counts as breaching, OK or missing is the alarm's own setting in CloudWatch.

## One alarm

- **State, Since, Condition and Actions.** The condition reads like the rule, for example `Sum HTTPCode_Target_5XX_Count > 25 for 3 of 5 × 1 min`. Composite alarms show their rule; metric-math alarms say so.
- **Why it fired:** CloudWatch's state reason, word for word.
- **The metric** against a threshold line, over 3 hours, 1 day or 1 week (one `GetMetricData` call for one metric).
- **State history:** every state change and configuration update, newest first (`DescribeAlarmHistory`).
- Dimensions, description, alarm actions and the ARN. The title copies the name; right-click copies the ARN.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-detail.webp?v=1" aria-label="An alarm's state, condition and reason; its metric against the threshold over a week; its state history.">
<source src="/media/docs/alarms/alarms-detail.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-detail.mp4?v=1" type="video/mp4">
</video>
<figcaption>Why it fired, the metric against the threshold, and every change.</figcaption>
</figure>

## Background checks and Mac notifications

**Settings → Alarm notifications** turns on a light background check. ARNscope is not a monitoring service: this is one small API call per profile and region, run by the app on your Mac.

- **What it checks.** **All alarms** in the chosen profiles (all of `~/.aws`, or the ones you pick) and regions (each profile's default region unless you add others), except alarms you mute. Or **Only alarms I pick**, which you turn on with **Notify me** on an alarm.
- **How often.** Every 30 seconds, 1 minute (the default) or 5 minutes. Each check is one `DescribeAlarms` call per profile/region pair, filtered to alarms in ALARM. The setting shows the calls a month: about 43,000 per pair at one minute. CloudWatch's free tier covers 1,000,000 API requests a month; beyond that it is US$0.01 per 1,000.
- **It keeps going with the window closed.** The check runs in the app's Rust backend, so it continues while the window is hidden or closed, as long as ARNscope is running.
- **Notifications.** When an alarm newly enters ALARM, macOS shows a notification with its name, profile, region and reason. Clicking it opens that alarm, switching profile and region if needed. Alarms already firing when ARNscope starts appear on the Alarms page and in the rail badge but do not notify. **Send test notification** checks that notifications reach you (System Settings and Focus modes decide).
- **Turned off, nothing is polled.**

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-watch-settings.webp?v=1" aria-label="Settings, Alarm notifications: which alarms, profiles and regions, the check interval with its monthly call count, and the status of each profile and region.">
<source src="/media/docs/alarms/alarms-watch-settings.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-watch-settings.mp4?v=1" type="video/mp4">
</video>
<figcaption>What is checked, how often, what it costs, and the status of each profile and region.</figcaption>
</figure>

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-notification.webp?v=1" aria-label="A notification for order-events-dlq-not-empty arrives while another page is open; clicking it opens the alarm.">
<source src="/media/docs/alarms/alarms-notification.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-notification.mp4?v=1" type="video/mp4">
</video>
<figcaption>A click on the notification opens the alarm. (The notification in this clip is drawn: the web preview the clips are recorded from has no macOS notifications.)</figcaption>
</figure>

### Firing across profiles, muting and the rail badge

While checks are on, the top of the alarm list shows **Firing across profiles**: every firing alarm in every watched profile and region, whichever profile the page is on. Click one to open it. **4 watched** opens the settings. Hover an alarm there, or use **Notifying** on an open alarm, to mute just that alarm; muted alarms never notify, count or show as firing. The rail's Alarms icon shows how many are firing, on any page.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-mute.webp?v=1" aria-label="Firing across profiles; an alarm muted and turned back on with its Notifying button.">
<source src="/media/docs/alarms/alarms-mute.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-mute.mp4?v=1" type="video/mp4">
</video>
<figcaption>Firing alarms from every watched profile; mute one with a click.</figcaption>
</figure>

### Expired sign-ins

If a profile's sign-in (usually an AWS SSO session) expires, its checks pause and its status reads **Sign-in expired, paused**. You get one notification per expired session, not one per check; clicking it, or **Sign in** in the settings, runs `aws sso login` for that session (this needs the AWS CLI) and checks again as soon as you are signed in. A sign-in from a terminal resumes the checks too.

## Desktop widgets

ARNscope ships macOS desktop widgets (macOS 14 or later):

- **Alarms firing**, fed by the background check above.
- **CloudWatch alarm** and **CloudWatch metric**, for alarms and metrics you pin.

### Pinning

| Pin | Where |
| --- | --- |
| An alarm | The pin in an open alarm's title bar, **Add to macOS widget**. On a pinned alarm it reads **On the macOS widget: click to remove it**. |
| A metric | Hover a chart on the CloudWatch page and use its pin, **Add to macOS widget…** (one item per metric when a chart has several). The same menu removes it. Metric math can't be pinned. |

Before you add one, the dialog shows the alarm or metric (namespace, statistic and period, profile, region, dimensions), lets you give it a label for the widget, and says what it will read and roughly what it costs a month. A metric's period is rounded to whole minutes, at least one. The same alarm or metric can't be pinned twice.

You can have up to **50 pins** across all profiles. At the limit the dialog says *50 pins is the limit. Remove one in Settings → Widgets first.*

### What pins read, and Settings → Widgets

Pinning is what turns on these reads; with nothing pinned, nothing is read. Every 5, 15 (the default) or 30 minutes, per profile and region, ARNscope makes one `DescribeAlarms` call for the pinned alarms and one `GetMetricData` call for the pinned metrics and each pinned alarm's metric. This runs while ARNscope is running, even with its window closed; when it isn't running, the widgets show when they were last updated. `GetMetricData` is billed per metric (US$0.01 per 1,000) and is not in the free tier.

**Settings → Widgets** lists every pin with its last reading, the interval, and the calls and cost a month. **Open** opens a pin in ARNscope; rename and remove pins there. Each pin's status reads:

| Status | Meaning |
| --- | --- |
| A value, or an alarm state | The last read worked. |
| **Waiting for the first read** | Just pinned. |
| **No data in the window** | The read worked but the metric had no recent point. |
| **Sign in to \<profile\>** | The profile's sign-in expired. |
| **Profile not in ~/.aws, not read** | The pin's profile is no longer in your AWS config. The pin is kept but not read. |
| An error message | CloudWatch's error for that read. |

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-widget.webp?v=1" aria-label="Adding an alarm to the desktop widgets with a label, the cost note in the dialog, and the pin in Settings, Widgets.">
<source src="/media/docs/alarms/alarms-widget.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-widget.mp4?v=1" type="video/mp4">
</video>
<figcaption>Add to widget says the cost first; pins are listed in Settings → Widgets.</figcaption>
</figure>

## Refreshing

The page reads alarms when you open it and when you press refresh. **Auto-refresh** is off until you pick an interval, and it pauses while the page or window is in the background.

<figure class="doc-clip">
<video data-clip controls muted loop playsinline preload="none" poster="/media/docs/alarms/alarms-refresh.webp?v=1" aria-label="The auto-refresh menu: Off by default, with intervals, and a note that it pauses in the background.">
<source src="/media/docs/alarms/alarms-refresh.webm?v=1" type="video/webm">
<source src="/media/docs/alarms/alarms-refresh.mp4?v=1" type="video/mp4">
</video>
<figcaption>Auto-refresh is opt-in and pauses in the background.</figcaption>
</figure>

## Limitations

- The background check watches at most 100 profile/region pairs.
- Notifications are for alarms entering ALARM, not for insufficient data or a return to OK. Clicking a notification opens the alarm on macOS; other platforms show the text only.
- Only alarms in ALARM are fetched by the background check, so a check is small however many alarms you have.
- At most 50 widget pins, and metric math can't be pinned.
- ARNscope reads alarms; it doesn't create, change or delete them.

Need another kind of alert? Write to [hello@arnscope.com](mailto:hello@arnscope.com) and tell us what you use.

## Permissions

| Action | Used for |
| --- | --- |
| `cloudwatch:DescribeAlarms` | The list, background checks, widget alarms |
| `cloudwatch:DescribeAlarmHistory` | State history |
| `cloudwatch:GetMetricData` | The alarm's metric chart, widget metrics |

Source: https://arnscope.com/docs/alarms
