ARNscopeDocs

CloudWatch dashboards

Last updated 13 November 2026

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 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

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

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

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 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:

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:

{
  "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

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

Need a widget type or option ARNscope doesn’t draw yet? Write to [email protected] 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