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

Dashboard Body Structure and Syntax

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

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

An example of this structure with one simple 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-23

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 Dashboard Body Object: 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 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: Yes, when the widget type is metric and metrics is not specified.

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

Dashboard Body Object: 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 just specify "." 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 just specify "." 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 just specify "." 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 an 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.

label

The label to display for this metric in the graph legend. If this is not specifed, the metric is given an auto-generated 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

If you specify annotations for a metric widget, you can display one alarm threshold in that widget. If you specify an alarm in annotations, 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"] }

Dashboard Widget Object: yAxis Properties Format

Defines the minimum and maximum values for the Y-axis of the graph. You can do this within the widget object to affect all metrics in the widget, and also within each metric in the metrics array if you want to override the widget settings for that particular metric.

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