Widget reference

Widget types

Every CloudWatch metric widget view, plus text and alarm status widgets, becomes a native iOS widget, drawn in your dashboard's colours with its thresholds and axis limits.

When a list doesn't fit

• Bars: if adding the leftover bars up makes sense (currency, or counts and sums of the same metric), the last bar becomes a grey Other bar with their total. Otherwise you'll see “+N more”.
• Totals: a bar or pie widget shows a Total when the dashboard has one, such as the account-wide EstimatedCharges row or a SUM(METRICS()) expression. That row isn't drawn as a bar of its own. A currency widget with several bars totals them itself.
• Pie: every slice is drawn; the legend lists as many as fit, then “+N more”. If the total is bigger than the slices add up to, the difference is a grey Other slice.
• Legends on line and stacked area charts list two series on medium widgets and four on large ones, each with its latest value, then “+N more”.
• Tables show as many rows as fit and stop there.

Sizes

Every widget comes in every size. CloudPeek previews each one before you add it.

A bar widget with a Total row gives one of its slots on small and medium widgets to the Total. Line and stacked area legends list two entries on medium and four on large.

Lock Screen

Lock Screen widgets show one headline value, so you can read it without unlocking.

• Rectangular: the title, the value, and the series or bar it came from (or a warning if it's out of date).
• Circular: the value and a caption of about 8 characters from the title.
• Inline, above the clock: the value and the title, cut to whole words of about 18 characters.

Dashboard settings CloudPeek uses

CloudPeek reads the dashboard's JSON and queries it the way the CloudWatch console does.

Supported

• Metrics: metric rows with the "." and "..." shorthands; metric math, SEARCH and Metrics Insights (SELECT … FROM SCHEMA(…)) expressions; "visible": false for inputs that shouldn't be drawn.
• Per metric: id, label (including dynamic labels such as ${PROP('Dim.ServiceName')} and ${LAST}), color, stat, period, region, accountId and yAxis.
• Per widget: title, view, stacked, stat (Average if not set), period, region, accountId, start, end, setPeriodToTimeRange, sparkline, trend, y-axis min and max on either side, horizontal annotations (value, colour, axis, and visible), and "legend": {"position": "hidden"}.
• Right y-axis: metrics with "yAxis": "right" are drawn on their own scale, labelled on the right.
• Per dashboard: start, end and periodOverride.
• Alarm widgets: alarms and sortBy.

Not used

• Annotation labels and y-axis labels (the lines and limits are drawn, without their text), annotation bands (only their first edge is drawn), and vertical annotations.
• Legend positions other than hidden, liveData, singleValueFullPrecision and table summary options.
• Dashboard variables: widgets use the values saved in the dashboard.

Time range and period

• Time range: the widget's start if it has one, otherwise the dashboard's, otherwise the last 3 hours. Relative ranges such as -PT3H or -P7D and absolute timestamps both work. Every widget shows the window it covers, such as “Last 3 hours”.
• Period: the metric's period, otherwise the widget's, otherwise 5 minutes. Like the console, CloudPeek raises it when the range would need too many points (more than 300, or 1,440 with "periodOverride": "inherit"), stepping through 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, 1 day, 1 week and 30 days.
• Older data has a coarser resolution in CloudWatch, so ranges starting more than 15 days ago use at least 5-minute periods, and more than 63 days ago at least 1-hour periods.
• setPeriodToTimeRange makes number, gauge, bar, pie and table widgets use one period for the whole range, as in the console.

How values are shown

• Numbers have three significant figures, with K, M, B and T for thousands, millions, billions and trillions: 1.23K, 45.6M. CloudWatch units aren't shown, so put the unit in the label, such as “Latency (s)”.
• Currency: when every metric on a widget is AWS/Billing EstimatedCharges in the same currency, values are shown as money: with cents under 100, whole amounts up to 10,000, then compact, such as $12.3K.
• Service names on billing widgets are shortened: AmazonEC2 becomes EC2 and AWSLambda becomes Lambda.
• Labels: a metric without a label is named after the metric, or after the dimension values that tell it apart from the others on the widget.
• Trends on numbers compare the latest data point with the one before.
• Colours: your color on each metric, otherwise CloudWatch's default palette.

Refreshing and freshness

• Widgets refresh every 30 minutes by default. In Settings you can choose 15 minutes, 30 minutes, 1, 2 or 6 hours. iOS decides exactly when, so treat it as a guide.
• They also refresh whenever you open the app, and when you tap a widget's refresh button.
• After a network or AWS hiccup, a widget tries again within 10 minutes.
• Data loaded in the last five minutes, by the app or by another widget, is reused rather than fetched and billed again, unless you've tapped refresh or a refresh has failed since.
• If a refresh fails, the widget keeps its last data and says why and how old it is, such as “Sign-in expired · data from Fri 14:05”. Data more than a day old fades, so it can't pass for current.

Each refresh makes one GetMetricData call per region on the widget, which AWS bills at $0.01 per 1,000 metrics, plus a GetDashboard call to pick up your edits. A 5-metric widget refreshing every 30 minutes costs about 7 cents a month. Alarm widgets use DescribeAlarms instead. See CloudWatch pricing.

Accounts, regions and limits

• Regions: each metric uses its own region, then the widget's, then the account's default region in CloudPeek. One widget can mix regions; CloudPeek queries each in parallel.
• Accounts: each pinned widget refreshes with the account it was pinned from. To show another account's metrics on one widget, use accountId on the metric with CloudWatch cross-account observability, or add that account to CloudPeek and pin from its own dashboards.
• Alarms are looked up in the account the widget was pinned from, in each ARN's region.
• Size: a widget can request up to 500 metrics per region at once, and keeps up to 400 points per line.

Text widgets

Text widgets are handy for a runbook note next to the graphs. CloudPeek shows:

• Bold, italic, code and links.
• Headings, as bold lines.
• Bulleted lists (*, - or +), as bullets.
• CloudWatch's buttons, [button:Label](https://…), as plain links.

Horizontal rules are left out, and runs of blank lines are closed up. Tables, images and code blocks are better kept to the dashboard in the console. A text widget without a title is named after its first line.