API でダッシュボードを作成して管理する

このドキュメントでは、Cloud Monitoring API の Dashboard リソースを使用して、カスタム ダッシュボードとそのダッシュボードのウィジェットを作成、管理する方法について説明します。以下の例は、curl を使用して API を呼び出すことでダッシュボードを管理する方法と、Google Cloud CLI を使用する方法を示しています。 Google Cloud コンソールを使用してカスタム ダッシュボードを管理することもできますが、API を使用すると、プログラムで複数のダッシュボードを同時に管理できます。

エンドポイントでは、ダッシュボードを管理および構成するための、次のメソッドがサポートされています。

API は、curl ユーティリティまたは Google Cloud CLI を使用して直接呼び出せます。

事前定義されたダッシュボードを取得、編集、削除することはできません。

ダッシュボードについて

ダッシュボードを作成するときは、表示するコンポーネント、またはウィジェットとそのウィジェットのレイアウトを指定する必要があります。ダッシュボードにラベルとフィルタを追加することもできます。ラベルは、ダッシュボードの検索や、ダッシュボード上のコンテンツの種類の表示に役立ちます。

ダッシュボードのレイアウト

レイアウトは、ダッシュボードのコンポーネントの順序を定義します。API では、次のレイアウトが提供されます。

  • GridLayout: 利用可能なスペースを等幅の縦の列に分割し、行優先戦略を使用してウィジェットのセットを配置します。

  • MosaicLayout: 利用可能なスペースをグリッドに分割します。各ウィジェットは 1 つ以上のグリッド ブロックを占有出来ます。

  • RowLayout: 利用可能なスペースを行に分割し、ウィジェットのセットを各行に水平に配置します。

  • ColumnLayout: 利用可能なスペースを縦の列に分割し、各列にウィジェットのセットを縦に並べます。

たとえば、3 つの Text ウィジェットを使用した RowLayout のダッシュボードの JSON 表現は以下のとおりです。

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

マイレポートのウィジェット

ウィジェットには 1 つのダッシュボード コンポーネントと、ダッシュボードにコンポーネントを表示する方法の構成が含まれています。ダッシュボードには複数のウィジェットを指定できます。Widget オブジェクトには複数のタイプがあります。

  • XyChart ウィジェットは、X 軸と Y 軸にデータを表示します。

    このウィジェットは、時系列データまたは SQL クエリによって生成されたデータセットを表示します。このウィジェットを使用すると、グラフに表示されるデータを左 Y 軸または右 Y 軸に関連付けることができます。複数の指標タイプをグラフ化する場合、両方の Y 軸を使用できます。XyChart ウィジェットは、次の表示スタイルをサポートしています。

    • 折れ線グラフ
    • 横棒グラフ
    • 積み上げ面グラフ
    • ヒートマップ

  • 最新の値など、1 つのディメンションから表示されるウィジェット:

    • PieChart: 時系列のコレクションの最新の値が表示されます。ここで、各時系列は円グラフに 1 つのスライスをもたらします。

    • Scorecard: 1 つの時系列の最新の値と、この値が 1 つ以上のしきい値とどのように関連するかを示します。

    • TimeSeriesTable: 各時系列の最新値または集計値が表示されます。テーブルはカスタマイズをサポートしています。たとえば、セルに色分けしたり、列名やデータの配置を構成したりできます。

  • アラート ポリシーまたはインシデント情報を表示するウィジェット:

    • AlertChart: 単一条件のアラート ポリシーの概要を表示します。このウィジェットでは、データを折れ線グラフとして表示し、しきい値を表示して、対応待ちのインシデントの数を一覧表示します。

    • IncidentList: インシデントのリストを表示します。特定のアラート ポリシーまたは特定のリソースタイプのインシデントを表示するようにウィジェットを構成できます。

  • ログエントリとエラーを表示するウィジェット:

  • テキスト ウィジェットと組織ウィジェット:

    • CollapsibleGroup: ウィジェットのコレクションを表示します。 グループのビューは折りたたむことができます。

    • SingleViewGroup: ウィジェットのコレクションに 1 つのウィジェットを表示します。表示するウィジェットを選択できます。

    • SectionHeader: ダッシュボードに横方向の分割線を作成し、ダッシュボードの目次にエントリを作成します。

    • Text: 生のテキスト文字列またはマークダウン文字列としてテキスト コンテンツを表示します。

    ダッシュボードにテキスト ウィジェットと組織ウィジェットを含めるには、ダッシュボードに MosaicLayout が必要です。

