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

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

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

• dashboards.create: ダッシュボードを作成します
• dashboards.delete: 指定したダッシュボードを削除します
• dashboards.list: 任意のプロジェクト内のすべてのダッシュボードのリストを取得します
• dashboards.get: 指定したダッシュボードを取得します
• dashboards.patch: 指定したダッシュボードの構造を更新します

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

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

この機能は Google Cloud プロジェクトでのみサポートされています。

ダッシュボードについて

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

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

レイアウトは、ダッシュボードのコンポーネントの順序を定義します。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: インシデントのリストを表示します。特定のアラート ポリシーまたは特定のリソースタイプのインシデントを表示するようにウィジェットを構成できます。

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

  • ErrorReportingPanel: 選択した Google Cloud プロジェクトに保存されているエラーグループが表示されます。

  • LogsPanel: 現在の Google Cloud プロジェクトに保存されているプロジェクト スコープのログエントリを表示します。現在の指標スコープを介してアクセス可能な Google Cloud プロジェクトに格納されているログエントリを表示するようにウィジェットを構成できます。

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

  • 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 フィールドを空の文字列に設定します。

注: Dashboard.labels オブジェクトでは、key フィールドのみが処理されます。value フィールドは無視されます。

ダッシュボードのフィルタと変数

ダッシュボードを設計する際、ダッシュボードに表示するデータの表示方法を複数特定できる場合があります。たとえば、ダッシュボードに仮想マシン（VM）インスタンスの時系列データが表示されているとします。すべての VM の時系列データを表示することも、特定のゾーンにあるデータのみを表示することもできます。この場合は、固定フィルタまたは変数を作成して、そのフィルタのデフォルト値を最もよく表示されるゾーンに設定することをおすすめします。

固定フィルタは、フィルタで指定されたラベルをサポートするすべてのダッシュボード ウィジェットに適用されます（ウィジェットに同じラベルキーを持つフィルタが含まれている場合を除く）。たとえば、グラフにフィルタ zone = us-central1-a が含まれている場合、そのグラフではラベルキーが zone の固定フィルタは無視されます。同様に、キーが zone のラベルがないグラフでは、このフィルタは無視されます。

変数は固定フィルタに似ていますが、特定のウィジェットにのみ適用されます。変数は、固定されたフィルタのようにラベルに基づくものもあれば、値のみを持つものもあります。値のみの変数には、1 つ以上のデフォルト値と、使用可能なすべての値のリストが含まれます。デフォルト値を指定しない場合、デフォルトはワイルドカード演算子 (*) に設定されます。すべての有効な値のセットを定義するには、値の配列を指定する方法と、SQL クエリを作成する方法があります。

データをクエリするウィジェットの場合、ウィジェットのクエリに変数を含めることができ、変数を使用してウィジェットの表示を制御できます。クエリが変数に依存している場合、変数の値を変更すると、ウィジェットがリクエストするデータが変更されます。その結果、表示されるデータも変更されます。変数を使用してウィジェットの表示を制御すると、ツールバーに 表示中アイコンが表示されます。公開設定に関連する制限については、ウィジェットの公開設定を設定するをご覧ください。

固定したフィルタと変数の両方について、ダッシュボード ツールバーには各変数と、変数の値を一時的に変更できるメニューが表示されます。固定されたフィルタと変数を表すために、同じデータ構造が使用されます。フィルタと変数を区別できるように、ダッシュボード ツールバーでは、変数名の前にドル記号 $ が付いています。詳細については、DashboardFilter をご覧ください。

変数を使用してウィジェットの表示を制御する方法の例については、ウィジェットの表示が構成されたダッシュボードをご覧ください。

ラベルベースの変数または値のみの変数を使用してウィジェットのクエリを更新する方法については、次のセクションをご覧ください。

• 変数の参照を解除する一般的な構文
• ログパネル ウィジェット
• PromQL クエリを使用したグラフ
• SQL クエリを使用したグラフ
• MQL クエリを使用したグラフ

• Monitoring フィルタクエリを使用したグラフ

  メニュー ドリブンのインターフェースを使用して時系列データを表示するグラフを作成するときに、選択内容はモニタリング フィルタに変換されます。

