# CloudWatch dashboards

The **CloudWatch** page shows two kinds of dashboards side by side: the ones in your AWS account, and your own, kept on your Mac. A local dashboard shows the same metric charts, alarm states and text as a console dashboard, but nothing is created in AWS. You can build one from any metric, copy one from AWS, or import one from a JSON file.

## Why keep a dashboard locally

CloudWatch includes 3 dashboards (up to 50 metrics each) per account at no charge, then bills each further dashboard per month. A local dashboard is not a CloudWatch dashboard, so it never counts towards that.

Charts still read data from CloudWatch. Each chart reads its metrics with `GetMetricData`, which CloudWatch bills per metric requested (about US$0.01 per 1,000). See [CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/) for current prices.

## The dashboard list

| Section | What it holds |
| --- | --- |
| **My dashboards** | Your local dashboards for the selected profile. A region chip shows when one is for another region than the page's. |
| **In AWS** | The dashboards in the account (`ListDashboards`) for the profile and region. **Refresh dashboards** reads the list again. |
| **Favourites** (bottom) | Dashboards you starred, from any profile or region. Clicking one switches profile and region and opens it. |

The buttons above the list are **New dashboard**, **Import dashboards from JSON files** and **Refresh dashboards**. **Filter dashboards** filters both sections by name.

The title bar of an open dashboard shows where it lives: **On this machine**, **CloudWatch**, or **Widget pin** (a metric pinned to a macOS widget, opened from the widget or from Settings → Widgets).

## Time range and refresh

- **Time range:** 1h, 3h (the default), 6h, 12h, 1d, 3d or 1w. A dashboard saved with a relative `start` such as `-PT3H` or `-P2W` opens at that range; one that is not a preset is added to the choices as **Range saved with this dashboard**.
- **Refresh widgets** re-reads the charts and sets the **Updated** time. Auto-refresh is **Off** until you pick 10 seconds, 30 seconds, a minute or 5 minutes, and it pauses while the page or window is in the background.
- A widget reads its metrics only once it has been scrolled into view, and a refresh re-reads only widgets that have been on screen. Each metric widget is one `GetMetricData` call.

## Dashboard actions

| Action | My dashboards | In AWS |
| --- | --- | --- |
| **Add to favourites** (star) | Yes | Yes |
| **Copy dashboard JSON**, to paste into the console's source view | Yes | Yes |
| **Add widget** | Yes | No |
| **Edit layout** | Yes, once it has a widget | No |
| **Save a copy** to my dashboards | No | Yes |
| **Export dashboard** | Yes | Save a copy first |
| **Resync from \<file\>** | Imported ones only | No |
| **Delete dashboard…** | Yes, after a confirmation | No |

ARNscope never changes or deletes a dashboard in AWS. In a narrow window the toolbar labels turn into icons, then the actions fold into **More actions** (…).

## Widgets

The grid is CloudWatch's: 24 columns wide. Every widget type in a dashboard body is kept, whether or not ARNscope draws it.

| Widget | How ARNscope shows it |
| --- | --- |
| `metric`, view `timeSeries` | A line chart. With `"stacked": true`, stacked bands, largest at the bottom, in steps (each value holds for its period); the tooltip adds a **Total**. |
| `metric`, view `singleValue` | Each series' latest value as a large number, with its name under it. |
| `metric`, view `gauge` | Like a single value, with a bar under each value filled to its share of the `yAxis.left` `min`/`max` (else 0 to the largest value). |
| `metric`, view `bar` | Like a single value, with a bar under each value filled to its share of the largest value. |
| `metric`, view `pie` or `table` | Each series' latest value as a number, like a single value. |
| `alarm` | One row per alarm: its state and name. Click a row to open the alarm. |
| `text` | Markdown, or plain text as written (see below). |
| `log` (Logs Insights) | Not run. *Logs Insights queries are billed.* **Copy query** copies the query to run in the console. |
| `explorer`, `custom` and other types | Not drawn: *"“explorer” widgets are shown in the CloudWatch console."* |