これらのオブジェクトに加えて、空白のプレースホルダをダッシュボードに追加することもできます。

たとえば、右の Y 軸が構成されている XyChart ウィジェットの JSON 表現は以下のとおりです。

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

ダッシュボード ラベル

ラベルは、ダッシュボードの管理と整理に役立ちます。たとえば、prod というラベルを追加して、ダッシュボードに本番環境リソースの時系列データとログデータを表示することを示します。または、ラベル playbook を追加して、ダッシュボードに障害のトラブルシューティングに役立つ情報が含まれていることを示します。

ダッシュボードにラベルを追加するのは任意です。

たとえば、次の図は、playbook という名前のラベルを指定する Dashboard オブジェクトを示しています。

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

上の例に示すように、labels フィールドは map として実装されます。ここで、key フィールドと value フィールドはどちらも文字列です。ダッシュボードにラベルを追加する場合は、key をラベル名に設定し、value フィールドを空の文字列に設定します。

ダッシュボード フィルタ

ダッシュボードを設計する際、ダッシュボードに表示するデータの表示方法を複数特定できる場合があります。たとえば、ダッシュボードに仮想マシン（VM）インスタンスの時系列データが表示されているとします。すべての VM の時系列データを表示することも、特定のゾーンにあるデータのみを表示することもできます。この状況では、永続フィルタを作成して、そのフィルタのデフォルト値を最もよく使用するビューに設定することをおすすめします。永続的なフィルタは、一部またはすべてのダッシュボード ウィジェットに適用できます。Google Cloud コンソールでダッシュボードを表示すると、ダッシュボード ツールバーに永続的なフィルタと、フィルタの値を一時的に変更するためのメニューが表示されます。

永続的なダッシュボード フィルタは、2 種類あります。

  • ダッシュボード全体のフィルタは、フィルタラベルをサポートし、そのラベルの値を指定しないダッシュボード上のすべてのウィジェットに適用されます。

    たとえば、グラフにフィルタ zone = us-central1-a が含まれている場合、そのグラフではラベル zone に基づくダッシュボード フィルタが無視されます。同様に、zone ラベルがないグラフでは、このラベルを含むダッシュボード フィルタが無視されます。

  • テンプレート変数は、特定のウィジェットに適用される名前付き変数です。 各変数は特定のラベルと値用です。テンプレート変数を適用するウィジェットを指定します。

すべてのフィルタタイプは、同じデータ構造で表されます。 詳細については、DashboardFilter をご覧ください。

たとえば、次の例では、テンプレート変数とダッシュボード全体のフィルタを定義するダッシュボードの JSON 表現の一部を示します。

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

表示された JSON で、dashboardFilters 構造の最初のエントリは、iid という名前のテンプレート変数と、ラベルキー zone を含むダッシュボード全体のフィルタ用です。テンプレート変数は、ラベル instance_id のエイリアスです。

テンプレート変数のデータ構造には、テンプレート変数を適用するウィジェットが記載されません。代わりに、ウィジェットのクエリを変更して、変数への参照を含むようにウィジェットをテンプレート変数に関連付けます。ウィジェットがダッシュボードに表示されると、テンプレート変数の値が解決されます。

ログパネルとグラフにアノテーションを付ける方法については、次のセクションをご覧ください。

ログパネル

テンプレート変数の値に基づいて表示をフィルタするようにログパネルを構成するには、変数をクエリペインに追加します。次の例は、テンプレート変数 iid の値でフィルタするクエリを示しています。

${iid}

ログパネルで表示するログをクエリする前に、テンプレート変数が解決されます。この例では、テンプレート変数の値が "12345" の場合、${iid} がステートメント resource.labels."instance_id"="12345" に置き換えられます。