フィルタと変数を作成する

ConsoleAPI

Google Cloud コンソールを使用して固定されたフィルタと変数を作成する方法については、次のドキュメントをご覧ください。

• フィルタを作成して固定する
• 変数を作成する

固定されたフィルタと変数を定義するには、dashboardFilters データ構造を使用します。

• 変数を作成するには、templateVariable フィールドの値を変数の名前に設定します。固定されたフィルタを作成する場合は、このフィールドを省略するか、値を空の文字列に設定します。
• 固定フィルタまたはラベルベースの変数を作成するには、labelKey フィールドを指定する必要があります。値のみの変数を使用する場合は、このフィールドを省略します。

• フィルタまたは変数のデフォルト値を設定します。このフィールドの設定によって、ユーザーが値のメニューから 1 つのオプションのみを選択できるか、複数の値を選択できるかが決まります。

  • 1 つのデフォルト値を設定し、ユーザーが値メニューで 1 つのオプションのみを選択できるようにするには、valueType フィールドを STRING として設定し、stringValue フィールドも設定します。

  "valueType": "STRING",
  "stringValue": "my-default-value",
  

  • 少なくとも 1 つのデフォルト値を設定し、ユーザーが値メニューで複数のオプションを選択できるようにするには、valueType フィールドを STRING_ARRAY として設定し、stringArrayValue フィールドも設定します。次の例では、3 つのデフォルト値があります。

  "valueType": "STRING_ARRAY",
  "stringArrayValue": {
    "values": [ "a", "b", "c" ]
  },
  

  注: デフォルト値を指定しない場合、ワイルドカード演算子 (*) が自動的に選択されます。ログパネルで変数を使用する場合は、正規表現を比較条件として使用する必要があります。SQL クエリの場合は、IF ステートメントを使用する必要があります。詳細については、SQL クエリを使用したグラフをご覧ください。

• 省略可: 値のみの変数で使用可能なすべての値のリストを指定するには、stringArray フィールドまたは timeSeriesQuery フィールドを設定します。クエリを指定する場合は、分析クエリにする必要があります。

  注: 固定フィルタまたはラベルベースの変数を作成するときに、timeSeriesQuery フィールドまたは stringArray フィールドを設定しないでください。使用可能なすべての値のセットは動的に決定されます。

たとえば、次の dashboardFilters オブジェクトについて考えてみましょう。

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

上記の JSON では、1 つの固定フィルタと 2 つの変数を定義しています。

• 固定されたフィルタのラベルキーは zone で、ツールバーに表示されます。valueType フィールドと stringValue フィールドには、単一のデフォルト値を指定します。詳細については、dashboardFilters データ構造の API リファレンス ページをご覧ください。

• ラベルベースの変数の名前は my_label_based_variable で、ラベルキーは instance_id です。この変数のデフォルト値は、特定のインスタンス ID に設定されています。配列を使用してデフォルト値を構成することもできます。ツールバーには、フィルタ名 my_label_based_variable が表示されます。

• 値のみの変数の名前は my_value_only_variable です。このエントリにはデフォルト値が指定されていないため、ワイルドカード演算子 (*) が自動的に適用されます。また、この変数は SQL クエリを使用して、変数の有効な値のリストを生成します。

dashboardFilters オブジェクトには、変数が適用されるウィジェットはリストされません。代わりに、変数に依存するようにウィジェットのクエリを更新します。

変数の参照を解除する一般的な構文

SQL で定義されているウィジェットを除くすべてのウィジェットでは、次の構文を使用して変数をクエリに適用します。

• ラベルベースの変数を適用し、ラベルキーとラベル値をクエリ言語の有効なフィルタ式に解決するには、${my_label_based_variable} を使用します。

• ラベルベースの変数の値のみを適用するには、${my_label_based_variable.value} を使用します。比較には正規表現を使用する必要があります。

• 値のみの変数の値のみを適用するには、${my_value_only_variable} を使用します。値のみの変数の場合は、.value 句を含めないでください。比較には正規表現を使用する必要があります。