For a dashboard from AWS, widgets ARNscope doesn't draw also offer **Copy console link** (the app can't open a browser link itself).

### Metric charts

- **Metrics:** each `metrics` row (`[namespace, metricName, dimName, dimValue, …, {options}]`), with `"."` copying the entry above, and metric math (`{"expression": …}`). Row options read: `id`, `label`, `stat`, `period`, `color`, `yAxis`, `visible` (`false` reads the metric but does not draw it). The widget's `stat` and `period` are the defaults for its rows; with no `stat` anywhere, `Average`.
- **Labels:** unlabelled series of the same metric are named by what differs between them (a dimension value, the statistic).
- **Axes:** round ticks on the y axis; 4, 3 or none, by the chart's size. The time axis is hidden when the chart area is under 100 px tall. Large values read in compact form (`25K`).
- **Right axis:** series with `"yAxis": "right"` get their own scale on the right, but only when other series stay on the left; if every series is on the right, they share the left axis.
- **Fixed bounds:** `yAxis.left.min` and `max` are kept; data beyond them is clipped, as in CloudWatch.
- **Thresholds:** horizontal annotations are dashed red lines, with their label and value at the right.
- **Colours:** a series' `color` from the JSON wins; otherwise the app's chart palette.
- **Tooltip:** hover (or focus a chart and use the arrow keys) for the time and every series' value.

### Legends

A chart with one series has no legend: its title names it, and its latest value shows in the header when there's room. With several series, ARNscope picks the first that fits:

1. The full names in the header, beside the title.
2. Shorter names in the header: only what tells the series apart (for example `p50 · p90 · p99`).
3. A legend under the chart, at most two lines, when the plot keeps at least 120 px.
4. Coloured dots in the header, or under the chart when the title would be cut too short. Hover or focus the dots to list every name.

Series on the right axis are marked **(right)**. Charts side by side in a row keep the same legend space under them, so their time axes line up.

### Single values, gauges and bars

Numbers get as large as the tile allows. Several values sit in columns (never an uneven 3 + 1), and tiles of the same height in one row use the same number size so they line up. A value too wide for its cell is shown compact (`5.5K`), or as `…` with the full value in its tooltip; a number is never cut. A tile with one row of values that is at least 140 px tall also draws a small trend line under each value. A value with no data in the range reads **No data in this range**.

### Alarm widgets

Each row shows the alarm's state as on the Alarms page: **OK**, **In alarm** or **Insufficient data**. In a narrow tile the labels shorten to **OK**, **Alarm** and **No data**, then to shapes: a filled dot for OK, a diamond in alarm, a hollow ring for insufficient data (the full state is in the row's tooltip). Long names lose their middle, not their end. Rows that don't fit collapse into **+N more**; click it to list them all. The header shows how many alarms the widget holds.

The states come from one `DescribeAlarms` call per region, the same cached list the Alarms page uses. Alarms are referenced by ARN.

### Text widgets

Text that uses Markdown is rendered; text without any is shown as written, line breaks kept. Supported:

