ダッシュボード本体の構造と構文

全体的な構造

DashboardBody は JSON 形式の文字列です。これには、0～500 個のウィジェットオブジェクトの配列と、他のいくつかのパラメータを含めることができます。ダッシュボードには widgets 配列を含める必要がありますが、その配列は空にすることができます。

以下はこの構造の例であり、1 つのメトリクスウィジェットと 1 つのテキストウィジェット、現在の時刻の 6 時間前から始まる時間範囲、各グラフの期間設定が常に準拠しています。

{
   "start": "-PT6H",
   "periodOverride": "inherit",
   "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",
            "liveData": false,
            "legend": {
                "position": "right"
              }
         }
      },
      {
         "type":"text",
         "x":0,
         "y":7,
         "width":3,
         "height":3,
         "properties":{
            "markdown":"Hello world"
         }
      }
   ]
}

次の例では、関数ごとの 3 つの Lambda メトリクスを表示し、ダッシュボード変数を使用して、ダッシュボードユーザーが異なる Lambda 関数名を切り替えて各関数の 3 つのメトリクスをすべて表示できるようにしています。これにより、さまざまなリソースの主要なメトリクスを表示できる単一の柔軟なダッシュボードを作成できます。この例では、関数はメトリクス検索クエリによって検出されるため、ダッシュボードは作成時に新しい Lambda 関数を自動的に検出します。

{
    "widgets": [{
            "height": 6,
            "width": 6,
            "y": 0,
            "x": 0,
            "type": "metric",
            "properties": {
                "view": "timeSeries",
                "stacked": false,
                "metrics": ["AWS/Lambda", "Invocations", "FunctionName", "my-function-name"],

                "region": "us-east-1",
                "liveData": true
            }
        },
        {
            "height": 12,
            "width": 12,
            "y": 0,
            "x": 6,
            "type": "metric",
            "properties": {
                "view": "timeSeries",
                "stacked": false,
                "metrics": ["AWS/Lambda", "Errors", "FunctionName", "my-function-name"],

                "region": "us-east-1",
                "liveData": true
            }
        },

        {
            "height": 3,
            "width": 6,
            "y": 0,
            "x": 18,
            "type": "metric",
            "properties": {
                "view": "timeSeries",
                "stacked": false,
                "metrics": ["AWS/Lambda", "Duration", "FunctionName", "my-function-name"],

                "region": "us-east-1",
                "liveData": true
            }
        }
    ],
    "variables": [{
        "type": "property",
        "property": "FunctionName",
        "inputType": "select",
        "id": "LambdaFunction_Variable",
        "label": "Function",
        "visible": true,
        "search": "{AWS/Lambda,FunctionName} MetricName=\"Duration\"",
        "populateFrom": "FunctionName"
    }]
}

次の例には 2 つのウィジェットがあります。最初のウィジェットには、2 つのメトリクスと、合計を計算する数式が含まれています。2 番目のウィジェットは、リージョン内のすべての EC2 インスタンスの CPUUtilization を表示する検索式です。