ログパネル ウィジェット

ログパネル ウィジェットに変数を適用するには、クエリペインを更新します。これらのウィジェットの構文は、一般的な構文で指定されている構文に従います。

ConsoleAPI

たとえば、次のクエリでは正規表現を使用して、jsonPayload.message フィールドの値をラベルベースの変数の値を含む文字列値と比較します。

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

別の例として、値のみの変数 value_only_severity_variable について考えてみましょう。値のメニューで、ERROR、INFO、NOTICE の 3 つの値が選択されているとします。次に、ログパネル ウィジェットのクエリペインに次のコードを追加します。

severity =~ "${value_only_severity_variable}"

レンダリングされたフォームは次のようになります。

severity =~ "^(ERROR|INFO|NOTICE)$"

たとえば、次の JSON は、ラベルベースの変数を使用してログパネル ウィジェットのクエリを更新する方法を示しています。

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

たとえば、次のクエリでは正規表現を使用して、jsonPayload.message フィールドの値をラベルベースの変数の値を含む文字列値と比較します。

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

別の例として、値のみの変数 value_only_severity_variable について考えてみましょう。メニューで ERROR、INFO、NOTICE の 3 つの値が選択されているとします。次に、ログパネル ウィジェットのクエリペインに次のコードを追加します。

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

ログパネル ウィジェットで実行されるクエリは次のとおりです。

severity =~ "^(ERROR|INFO|NOTICE)$"

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

次の表に、ログパネルで変数の例が解決される方法を示します。前述のように、変数の値のみを使用する場合は、比較演算子として正規表現を使用する必要があります。

構文	選択された 値	解決されたログパネル式
${my_label_based_variable}	12345	resource.labels."instance_id"="12345" 変数の例は、リソースラベル instance_id に基づいています。
${my_label_based_variable}	*	""
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.*

PromQL クエリを含むグラフ

ラベルベースの変数に依存するように PromQL クエリを含むグラフを更新するには、一般的な構文に記載されているガイダンスに沿って操作します。

ConsoleAPI

たとえば、次のクエリは、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提としています。

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

クエリを変更して、変数の値のみを解決することもできます。次の例では、正規表現を使用して、ラベルベースのクエリの値を instance_id と比較します。

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

値のみの変数の場合は、.value 句を省略します。たとえば、値のみの変数を使用してゾーンでフィルタリングするには、クエリに次のような内容を含めます。

zone=~"${my_value_only_variable}"

たとえば、次の JSON は、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提とするクエリを示しています。

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

クエリを変更して、変数の値のみを解決することもできます。次の例では、正規表現を使用して、ラベルベースのクエリの値を instance_id と比較します。

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

値のみの変数の場合は、.value 句を省略します。たとえば、値のみの変数を使用してゾーンでフィルタリングするには、クエリに次のような内容を含めます。

zone=~\"${my_value_only_variable}\"

次の表に、PromQL によって変数の例が解決される方法を示します。前述のように、変数の値のみを使用する場合は、比較演算子として正規表現を使用する必要があります。

構文	選択された 値	解決された PromQL 式
${my_label_based_variable}	12345	instance_id == '12345' 変数の例は、リソースラベル instance_id に基づいています。
${my_label_based_variable}	*	noop_filter=~".*"
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.+

SQL クエリを使用したグラフ

SQL で定義されたウィジェットを変数に依存するように更新する場合は、WHERE 句を更新して変数の値を参照します。すべての変数に「at」記号を接頭辞として追加します（例: @variable_name）。ラベルベースの変数の場合は、変数名 @my_label_based_variabe.value に .value を追加します。

SQL クエリの場合、変数の置換は BigQuery に依存し、SQL インジェクションに対して安全です。詳細については、パラメータ化クエリの実行をご覧ください。

ConsoleAPI

SQL ではワイルドカード演算子を「任意の値」と解釈しないため、SQL クエリで変数を使用する場合は、常に IF ステートメントを使用することをおすすめします。次の例は、データ型が文字列の値のみの変数の使用方法を示しています。

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