テンプレート変数の値のみをクエリに含めることもできます。この値は、正規表現で定義されたフィルタの一部としてのみ使用することをおすすめします。たとえば、次のクエリでは正規表現を使用して、指定された文字列を含む JSON ペイロードを持つログエントリを照合します。

jsonPayload.message=~"Connected to instance: ${iid.value}"

ログパネルのクエリを構成してからボタンを選択してログ エクスプローラを開くと、ログ エクスプローラが開く前にテンプレート変数が解決されます。

次の表に、ログパネルでテンプレート変数が解決される方法を示します。

構文 選択された
値		 解決されたログパネル式
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

MQL 定義のグラフとテーブル

Monitoring Query Language（MQL）を使用してグラフを構成する場合は、クエリ文字列にパイプとその変数を追加します。

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}

グラフで表示する時系列をクエリする前に、テンプレート変数が解決されます。この例では、テンプレート変数の値が "12345" の場合、${iid} がステートメント filter (resource.instance_id == '12345') に置き換えられます。このフィルタは、resource.instance_id という名前のラベルを持つ時系列に一致し、ラベルの値が 12345 の場合にのみ一致します。

正規表現を使用して時系列をフィルタリングする場合は、テンプレート変数の値のみが含まれるようにクエリを構成します。構文の詳細を説明するために、正規表現を使用して、ラベル resource.instance_id の値にテンプレート変数 iid の値が含まれているかどうかを判別する方法を示します。

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

次の表に、MQL クエリでテンプレート変数が解決される方法を示します。

構文 選択された
値		 解決された MQL 式
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

PromQL 定義のグラフとテーブル

PromQL を使用してグラフを定義する場合は、クエリ文字列に中かっこで囲まれた変数を追加します。

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

グラフで表示する時系列をクエリする前に、テンプレート変数が解決されます。この例では、テンプレート変数の値が "12345" の場合、${iid} がステートメント instance_id == '12345' に置き換えられます。

MQL と同様に、PromQL でウィジェットを定義する場合、クエリはテンプレート変数の値のみを抽出できます。この値は、正規表現で定義されたフィルタの一部としてのみ使用することをおすすめします。構文の詳細を説明するために、正規表現を使用して、ラベル instance_id の値にテンプレート変数 iid の値が含まれているかどうかを判別する方法を示します。

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${iid.value}"
}

次の表に、PromQL クエリでテンプレート変数が解決される方法を示します。

構文 選択された
値		 解決された PromQL 式
${iid} 12345 instance_id == '12345'
${iid} * noop_filter=~".*"
${iid.value} 12345 12345
${iid.value} * .+

時系列フィルタで定義されたグラフとテーブル

時系列フィルタを使用してグラフを定義する場合は、その変数をフィルタ文字列に追加します。

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

MQL 定義のグラフや PromQL 定義のグラフとは異なり、テンプレート変数の値を時系列フィルタで使用することはできません。

次の表に、テンプレート変数の解決方法を示します。

構文 選択された
値		 解決されたフィルタ式
${iid} 12345 resource.instance_id == "12345"
${iid} * 除外
${iid.value} 12345 非対応
${iid.value} * 非対応

ダッシュボードを作成する

新しいカスタム ダッシュボードを作成するには、dashboards.create メソッドを呼び出し、それをレイアウトとウィジェットに指定してダッシュボードに表示します。

ダッシュボードを作成すると、API が自動的に dashboard_id を生成します。カスタム dashboard_id を指定する場合は、Dashboard オブジェクトの name フィールドを設定できます。名前フィールドの形式は次のようになります。

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

プロトコル

新しいダッシュボードを作成するには、POST リクエストをDashboard エンドポイントに送信します。

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

プロジェクトでダッシュボードを作成するには、gcloud monitoring dashboards create コマンドを使用します。

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

たとえば、ダッシュボードを複製するには、次の操作を行います。

  1. ダッシュボードを取得するの手順を完了して、元のダッシュボードの定義をダウンロードします。
  2. 返された JSON を編集して、etag フィールドと name フィールドを削除し、displayName フィールドの値を変更します。
  3. コマンドを実行してダッシュボードを作成します。