| Markdown | Example |
| --- | --- |
| Headings, levels 1 to 6 | `## Runbook` |
| Bold, italic, strikethrough | `**bold**`, `*italic*`, `_italic_`, `~~old~~` |
| Inline code and fenced code blocks | `` `FLAG=on` ``, ```` ```sql ```` |
| Bulleted and numbered lists, nested by two spaces | `- item`, `1. step` |
| Block quotes | `> note` |
| Tables, with column alignment | `\| a \| b \|` and `\| :-- \| --: \|` |
| Horizontal rules | `---` |
| Links | `[Runbook](https://…)`, `<https://…>` |

A link shows its text and host with a **Copy link** button; links can't be opened from ARNscope yet. CloudWatch's button links (`[button:Label](…)` and `[button:primary:Label](…)`) show as plain links. HTML, images and reference-style links are not rendered. Long text scrolls, with a fade at the bottom while there is more; a wide table scrolls sideways.

### When a widget can't load

- **Couldn't load** with **Retry**: the `GetMetricData` call failed. Larger tiles show CloudWatch's message itself.
- **This widget has no metrics ARNscope can read.**: the widget has no metric rows ARNscope understands.
- **No data in this range**: CloudWatch returned no points for the range.
- A **⚠ count** in the header: CloudWatch's own message about a series (for example partial data, or a bad expression). Hover or focus it to read them.

### Pin a chart to a macOS widget

Hover a chart and use the pin, **Add to macOS widget**, to show one of its metrics on ARNscope's desktop widget (one menu item per metric when the chart has several). The dialog says what it will read and what that costs before you add it. Metric math can't be pinned (*Expressions can’t be pinned to the macOS widget*). See [CloudWatch alarms → Desktop widgets](https://arnscope.com/docs/alarms#desktop-widgets) for how pins are read.

## Build your own

**New dashboard** asks for a name and saves an empty dashboard for the current profile and region. **Add widget** has two tabs:

- **Metrics:** pick a namespace and metrics (search by metric name or dimension value), a **Statistic** (`Average`, `Sum`, `Minimum`, `Maximum`, `SampleCount`, `p50`, `p90`, `p99`) and a **View** (**Line** or **Number**). All picked metrics go into one widget. The list shows metrics that reported in the last 3 hours; tick **Include inactive metrics** for everything from the last two weeks. At most 300 matches are listed.
- **Alarms:** pick metric or composite alarms in the region; they go into one alarm widget.

New metric widgets are half the grid wide (12 × 6), alarm widgets a quarter (6 × 6). They are placed left to right after the last row.

**Save a copy** (on a dashboard in AWS) copies it to my dashboards, named `<name>-copy` unless you change it.

## Edit the layout

Click **Edit layout** on one of your dashboards. Charts and alarm rows stop reacting while you edit. Click **Done**, or press **Esc**, to finish. Every change is saved as you make it.

### With the mouse

| Drag | Does |
| --- | --- |
| The grip (⋮⋮) left of the title | Moves the widget |
| The right edge | Changes its width |
| The bottom edge | Changes its height |
| The bottom-right corner | Changes both |

While you drag, a dashed outline shows where the widget will land, a badge shows its size in columns × rows, and the other widgets move out of the way live. Widgets it lands on are pushed down, and gaps close upward, as in the CloudWatch console. **Esc** during a drag cancels it. **×** removes a widget (on tiles under 160 px wide it appears on hover).

### With the keyboard

Each widget has three tab stops in edit mode: the grip, **Remove** and the resize corner.

| Focus | Key | Does |
| --- | --- | --- |
| Grip | ↑ ↓ | Trades places with the widget above or below it in its columns. With widgets of different heights, whole rows trade places. |
| Grip | ← → | Trades places with the widget beside it when they are the same size; otherwise moves one column into free space. |
| Corner | → ← | One column wider or narrower |
| Corner | ↓ ↑ | One row taller or shorter |

The widget's border flashes where it landed, and screen readers hear where it went (for example *Moved Latency below Errors. Also moved: Throughput.*).

### When a step is refused

A refused step shows a short note on the widget for 2 seconds:

| Note | Why |
| --- | --- |
| **At top** | Nothing is above it in its columns. |
| **Already last** | Nothing is below it, and it is at the bottom of the dashboard. |
| **Nothing below** | Nothing is below it in its columns. A widget can't sit lower with empty space above it: the gap would close and float it back up. |
| **At left edge**, **At right edge** | The grid ends there (also when widening at the right edge). |
| **Size differs** | The widget beside it has a different size, so they can't trade places and there is no free column. |
| **Narrowest**, **Shortest** | The widget is at its minimum size. |

Minimum sizes: 4 columns wide for every widget; 3 rows tall for charts, 2 for single values, alarms, text and other widgets. An older widget already smaller than that keeps its size but can't shrink further.

### Undo

While editing, **Undo** (or **⌘Z**, Ctrl+Z elsewhere) reverses the last move, resize or removal, up to 20 steps. Holding an arrow key counts as one step. Undoing a removal brings the widget back and focuses its grip. The history is cleared when you open another dashboard, leave the page, or change the dashboard another way (Add widget, Resync).

## Import a dashboard

1. Open **CloudWatch** and choose the profile the dashboard is for.
2. Click **Import dashboards from JSON files** and choose one file or several (up to 50 at a time, each up to 1 MB).
3. For one file, check the name and click **Import**. Several files are imported at once under their own names, and the first one opens; files that can't be read are skipped and listed. A name already used gets “Name (2)”.

The dashboard is saved under the profile you have selected, so the same file works for a staging and a production account.

### Resync from the file

Importing copies the file once; later changes to the file don't reach the dashboard on their own. **Resync from \<file\>** reads the same file again and replaces the dashboard with it. If you changed the dashboard in ARNscope since the last sync, ARNscope asks first (**Replace your changes?**). Resync never replaces a dashboard with nothing: if the file has moved, can't be read, or has no widgets, the dashboard is kept and a notice says why.

## Export a dashboard

Select one of your dashboards and click **Export dashboard**. ARNscope saves `<name>.dashboard.json` (the name in lower case, with other characters turned into `-`) in the format below. To export a dashboard that lives in AWS, use **Save a copy** first, then export the copy.

## The file format

The file is CloudWatch's own dashboard body: the JSON shown under **Actions → View/edit source** in the CloudWatch console, and the value of `dashboard_body` in Terraform's `aws_cloudwatch_dashboard`. Any of these can be imported:

- **An ARNscope file**: the body wrapped with a name and region. Export writes this.
- **A bare dashboard body**: an object with a `widgets` list. The name comes from the file name (without `.json` or `.dashboard.json`) and the region from the CloudWatch page.
- **An ARNscope file whose `body` is a JSON string**, as the AWS API and Terraform state return it.

```
{
  "arnscope": "dashboard/v1",
  "name": "Checkout health",
  "region": "us-east-1",
  "body": {
    "start": "-PT3H",
    "widgets": [
      {
        "type": "metric", "x": 0, "y": 0, "width": 12, "height": 6,
        "properties": {
          "title": "Orders placed",
          "view": "timeSeries",
          "region": "us-east-1",
          "metrics": [["Shop/Checkout", "OrdersPlaced", "Environment", "prod"]],
          "stat": "Sum",
          "period": 60
        }
      },
      {
        "type": "alarm", "x": 12, "y": 0, "width": 6, "height": 6,
        "properties": {
          "title": "Checkout alarms",
          "alarms": ["arn:aws:cloudwatch:us-east-1:123456789012:alarm:orders-placed-drop"]
        }
      }
    ]
  }
}
```

| Field | Required | Meaning |
| --- | --- | --- |
| `arnscope` | Yes | Always `"dashboard/v1"`. A file with any other value is refused, so a newer format is never misread. |
| `name` | No | Dashboard name, up to 255 characters. Defaults to “Imported dashboard”. |
| `region` | No | Default region for widgets that do not set their own, such as `us-east-2`. An invalid value falls back to the current region, with a warning. |
| `body` | Yes | The CloudWatch dashboard body, as an object or as a JSON string. |

There is no profile in the file: profile names differ from Mac to Mac. Widgets without `x`, `y`, `width` or `height` stack in order down the left, 6 × 6 each, as in the console. ARNscope only reads the file; nothing in it is run.

### Getting a dashboard body

- **CloudWatch console**: open the dashboard, choose **Actions → View/edit source**, copy the JSON into a file.
- **AWS CLI**:
  ```
  aws cloudwatch get-dashboard --dashboard-name checkout-health \
    --query DashboardBody --output text > checkout-health.json
  ```
- **Terraform**: the rendered `dashboard_body` of an `aws_cloudwatch_dashboard`, for example from `terraform state show`.
- **ARNscope**: open a dashboard from your account and click **Save a copy**; it is already local.

## Notices and warnings

### Importing

| Message | Meaning |
| --- | --- |
| *This file is not valid JSON.* | The file couldn't be parsed. |
| *This file is not a dashboard: expected a JSON object.* | The JSON is a list or a value, not an object. |
| *This file was made by a newer or unknown version of ARNscope (…).* | `arnscope` is not `dashboard/v1`. |
| *The dashboard body in this file is not valid JSON.* | `body` is a string that isn't JSON. |
| *This file has no dashboard body: expected a JSON object with a widgets list.* | `body` is missing or not an object. |
| *This dashboard has no widgets list.* / *The widgets in this dashboard are not a list.* | `widgets` is missing or not a list. |
| *This dashboard has N widgets; CloudWatch allows at most 500.* | Too many widgets. |
| *The file is larger than 1 MB* / *Pick at most 50 files at a time.* | Size limits. |
| *Widget 3 has no type and was skipped.* | Warning: the rest is imported. |
| *“…” does not look like an AWS region, so us-east-1 is used.* | Warning: the file's `region` is invalid; the page's region is used. |
| *2 widgets (log, explorer) are kept but only open in the CloudWatch console.* | Warning: these types aren't drawn (see Widgets). |
| *Skipped 1 of 3 files.* / *None of the 3 files could be imported.* | Followed by each file and its reason. |

### Resync and favourites

| Message | Meaning |
| --- | --- |
| *… is no longer where it was imported from (moved, renamed or deleted), so nothing was changed.* | Import it again from its new place. |
| *… could not be read as a dashboard, so nothing was changed: …* | The file now fails one of the import checks. |
| *… has no widgets now, so the dashboard was kept as it is.* | Resync won't empty a dashboard. |
| *“…” is no longer among my dashboards in …* | A favourite points at a local dashboard that was deleted. |
| *“…” is not among the dashboards in … It may have been deleted or renamed in AWS.* | A favourite points at a dashboard that is gone from the account. |
| *The AWS profile “…” is not in your AWS config, so “…” cannot be opened.* | The favourite's profile is no longer in `~/.aws`. |
| *That metric is no longer pinned to a widget.* | A macOS widget was tapped after its pin was removed. |

## Limitations

- A dashboard's absolute time range (a fixed `start` and `end`) is not used; pick a range from the presets.
- Pie and table views show each series' latest value as a number, not as a pie or a table.
- Only `yAxis.left` bounds and horizontal annotations are read; right-axis bounds, vertical annotations and other display options are kept in the JSON but not drawn.
- Logs Insights, explorer and custom widgets are not run or drawn, and links in text widgets can't be opened yet; both offer a copy instead.
- Layouts can be edited only for your own dashboards. Edit a dashboard in AWS by saving a copy, or in the console.
- Your dashboards are kept on this Mac only; export them to move them to another machine or to share them.

Need a widget type or option ARNscope doesn't draw yet? Write to [hello@arnscope.com](mailto:hello@arnscope.com) and tell us what your dashboards use.

## Permissions

| Action | Used for |
| --- | --- |
| `cloudwatch:ListDashboards` | The **In AWS** list |
| `cloudwatch:GetDashboard` | Opening a dashboard from AWS |
| `cloudwatch:GetMetricData` | Every metric chart and value |
| `cloudwatch:ListMetrics` | **Add widget** |
| `cloudwatch:DescribeAlarms` | Alarm widgets and the alarm picker |

Source: https://arnscope.com/docs/cloudwatch-dashboards