変数のメニュー オプションで複数の値を選択できるようにする場合は、CAST 関数を使用して、変数の値を GoogleSQL データ型にキャストする必要があります。次のクエリは、この構文を示しています。

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

SQL ではワイルドカード演算子が「任意の値」を意味すると解釈されないため、前述の例の IF ステートメントを使用することをおすすめします。したがって、IF ステートメントを省略し、ワイルドカード演算子を選択した場合、クエリの結果は空のテーブルになります。2 番目の例では、UNNEST 関数によって配列がテーブルに変換されます。

適切な形式の WHERE 句を追加する手順は次のとおりです。

1. ウィジェットを編集します。
2. ツールバーで [変数フィルタを挿入] を選択し、WHERE 句を更新する変数を選択します。
3. 表示されたダイアログで、生成されたコードを確認し、[コピーして閉じる] をクリックします。

4. コピーしたコードを [クエリ] ペインに貼り付け、必要に応じて編集します。

   たとえば、ログ名のリストを生成して、log_name という名前の単一列を持つテーブルに出力する LogName という名前の変数を作成したとします。次に、グラフを作成し、[変数フィルタを挿入] を選択して、変数 LogName を選択します。次のコードが生成されます。

   WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
   

   この例では、テーブル結合を実行できるように、生成されたコードを編集して LogName = を log_name = に置き換える必要があります。

   WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
   

5. [実行]、[適用] の順にクリックします。

6. 変更したダッシュボードを保存するには、ツールバーで [保存] をクリックします。

SQL ではワイルドカード演算子を「任意の値」と解釈しないため、SQL クエリで変数を使用する場合は、常に IF ステートメントを使用することをおすすめします。次の例は、データ型が文字列の値のみの変数の使用方法を示しています。

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

たとえば、次の例は、SQL クエリの結果を表示するグラフの JSON 表現の一部を示しています。ログ名による結果のフィルタリングをサポートするため、LogName という名前の変数を参照する WHERE 句が追加されました。

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

変数 LogName は、使用可能なログ名のリストを決定するためにクエリも発行します。

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

変数のメニュー オプションで複数の値を選択できるようにする場合は、CAST 関数を使用して、変数の値を GoogleSQL データ型にキャストする必要があります。次のクエリは、この構文を示しています。

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

SQL ではワイルドカード演算子が「任意の値」を意味すると解釈されないため、前述の例の IF ステートメントを使用することをおすすめします。したがって、IF ステートメントを省略し、ワイルドカード演算子を選択した場合、クエリの結果は空のテーブルになります。2 番目の例では、UNNEST 関数によって配列がテーブルに変換されます。

MQL クエリを使用したグラフ

ラベルベースの変数を使用する MQL クエリを含むグラフにパイプ（(|)）を追加し、一般的な構文に記載されているガイダンスに沿って操作します。

メニュー ドリブンのインターフェースを使用して時系列データを表示するグラフを作成するときに、選択内容はモニタリング フィルタに変換されます。

ConsoleAPI

たとえば、次のクエリは、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提としています。

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

クエリを変更して、変数の値のみを解決することもできます。次の例では、正規表現を使用して、ラベルベースのクエリの値を instance_id と比較します。

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

値のみの変数の場合は、.value 句を省略します。たとえば、値のみの変数を使用してゾーンでフィルタリングするには、クエリに次のような内容を含めます。

resource.zone=~'${my_value_only_variable}'

たとえば、次の JSON は、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提とするクエリを示しています。

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

クエリを変更して、変数の値のみを解決することもできます。次の例では、正規表現を使用して、ラベルベースのクエリの値を instance_id と比較します。

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

値のみの変数の場合は、.value 句を省略します。たとえば、値のみの変数を使用してゾーンでフィルタリングするには、クエリに次のような内容を含めます。

resource.zone=~'${my_value_only_variable}'

次の表に、MQL によってサンプル変数が解決される方法を示します。前述のように、変数の値のみを使用する場合は、比較演算子として正規表現を使用する必要があります。