詳細については、gcloud monitoring dashboards create リファレンスをご覧ください。

この例では、my-dashboard.json ファイルを使用してサンプルのダッシュボードを作成します。 Google Cloud コンソールからダッシュボードを管理できるようになりました。

ダッシュボードのその他の構成については、ダッシュボードとレイアウトのサンプルをご覧ください。

ダッシュボードの削除

カスタム ダッシュボードを削除するには、dashboards.delete メソッドを呼び出して、削除するダッシュボードを指定します。

プロトコル

カスタム ダッシュボードを削除するには、削除するダッシュボードの ID で修飾された Dashboard エンドポイントに DELETE リクエストを送信します。

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

成功すると、このメソッドは空のレスポンスを返します。それ以外の場合は、エラーを返します。

gcloud

カスタム ダッシュボードを削除するには、gcloud monitoring dashboards delete を使用して、削除するダッシュボードの完全修飾 ID を指定します。

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

詳細については、gcloud monitoring dashboards delete リファレンスをご覧ください。

ダッシュボードの一覧表示

プロジェクトに属するすべてのカスタム ダッシュボードを一覧表示するには、dashboards.list メソッドを呼び出し、プロジェクト ID を指定します。

プロトコル

プロジェクトのすべてのカスタムダッシュボードを一覧表示するには、プロジェクト ID を Dashboard エンドポイントに送信します。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

プロジェクトのすべてのカスタム ダッシュボードを一覧表示するには、gcloud monitoring dashboards list コマンドを使用します。

gcloud monitoring dashboards list

詳細については、gcloud monitoring dashboards list リファレンスをご覧ください。

この例ではプロジェクトに関連付けられたカスタム ダッシュボードが返されます。

リスト レスポンスのページ分け

dashboards.list メソッドはページ分けをサポートしているので、すべての結果を一度にではなく、1 ページずつ結果を取得できます。

プロトコル

結果リストの最初のページで、リクエストに pageSize クエリ パラメータを指定します。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

メソッドは、リストの最初のページと nextPageToken を返します。次に例を示します。

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

残りの各ページには、リクエストに対応する nextPageToken を指定する必要があります。

gcloud

ページあたりのリソース数を指定するには、コマンドで --page-size フラグを渡します。次に例を示します。

gcloud monitoring dashboards list --page-size=1

ダッシュボードを取得する

プロジェクトの特定のカスタム ダッシュボードを取得するには、ダッシュボード ID で修飾された dashboards.get メソッドを呼び出します。

プロトコル

特定のカスタム ダッシュボードを取得するには、ダッシュボード ID を Dashboard エンドポイントに送信します。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

このメソッドは、次の例に類似したレスポンスを返します。

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

特定のカスタム ダッシュボードを取得するには、gcloud monitoring dashboards describe コマンドを使用してダッシュボード ID を指定します。

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

このコマンドにより、リクエストされたダッシュボードが返されます。

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

詳細については、gcloud monitoring dashboards describe リファレンスをご覧ください。

ダッシュボードの更新

既存のカスタム ダッシュボードを更新するには、dashboards.patch メソッドを呼び出します。現在の etag の値を取得するには、dashboards.get メソッドを呼び出すと、レスポンス内で確認できます。

プロトコル

カスタム ダッシュボードを更新するには、PATCH リクエストを Dashboard エンドポイントに送信し、修正した Dashboard オブジェクトと最新 dashboards.get レスポンスの etag 値を指定します。

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

gcloud

カスタム ダッシュボードを更新するには、gcloud monitoring dashboards update を使用して更新するダッシュボードの ID を指定し、ダッシュボードに変更を送信します。

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

詳細については、gcloud monitoring dashboards update リファレンスをご覧ください。

この例では、my-updated-dashboard.json ファイルを使用して既存のカスタム ダッシュボードを更新し、更新したダッシュボードの一覧のコピーを返します。返されるデータには、新しい etag 値が含まれます。

次のステップ