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 を使用して直接呼び出せます。

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

ダッシュボードについて

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

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

レイアウトは、ダッシュボードのコンポーネントの順序を定義します。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 フィルタクエリを使用したグラフ

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

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

Console

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

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

API

固定されたフィルタと変数を定義するには、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 句を含めないでください。比較には正規表現を使用する必要があります。

ログパネルのウィジェット

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

Console

たとえば、次のクエリでは正規表現を使用して、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)$"

API

たとえば、次の 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 クエリを含むグラフに適用するには、一般的な構文に記載されているガイダンスに沿って操作します。

Console

たとえば、次のクエリは、ラベルベースの変数 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}"

API

たとえば、次の 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 句を更新して変数の値を参照します。すべての変数に、変数名の前に「@」記号を付けます（例: @variable_name）。ラベルベースの変数の場合は、変数名 @my_label_based_variabe.value に .value を追加します。

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

Console

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. 変更したダッシュボードを保存するには、ツールバーで [保存] をクリックします。

API

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

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

Console

たとえば、次のクエリは、ラベルベースの変数 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}'

API

たとえば、次の 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 フィルタの形式のクエリを含むグラフにラベルベースの変数を適用するには、一般的な構文に記載されているガイダンスに沿って操作します。

Console

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

値ベースの変数をこれらのタイプのグラフに適用する手順は次のとおりです。

1. グラフの編集。
2. クエリペインで [フィルタを追加] をクリックし、ラベルキーを選択します。たとえば、[ゾーン] を選択します。
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})

API

たとえば、次の 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}	*	".*"

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

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

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

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

API

新しいダッシュボードを作成するには、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 リファレンスをご覧ください。

Terraform

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

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

Terraform を使用してダッシュボードを作成するには、Terraform リソース google_monitoring_dashboard を使用します。

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

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

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

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

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

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

ダッシュボードの削除

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

API

カスタム ダッシュボードを削除するには、削除するダッシュボードの 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 リファレンスをご覧ください。

Terraform

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

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

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

API

プロジェクトのすべてのカスタムダッシュボードを一覧表示するには、プロジェクト 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 リファレンスをご覧ください。

Terraform

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

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

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

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

API

結果リストの最初のページで、リクエストに 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

Terraform

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

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

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

API

特定のカスタム ダッシュボードを取得するには、ダッシュボード 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 リファレンスをご覧ください。

Terraform

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

ダッシュボードの更新

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

API

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

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

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 値が含まれ、更新されたダッシュボードの一覧のコピーです。

Terraform

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

Terraform を使用してダッシュボードを更新するには、Terraform リソース google_monitoring_dashboard を使用します。

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

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

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

次のステップ

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