構文	選択された 値	解決された MQL 式
${my_label_based_variable}	12345	filter (resource.instance_id == '12345') 変数の例は、リソースラベル instance_id に基づいています。
${my_label_based_variable}	*	filter (true)
${my_label_based_variable.value} ${my_value_based_variable}	12345	12345
${my_label_based_variable.value} ${my_value_based_variable}	*	.*

Monitoring フィルタクエリを含むグラフ

Monitoring フィルタの形式のクエリを含むグラフを更新して、ラベルベースの変数に依存させるには、一般的な構文に記載されているガイダンスに沿って操作します。

ConsoleAPI

Google Cloud コンソールを使用してグラフを作成し、メニュー ドリブン インターフェースを使用している場合は、変数の [グラフに適用] フィールドを使用するか、ウィジェットを編集して [フィルタ] メニューからラベルベースの変数を選択することで、グラフのクエリを更新できます。[フィルタ] メニューには、すべてのラベルベースの変数とすべてのラベルキーが一覧表示されます。

値ベースの変数に依存するようにグラフのクエリを更新するには、次の操作を行います。

1. グラフの編集。
2. クエリペインで [フィルタを追加] をクリックし、ラベルキーを選択します。たとえば、[zone] を選択します。
3. [値] メニューで、値のみの変数を選択します。
4. [適用] をクリックします。
5. 変更したダッシュボードを保存するには、ツールバーで [保存] をクリックします。

たとえば、次の JSON は、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提とするクエリを示しています。

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Monitoring フィルタの形式のクエリを使用するウィジェットでは、ラベルベースの変数の値で時系列をフィルタリングすることはできませんが、値のみの変数でフィルタリングすることはできます。たとえば、次のクエリは、値のみの変数の値に基づいて zone でフィルタするクエリの [フィルタ] フィールドの値を示しています。

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

たとえば、次の JSON は、ラベルベースの変数 my_label_based_variable がフィルタ式に解決されることを前提とするクエリを示しています。

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Monitoring フィルタの形式のクエリを使用するウィジェットでは、ラベルベースの変数の値で時系列をフィルタリングすることはできませんが、値のみの変数でフィルタリングすることはできます。たとえば、次のクエリは、値のみの変数の値に基づいて zone でフィルタするクエリの "filter" フィールドを示しています。

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

次の表に、Monitoring フィルタによって変数の例が解決される方法を示します。前述のように、変数の値のみを使用する場合は、比較演算子として正規表現を使用する必要があります。

構文	選択された 値	解決されたフィルタ式
${my_label_based_variable}	12345	resource.instance_id == "12345" 変数の例は、リソースラベル instance_id に基づいています。
${my_label_based_variable}	*	除外
${my_label_based_variable.value}	12345	非対応
${my_label_based_variable.value}	*	非対応
${my_value_based_variable}	12345	"12345"
${my_value_based_variable}	*	".*"

始める前に

ダッシュボードを作成または管理する Google Cloud プロジェクトで、次の操作を行います。

• Select the tab for how you plan to use the samples on this page:

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Terraform

  ローカル開発環境でこのページの Terraform サンプルを使用するには、gcloud CLI をインストールして初期化し、ユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定します。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  詳細については、 Google Cloud 認証ドキュメントの ローカル開発環境の ADC を設定するをご覧ください。

  REST

  このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

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

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

name フィールドは省略可能です。name フィールドの値の構造は次のとおりです。

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

ダッシュボードを作成すると、API が自動的に DASHBOARD_ID コンポーネントを生成します。カスタム DASHBOARD_ID を指定する場合は、Dashboard オブジェクトの name フィールドを指定できます。

注: name フィールドの値はグローバルに一意である必要があります。このフィールドはダッシュボードの一意の名前として使用されます。ダッシュボードの作成に使用する YAML ファイルまたは JSON ファイルでこのフィールドを指定する場合は、実行ごとに DASHBOARD_ID に固有の値を使用していることを確認してください。同じプロジェクトにダッシュボードを作成しようとしたときに、指定した ID が使用中の場合、エラーが発生します。詳細については、ダッシュボードの作成に失敗するをご覧ください。表示名は一意である必要はありません。

gcloudTerraformREST

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

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

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。

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

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

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

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。 詳細については、Terraform プロバイダのリファレンス ドキュメントをご覧ください。

