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 軸を使用してデータを表示します。 次のグラフは、XyChart ウィジェットのインスタンスです。

    • 折れ線グラフ

    • 横棒グラフ

    • 積み上げ面グラフ

    • ヒートマップ

    • ログ分析グラフ

    • SLO ウィジェット（ただし、API を使用した SLO グラフの作成はサポートされていません）。

    折れ線グラフ、積み上げ棒グラフ、積み上げ面グラフを作成する場合は、指標が左右の Y 軸を参照するように指定できます。複数の指標をグラフ化する場合、両方の Y 軸を使用できます。

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

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

    • TimeSeriesTable: 指標の最新値を表示します。列に基づいてテーブルを並べ替え、テーブルをフィルタし、表示する列を追加または削除できます。

  • アラートグラフとインシデント ウィジェット:

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

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

  • ログウィジェットとエラー ウィジェット:

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

    これらのウィジェットをダッシュボードに含めるには、ダッシュボードに MosaicLayout が必要です。

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

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

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

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

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

たとえば、右の 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"
          }
        }
      }
    ]
  }
}

ダッシュボード フィルタ

ダッシュボードを設計する際、ダッシュボードに表示するデータの表示方法を複数特定できる場合があります。たとえば、ダッシュボードに仮想マシン（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 値が含まれます。

次のステップ