Menu
Amazon CloudWatch
API Reference (API Version 2010-08-01)

Dashboard Body Structure and Syntax

Overall Structure

A DashboardBody is a string in JSON format. It is an array of between 0 and 100 widget objects.

Copy
{ "widgets": [ {widget1},{widget2}, ... {widgetN} ] }

An example of this structure with one metric widget and one text widget:

Copy
{ "widgets":[ { "type":"metric", "x":0, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/EC2", "CPUUtilization", "InstanceId", "i-012345" ] ], "period":300, "stat":"Average", "region":"us-east-1", "title":"EC2 Instance CPU" } }, { "type":"text", "x":0, "y":7, "width":3, "height":3, "properties":{ "markdown":"Hello world" } } ] }

The rest of this section includes examples illustrating each part of the DashboardBody syntax. For more examples showing the entire command syntax, see PutDashboard in the Amazon CloudWatch API Reference.

Each widget of any type can have the following properties.

type

The type of widget.

Valid Values: metric | text

Type: String

Required: Yes

x

The horizontal position of the widget on the 24-column dashboard grid. The default is the next available position.

Valid Values: 0–23

Type: Integer

Required: No

y

The vertical position of the widget on the 24-column dashboard grid. The default is the next available position.

Valid Values: Any integer, 0 or higher.

Type: Integer

Required: No

width

The width of the widget in grid units (in a 24-column grid). The default is 6.

Valid Values: 1–24

Type: Integer

Required: No

height

The height of the widget in grid units. The default is 6.

Valid Values: 1–1000

Type: Integer

Required: No

properties

The detailed properties of the widget, which differ depending on the widget type. For more information about the format of properties, see Properties of a Metric Widget Object or Properties of a Text Widget Object.

Type: Object

Required: Yes

Properties of a Text Widget Object

A widget of type text must have exactly one properties field: markdown.

markdown

The text to be displayed by the widget. Use this parameter only for text widgets.

Type: String

Required: Yes (when the widget type is text).

Copy
{ "widgets": [ { "type: "text", "x": 0, "y": 7, "width": 3, "height": 3, "properties": { "markdown": "Hello world" }, }, ]

Properties of a Metric Widget Object

A widget of type metric can have the following fields within properties:

metrics

To include one or more metrics (without alarms) in the widget, specify a metrics array. One metrics array can include 0–100 metrics. Use this parameter only for metric widgets. For more information about the format of metrics, see Metric Widget: Format for Each Metric in the Array.

Type: Array of arrays

Required: Yes, when the widget type is metric and annotations is not specified..

annotations

To include an alarm or horizontal annotation in the widget, specify an annotations array. For more information about the format, see Dashboard Widget Object: Annotation Properties. Use this parameter only for metric widgets.

Type: Array

Required: An alarm annotation is required only when the widget type is metric and metrics is not specified. A horizontal annotation is not required.

title

The title to be displayed for the graph or number. Use this parameter only for metric widgets.

Type: String

Required: No

period

The default period, in seconds, for all metrics in this widget. This default can be overridden within each metric definition. Use this parameter only for metric widgets. The default is 300.

Valid Values: Any multiple of 60, with 60 as the minimum.

Type: Integer

Required: No

region

The region of the metric. Use this parameter only for metric widgets.

Type: String

Required: Yes

stat

The default statistic (such as Average, Maximum, and so on) to be displayed for each metric in the array. This default can be overridden within the definition of each individual metric in the metrics array. Use this parameter only for metric widgets.

Type: String that is a valid CloudWatch statistic.

Required: No

view

Specify timeSeries to display this metric as a graph, or singleValue to display it as a number. Use this parameter only for metric widgets.

Valid Values: timeSeries | singleValue

Type: String

Required: No

stacked

Specify true to display the graph as a stacked line, or false to display as separate lines. This parameter is ignored if view is singleValue. Use this parameter only for metric widgets.

Type: Boolean

Required: No

yAxis

Limits for the minimums and maximums of the y-axis, if this is a graph. This applies to every metric being graphed, unless specific metrics override it. For more information about the format, see Dashboard Widget Object: yAxis Properties Format.

Type: YAxes object

Required: No

Copy
{ "type":"metric", "x":0, "y":0, "width":12, "height":6, "properties":{ "metrics":[ [ "AWS/EC2", "CPUUtilization", "InstanceId", "i-012345" ], [ "AWS/EC2", "NetworkIn", "InstanceId", "i-012345", { "yAxis":"right", "label":"NetworkIn", "period":3600, "stat":"Maximum" } ] ], "period":300, "stat":"Average", "region":"us-east-1", "title":"EC2 Instance CPU", "stacked":true, "view":"singleValue", "yAxis":{ "left":{ "min":0, "max":100 }, "right":{ "min":50 } }, } }

Metric Widget: Format for Each Metric in the Array

Each metric in the metrics array has the following format:

Copy
[Namespace, MetricName, [{DimensionName,DimensionValue}...] [Rendering Properties Object] ]
Namespace

The AWS namespace containing the metric. If you have multiple entries in the metrics array, for each one after the first you may specify only "." to use the same namespace as the previous metric in the array.

Type: String

Required: Yes

MetricName

The name of the CloudWatch metric. If you have multiple entries in the metrics array, for each one after the first you may specify only "." to use the same metric name as the previous metric in the array.

Type: String

Required: Yes

DimensionName

The name of a dimension to further refine what data is shown. If you have multiple entries in the metrics array, for each one after the first you may specify only "." to use the same dimension name as in the corresponding dimension specified in the previous metric in the array. You may specify 0 dimensions for a metric, or up to as many dimensions as the metric support.

Type: String

Required: No

DimensionValue

The value to use for that dimension for the metric. Required if there is a corresponding dimension name.

Type: String

Required: No

Rendering Properties Object

Specifies rendering properties to be used for this particular metric, overriding the values specified for the overall widget. For more information about the format, see Dashboard Widget Object: Rendering Properties Object Format.

Type: Metric Render Properties Object

Required: No

Copy
// The simplest example, a metric with no dimensions [ "AWS/EC2", "CPUUtilization" ] // A metric with a single dimension [ "AWS/EC2", "CPUUtilization", "InstanceId", "i-012345" ] // A metric with a single dimension and rendering properties [ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-xyz", { yAxis: "right"} ] // The following example graphs the DiskReadBytes metric for three instances. [ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-xyz" ], [ ".", ".", ".", "i-abc" ], [ ".", ".", ".", "i-123" ]

Dashboard Widget Object: Rendering Properties Object Format

Each metric in the metrics array can optionally have custom rendering properties that override the default rendering properties specified in the yAxis parameter of the widget object. This section describes the format for those per-metric custom rendering properties.

color

The six-digit HTML hex color code to be used for this metric.

Type: String

Required: No

label

The label to display for this metric in the graph legend. If this is not specified, the metric is given an autogenerated label that distinguishes it from the other metrics in the widget.

Type: String

Required: No

period

The period for this metric, in seconds.

Valid Values: A multiple of 60, with a minimum of 60.

Type: Integer

Required: No

stat

The statistic for this metric, if it is to be different than the statistic used for the other metrics in the array.

Type: String

Required: No

yAxis

Where on the graph to display the y-axis for this metric. The default is left.

Valid Values: left | right

Type: String

Required: No

Copy
// The third metric has its own rendering properties, overriding those of the rest of the widget. [ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-xyz" ], [ ".", ".", ".", "i-abc" ], [ ".", ".", ".", "i-123", { "label":"Instance i-123", "yAxis": "right"} ]

Dashboard Widget Object: Annotation Properties

Annotations include alarms and horizontal annotations. A single metric widget can have up to one alarm, and multiple horizontal annotations.

Alarm Annotations

If you specify an alarm annotation, you cannot also specify a metrics array in the same widget.

alarms

The Amazon Resource Name (ARN) of the alarm.

Type: Array of strings. There can be 0–1 strings in the array.

Required: Only if no metrics are listed.

Copy
"annotations": { "alarms": [ "arn1"] }

Horizontal Annotations

horizontal

An array of horizontal annotations. Horizontal annotations have several options for fill shading, including shading above the annotation line, shading below the annotation line, and "band" shading that appears between two linked annotation lines as part of a single annotation. Each horizontal annotation in the array that does not have band shading has the following format:

Copy
[{value, label, color, fill, yAxis, visible}]

Each horizontal annotation that does have band shading has the following format:

Copy
{value, label, color, yAxis, visible}, {value, label}
value

The metric value in the graph where the horizontal annotation line is to appear. On a band shading annotation, the two values for Value define the upper and lower edges of the band.

On a graph with horizontal annotations, the graph is scaled so that all visible horizontal annotations appear on the graph.

Type: Float

Required: Yes

label

A string that appears on the graph next to the annotation.

Type: String

Required: No

color

The six-digit HTML hex color code to be used for the annotation. This color is used for both the annotation line and the fill shading.

Type: String

Required: No

fill

How to use fill shading with the annotation. Valid values are above for shading above the annotation, below for shading below the annotation, and none for no shading. If fill is omitted, there is no shading.

The exception is an annotation with band shading. These annotations always have shading between the two values, and any value for fill is ignored.

Type: String

Required: No

visible

Set this to true to have the annotation appear in the graph, or false to have it be hidden. The default is true.

Type: Boolean

Required: No

yAxis

If the graph includes multiple metrics, specifies whether the numbers in Value refer to the metric associated with the left Y-axis or the right Y-axis, . Valid values are right and left.

Type: String

Required: No

Copy
// A single horizontal annotation with fill shading above the annotation line, based on the metric associated with the right Y-axis "annotations": { "horizontal": [ { "visible":true, "color":"#9467bd", "label":"Critical range", "value":20, "fill":"above", "yAxis":"right" } ] } // A band annotation. Each value has a label, but other parameters for the band are specified only with the first number "annotations": { "horizontal": [ [ { "label":"Band top", "value":200, "color":"#9467bd", "visible":true, "yAxis":"right" }, { "value":95.5, "label":"Band bottom" } ] ] } // Three annotations on a graph. The first one is a band annotation. The final one is hidden. "annotations": { "horizontal": [ [ { "label":"Band top", "value":200 "color":"#9467bd" "visible":true, "yAxis":"right" }, { "value":95.5, "label":"Band bottom" } ], { "visible":true, "color":"#9467bd", "label":"Label for this annotation", "value":20, "fill":"below", "yAxis":"right" }, { "visible":false, "color":"#aaa", "label":"Hidden annotation", "value":150 } ] }

Dashboard Widget Object: yAxis Properties Format

Defines the minimum and maximum values for the Y-axis of the graph. Set this within the widget object to affect all metrics in the widget. To override the widget settings for a particular metric, set it for the metric in the metrics array.

Copy
{ left: { min: 0, max: 100 }, right: { min: 0 } }
left

Optional min and max settings for the left Y-axis.

Type: YAxis object

Required: No

right

Optional min and max settings for the right Y-axis.

Type: YAxis object

Required: No

Each of the left and right objects can include the following parameters:

min

The minimum value for this Y-axis

Type: Float

Required: No

max

The maximum value for this Y-axis

Type: Float

Required: No