注: Terraform を使用してダッシュボードを作成した場合は、Google Cloud コンソールでダッシュボードを表示できます。ただし、Google Cloud コンソールでダッシュボードを編集しないでください。編集すると、ダッシュボードのサイズが変更されます。詳細については、トラブルシューティング: Terraform で作成されたダッシュボードのサイズが変更されるをご覧ください。

Terraform を使用してダッシュボードを作成するには、次の操作を行います。

1. プロジェクトに Terraform をインストールして構成します。

2. Terraform リソース google_monitoring_dashboard を使用します。

   コマンドで、次のフィールドを設定します。

   • dashboard_json: Dashboards 形式のダッシュボードの JSON 表現。

     この形式の例については、API Explorer を使用してダッシュボードを一覧表示するか、Google Cloud コンソールでダッシュボードを開いて JSON 表現を表示します。

   • parent: プロジェクトの完全修飾名。たとえば、このフィールドを "projects/PROJECT_ID" に設定します。ここで、PROJECT_ID は Google Cloud プロジェクトの 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

前のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。

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

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

ダッシュボードの削除

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

gcloudTerraformREST

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

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。
• DASHBOARD_ID: ダッシュボードの ID。

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

リソースは Terraform を使用して削除できます。リソースの削除については、Terraform コマンド destroy をご覧ください。

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

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

前のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。
• ${DASHBOARD_ID}: ダッシュボードの ID を格納する環境変数。

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

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

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

gcloudTerraformREST

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

gcloud monitoring dashboards list --project=PROJECT_ID

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。

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

Terraform を使用してプロジェクトにクエリを送信し、ダッシュボードのリストをレスポンスとして取得することはできません。ただし、これらのダッシュボードは Google Cloud コンソールを使用して表示できます。

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

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

上記のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。

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

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

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

gcloudTerraformREST

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

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。

Terraform を使用してプロジェクトにクエリを送信し、レスポンスでダッシュボードのページネーション付きリストを取得することはできません。ただし、これらのダッシュボードは Google Cloud コンソールを使用して表示できます。

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

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

上記のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。

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

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

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

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

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

gcloudTerraformREST

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

gcloud monitoring dashboards describe DASHBOARD_ID --format=json -project=PROJECT_ID

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。
• DASHBOARD_ID: ダッシュボードの 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 monitoring dashboards describe リファレンスをご覧ください。

Terraform を使用してプロジェクトにクエリを送信し、個々のダッシュボードをレスポンスとして返すことはできません。ただし、これらのダッシュボードは Google Cloud コンソールを使用して表示できます。

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

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

上記のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。
• ${DASHBOARD_ID}: ダッシュボードの ID を格納する環境変数。

上記の式で、${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"
}

ダッシュボードの更新

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

gcloudTerraformREST

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

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

前述のコマンドを実行する前に、次のように置き換えます。

• PROJECT_ID: プロジェクトの識別子。
• DASHBOARD_ID: ダッシュボードの ID。

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

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

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。 詳細については、Terraform プロバイダのリファレンス ドキュメントをご覧ください。

Terraform を使用してダッシュボードを更新する手順は次のとおりです。

1. プロジェクトに Terraform をインストールして構成します。

2. Terraform リソース google_monitoring_dashboard を使用します。

   コマンドで、次のフィールドを設定します。

   • dashboard_json: Dashboards 形式のダッシュボードの JSON 表現。

   • parent: プロジェクトの完全修飾名。たとえば、このフィールドを "projects/PROJECT_ID" に設定します。ここで、PROJECT_ID は Google Cloud プロジェクトの ID です。

カスタム ダッシュボードを更新するには、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}

上記のコマンドを実行する前に、次のように構成します。

• ${PROJECT_ID}: ダッシュボードを作成するプロジェクト ID を格納する環境変数。
• ${DASHBOARD_ID}: ダッシュボードの ID を格納する環境変数。

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

次のステップ

• ダッシュボードとレイアウトのサンプル
• Google Cloud コンソールでカスタム ダッシュボードを作成して管理する