{
   "start": "-PT9H",
   "periodOverride": "inherit",
   "widgets": [
      {
         "type":"metric",
         "x":0,
         "y":0,
         "width":12,
         "height":6,
         "properties":{
            "metrics":[
               [ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-123",{ "id": "m1" } ],
               [ ".", ".", ".", "i-abc", { "id": "m2" } ],
               [ { "expression": "SUM(METRICS())", "label": "Sum of DiskReadbytes", "id": "e3" } ]
            ],
            "view": "timeSeries",
            "stacked": false,
            "period":300,
            "stat":"Average",
            "region":"us-east-1",
            "title":"EC2 Instance CPU"
         }
      },
      {
         "type":"metric",
         "x":0,
         "y":0,
         "width":18,
         "height":9,
         "properties":{
            "metrics":[
               [ { "expression": "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)", "id": "e1" } ]
            ],
            "view": "timeSeries",
            "stacked": false,
            "region":"us-east-1",
            "title":"EC2 Instance CPU"
         }
      }
   ]
}
    

このセクションの残りの部分には、DashboardBody 構文の各部分を示す例が含まれています。コマンド構文全体を示すその他の例については、Amazon CloudWatch API リファレンス」の「PutDashboard」を参照してください。

JSON オブジェクトの最上位レベルには、次のプロパティを含めることができます。

ウィジェット配列構造

どのタイプのウィジェットでも、それぞれに以下のプロパティを含めることができます。

変数配列構造

配列内の各ダッシュボード変数には、次のプロパティを含めることができます。

変数の例

次の例では、プロパティ変数を使用し、テキスト入力フィールドを使用してすべてのウィジェットのリージョンを変更します。ダッシュボードを最初に開くと、変数に us-east-1 のデフォルト値が使用されます。

"variables": [
     {
        "type": "property", 
        "property": "region",
        "inputType": "input",
        "id": "region",
        "label": "Region",
        "defaultValue": "us-east-1",
        "visible": true
    } 
],

次の例では、ARN などの文字列の途中でリージョンが設定されている場合に備え、パターン変数を使用してすべてのウィジェットのリージョンを変更します。

"variables": [
    {
        "type": "pattern",
        "pattern": "us-east-1",
        "inputType": "input",
        "id": "region",
        "label": "Region",
        "defaultValue": "us-east-1",
        "visible": true
    }
],

次の例では、関数ごとにラジオボタンが付いた Lambda 関数変数を生成します。関数は、メトリクスクエリ検索によって検出されます。

"variables": [
    {
        "type": "pattern",
        "pattern": "originalFuncNameInDashboard",
        "inputType": "radio",
        "id": "functionName",
        "label": "Function",
        "visible": true,
        "search": "{AWS/Lambda,FunctionName} MetricName=\"Duration\"",
        "populateFrom": "FunctionName",
        "defaultValue": "__FIRST"
    }
],

次のサンプルは、ダッシュボードで複数の変数を指定する方法と、いくつかのタイプの変数を示しています。

"variables": [{
        "type": "property",
        "property": "region",
        "inputType": "select",
        "id": "unique_id_1",
        "label": "Region",
        "defaultValue": "us-east-1",
        "visible": true,
        "values": [{
                "label": "IAD",
                "value": "us-east-1"
            },
            {
                "label": "CMH",
                "value": "us-east-2"
            },
            {
                "label": "NRT",
                "value": "ap-northeast-1"
            }
        ]
    },
    {
        "type": "property",
        "property": "FunctionName",
        "inputType": "select",
        "id": "unique_id_2",
        "label": "Function",
        "visible": true,
        "values": [{
                "value": "my-FunctionName-1"
            },
            {
                "value": "my-FunctionName-2"
            },
            {
                "value": "my-FunctionName-3"
            }
        ]
    },
    {
        "type": "property",
        "property": "accountId",
        "inputType": "radio",
        "id": "unique_id_3",
        "defaultValue": "111122223333",
        "visible": true,
        "values": [{
                "label": "IAD Account",
                "value": "111122223333"
            },
            {
                "label": "CMH Account",
                "value": "123456789012"
            },
            {
                "label": "NRT Account",
                "value": "000000000000"
            }
        ]
    }
]

テキストウィジェットオブジェクトのプロパティ

タイプ text のウィジェットには、properties セクションに 1 つまたは 2 つのパラメータを含めることができます。markdown フィールドは必須であり、transparent フィールドはオプションです。

CloudWatch テキストウィジェットでサポートされているマークダウンのスタイルの詳細については、「コンソールでのマークダウンの使用」を参照してください。

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

ログウィジェットオブジェクトのプロパティ

タイプ log のウィジェットは、CloudWatch Logs Insights クエリの結果を表します。詳細については、Analyzing Log Data with CloudWatch Logs Insights を参照してください。

log ウィジェットの properties フィールドには、次のフィールドを含めることができます。

{
    "widgets": [
        {
            "type": "log",
            "x": 12,
            "y": 24,
            "width": 12,
            "height": 6,
            "properties": {
                "region": "us-east-1",
                "title": "Errors (Application Log)",
                "query": "SOURCE 'application1.log' | SOURCE 'application2.log' | filter @message like \"[ERROR]\"\n| parse \"Error for [*] [*] due to: *\" canaryName1, canaryId1, cause1\n| parse \"Executor canary [*] *\" canaryName2, cause2\n| fields coalesce(cause1, cause2) as cause\n| fields coalesce(canaryName1, canaryName2) as canaryName\n| fields ispresent(cause) as isP\n| filter isP\n| stats count() as errCount by canaryName, substr(cause, 0, 130)\n| sort errCount DESC",
                "view": "table"
            }
        }
    ]
}

メトリクスウィジェットオブジェクトのプロパティ

タイプ metric のウィジェットには、properties 内に次のフィールドを含めることができます。

例: 積み上げ領域ウィジェットとゲージウィジェット

{
    "widgets": [
{
   "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",
      "timezone":"+0300",
      "title":"EC2 Instance CPU",
      "stacked":true,
      "view":"timeSeries",
      "liveData":false,
      "yAxis":{
         "left":{
            "min":0,
            "max":100
         },
         "right":{
            "min":50
         }
      },
      "annotations":{
         "horizontal":[
            {
               "visible":true,
               "color":"#9467bd",
               "label":"Critical range",
               "value":20,
               "fill":"above",
               "yAxis":"right"
            }
         ]
      }
   },
{
   "type": metric, 
   "x": 18,
   "y"; 60,
   "width": 6, 
   "height": 6,
   "properties": {
      "metrics": [
         [ 
         "AWSLogsShrinkRay",
         "disk_inodes_used",
         "path", 
         "/dev/shm",
         "InstanceId",
         "i-012345",
         "AutoScalingGroupName",
         "ShrinkRayExecutorResourceStack-Gamma-us-east-1-ASGuseast1ac48xlargeASGB9B53974-VTYXJUZGUAHV",
         "InstanceType",
         "c4.8xlarge",
         "device",
         "tmpfs",
         "fstype",
         "tmpfs" 
         ]
         ],
      "view": "gauge", 
      "title": "Disk Inodes Used"
      "region": "us-east-1",
      "yAxis": {
         "left": {
            "min": 0, 
            "max": 100,
         }        
       }
     }
   }

メトリクスウィジェット: 配列内の各メトリクスの形式

metrics 配列内の各項目は、単一のメトリクス、数式、検索式のいずれかです。metrics 配列内のメトリクスのそれぞれの形式は以下のとおりです。

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

metrics 配列の各式の形式は以下のとおりです。

[ {"expression" : "expression", ["label" : "label"] , ["id" : "id"] } ]

// 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" ]
       
 // The following example includes two metrics and a math expression to sum them.
        [ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-123",{ "id": "m1" } ],
        [ ".", ".", ".", "i-abc", { "id": "m2" } ],
        [ { "expression": "SUM(METRICS())", "label": "Sum of DiskReadbytes", "id": "e3" } ]
       
  // The following example is a search expression showing the EC2 CPUUtilization for each instance in the Region.
        [ { "expression": "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)", "id": "e1" } ],

ダッシュボードウィジェットオブジェクト: レンダリングプロパティオブジェクト形式

metrics 配列内の各メトリクスは、オプションで、widget オブジェクトの yAxis パラメータで指定されたデフォルトのレンダリングプロパティを上書きするカスタムレンダリングプロパティを持つことができます。このセクションでは、メトリクスごとのカスタムレンダリングプロパティの形式について説明します。

       
 // 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"}  ]

ダッシュボードウィジェットオブジェクト: 注釈プロパティ

注釈には、アラーム、水平注釈、垂直注釈が含まれます。1 つのメトリクスウィジェットに最大 1 つのアラームを含めることも、1 つ以上の水平注釈または垂直注釈を含めることもできます。1 つのウィジェットにアラームと水平注釈または垂直注釈の両方を含めることはできません。

アラーム注釈

アラーム注釈を指定した場合、同じウィジェットで metrics 配列を指定することもできません。

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

水平注釈

// 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
        }
    ]
}

垂直注釈

// A single vertical annotation with fill shading after the annotation line
                    
"annotations": {
    "vertical": [
        {
            "visible": true,
            "color": "#9467bd",
            "label": "Bug fix deployed",
            "value": "2018-08-28T15:25:26Z",
            "fill": "after"
        }
    ]
}	


// A band vertical annotation. Each annotation line has a label, but other parameters for the band are specified only with the first value

"annotations": {
    "vertical": [
        [
            {
                "label": "Band start",
                "value": "2018-08-27T15:25:26Z",
                "color": "#9467bd",
                "visible": true
            },
            {
                "value": "2018-08-28T15:25:26Z",
                "label": "Band end"
            }
        ]
    ]
}

ダッシュボードウィジェットオブジェクト: yAxis プロパティ形式

グラフの Y 軸の設定を定義します。設定には、最大値と最小値、軸のラベル、軸に単位を表示するかどうかが含まれます。widget オブジェクト内でこれを設定すると、ウィジェット内のすべてのメトリクスに影響します。特定のメトリクスのウィジェット設定を上書きするには、metrics 配列内のメトリクスに設定します。

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

left および right オブジェクトのそれぞれに次のパラメータを含めることができます。

ダッシュボードウィジェットオブジェクト: テーブルプロパティ

メトリクスウィジェットに table を指定した場合、集計列、データポイント列、テーブルレイアウトの可視性に関連する視覚化を含めることができます。これらのプロパティは、ウィジェットビュータイプが table の場合にのみ有効になり、含まれている場合は他のビュータイプを変更しません。テーブルウィジェットを使用する場合、table プロパティは必須ではありません。

たとえば、次の JSON は、テーブル内の各メトリクスの最小値と最大値を表示するテーブルを作成します。

"table": {
    "summaryColumns": ["MIN", "MAX"],
    "layout": "vertical",
    "stickySummary": true,
    "showTimeSeriesData": false,
    },

メトリクスエクスプローラーウィジェットオブジェクトのプロパティ

タイプ explorer のウィジェットは、メトリクスエクスプローラーウィジェットを表します。詳細については、「メトリクスエクスプローラーを使用して、タグとプロパティ別にリソースをモニタリングする」を参照してください。

CloudFormation を使用してダッシュボードにメトリクスエクスプローラーウィジェットを追加することもできます。詳細については、「AWS::CloudWatch::Dashboard」を参照してください。

このウィジェットタイプには、ウィジェット properties 内に次のフィールドを含めることができます。

例

次の例では、アカウントの実行中の EC2 インスタンスごとに 3 つのメトリクスを表示し、ウィジェット内のグラフをアベイラビリティーゾーンで分割します。各グラフ内では、メトリクスはインスタンスタイプ別に集計されます。

{
    "widgets": [
        {
            "type": "explorer",
            "width": 24,
            "height": 15,
            "x": 0,
            "y": 0,
            "properties": {
                "metrics": [
                    {
                        "metricName": "CPUUtilization",
                        "resourceType": "AWS::EC2::Instance",
                        "stat": "Average"
                    },
                    {
                        "metricName": "NetworkIn",
                        "resourceType": "AWS::EC2::Instance",
                        "stat": "Average"
                    },
                    {
                        "metricName": "NetworkOut",
                        "resourceType": "AWS::EC2::Instance",
                        "stat": "Average"
                    }
                ],
                "aggregateBy": {
                    "key": "InstanceType",
                    "func": "MAX"
                },
                "labels": [
                    {
                        "key": "State",
                        "value": "running"
                    }
                ],
                "widgetOptions": {
                    "legend": {
                        "position": "bottom"
                    },
                    "view": "timeSeries",
                    "rowsPerPage": 8,
                    "widgetsPerRow": 2
                },
                "period": 300,
                "splitBy": "AvailabilityZone",
                "title": "Running EC2 Instances by AZ"
            }
        }
    ]
}

メトリクスエクスプローラーウィジェットオブジェクトの有効な resourceType 値

メトリクスエクスプローラーウィジェットの metrics セクションの resourceType フィールドの有効な値は次のとおりです。

アラームステータスウィジェットオブジェクトのプロパティ

タイプ alarm のウィジェットには、properties 内に次のフィールドを含めることができます。

次の例は、現在の状態に関係なく、名前で指定された 4 つのアラームを表示するアラームステータスウィジェットです。

{
    "type": "alarm",
    "x": 0,
    "y": 0,
    "width": 12,
    "height": 6,
    "properties": {
        "alarms": [
            "arn:aws:cloudwatch:us-east-1:012345678901:alarm:EC2FrontendCPU",
            "arn:aws:cloudwatch:us-east-1:012345678901:alarm:EC2BackendCPU",
            "arn:aws:cloudwatch:eu-west-1:987654321098:alarm:EC2FrontendCPU",
            "arn:aws:cloudwatch:eu-west-1:987654321098:alarm:EC2BackendCPU"
        ],
        "sortBy": "stateUpdatedTimestamp",
        "title": "All EC2 CPU alarms"
    }
}

次のウィジェットの例では、同じ 4 つのアラームを指定しますが、ウィジェットには、現在 ALARM または INSUFFICIENT_DATA 状態にあるアラームのみが表示されます。

{
    "type": "alarm",
    "x": 0,
    "y": 0,
    "width": 12,
    "height": 6,
    "properties": {
        "alarms": [
            "arn:aws:cloudwatch:us-east-1:012345678901:alarm:EC2FrontendCPU",
            "arn:aws:cloudwatch:us-east-1:012345678901:alarm:EC2BackendCPU",
            "arn:aws:cloudwatch:eu-west-1:987654321098:alarm:EC2FrontendCPU",
            "arn:aws:cloudwatch:eu-west-1:987654321098:alarm:EC2BackendCPU"
        ],
        "sortBy": "stateUpdatedTimestamp",
        "states": [
            "ALARM",
            "INSUFFICIENT_DATA"
        ],
        "title": "EC2 alarms that are not currently OK"
    }
}