変数と固定されたフィルタを作成して管理する

このドキュメントでは、ダッシュボード レベルのフィルタを固定して、これらのフィルタを永続的にする方法について説明します。各ウィジェットを変更せずにダッシュボードに表示されるデータを変更できる固定フィルタは、デフォルトの状態を持ち、ダッシュボード全体に適用されます。ダッシュボード ツールバーには、各固定フィルタと、フィルタの値を一時的に変更できるメニューが表示されます。

変数は固定フィルタと似ていますが、特定のウィジェットにのみ適用されます。このドキュメントでは、変数を作成する方法と、ウィジェットで変数を適用する方法について説明します。変数は、ウィジェットのクエリを変更したり、ウィジェットの表示を制御したりできます。ダッシュボードのツールバーには、各変数が名前とともに表示されます。また、変数の値を一時的に変更できるメニューも表示されます。フィルタと変数を区別できるように、ツールバーの変数名の先頭にはドル記号 $ が付いています。

このドキュメントでは、 Google Cloud コンソールを使用して変数と固定フィルタを作成する方法について説明します。Cloud Monitoring API の使用方法については、API を使用してダッシュボードを作成、管理する: ダッシュボード フィルタをご覧ください。

現在のセッションにのみ適用される一時的なグループとフィルタを追加および変更する方法については、カスタム ダッシュボードに一時的なフィルタを追加するをご覧ください。

この機能は Google Cloud プロジェクトでのみサポートされています。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。

固定フィルタについて

固定フィルタには、ラベル、1 つ以上のデフォルト値、すべての有効な値のリストが含まれます。使用可能なすべての値のリストは、ダッシュボードに表示される時系列データから動的に取得されます。フィルタの構造については、DashboardFilter をご覧ください。

固定フィルタは個々のウィジェットには適用されません。代わりに、次のルールを使用して、固定フィルタでウィジェットに表示されるデータを変更できるかどうかを判断します。

• ウィジェットに、固定フィルタで指定されたラベルキーを含むデータが表示され、ウィジェットでそのラベルキーの値が指定されていない場合、固定フィルタによって表示されるデータを変更できます。

  たとえば、固定フィルタ cluster_name: mycluster を追加したとします。グラフには、値が mycluster の cluster_name ラベルを持つ時系列のみが自動的に表示されます。同様に、ログパネル ウィジェットのクエリは resource.labels."cluster_name"="mycluster" に変更され、グラフには、固定フィルタのラベルを含む時系列のみが自動的に表示されます。

• ウィジェットに同じラベルキーのフィルタが含まれている場合、またはウィジェットに表示されるデータに固定フィルタで指定されたラベルキーが含まれていない場合、固定フィルタはウィジェットによって無視されます。

変数について

変数には名前と型があります。変数は、ウィジェットに含まれるクエリを変更することで、特定のウィジェットに適用されます。フィルタの構造については、DashboardFilter をご覧ください。

ダッシュボードのツールバーでは、変数名の前にドル記号 $ が付加されます。visibility（表示）アイコンも表示されている場合は、その変数が少なくとも 1 つのウィジェットの表示を制御しています。

変数はラベルベースにすることも、値のみにすることもできます。

• ラベルベースの変数は、固定フィルタのようなものです。これらの変数には、ラベルキー、1 つ以上のデフォルトのラベル値、使用可能なすべてのラベル値のリストが含まれます。使用可能なすべての値のリストは、ダッシュボードに表示される時系列データから動的に取得されます。

• 値のみの変数には 1 つ以上のデフォルト値が含まれており、すべての有効な値がリストされている場合があります。デフォルト値を指定しない場合、デフォルト値にはワイルドカード演算子 (*) が選択されます。可能な値のセットを定義するには、値の配列を指定するか、SQL クエリを作成します。

  値のみの変数には、カスタム、テキスト入力、SQL クエリの 3 種類があります。

  • カスタム: 可能な値のリストを列挙し、1 つ以上のデフォルト値を設定する場合に使用します。たとえば、使用可能なすべての値のリストを prod, staging, dev に設定し、デフォルト値を prod に設定できます。

  • テキスト入力: すべての可能な値を把握していない場合に使用します。たとえば、URL でフィルタしたいが、変数の作成時に URL の正確なリストがわからないとします。ウィジェットのフィルタ メニューを使用するときに、新しい URL を入力し、現在のセッションまたは変数定義の変更を保存できます。

  • SQL クエリ: SQL クエリを使用して可能な値のリストを生成する場合に使用します。これらの変数は、ログ分析を使用して作成されたグラフに適用することを目的としています。

    これらの変数については、クエリ結果が 1 列のテーブルであり、その列のデータ型が文字列で、テーブルの各行に一意の文字列値が含まれていることを確認してください。

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    SQL クエリは変数に依存できません。

変数をウィジェットに適用するには、ウィジェットによって発行されたクエリを更新するか、ウィジェットの公開設定を更新します。ウィジェットを編集してクエリを更新することはいつでも可能です。ただし、ラベルベースの変数と一部のウィジェット タイプでは、メニューから選択してクエリを更新できます。公開設定を制御するには、ウィジェットを編集する必要があります。詳細については、このドキュメントの次のセクションをご覧ください。

• ウィジェットのクエリを更新する
• ウィジェットの表示 / 非表示を設定する

始める前に

フィルタと変数を構成する Google Cloud プロジェクトで、次の操作を行います。

• Google Cloud コンソールを使用して変数または固定フィルタを追加または変更するために必要な権限を取得するには、プロジェクトに対する Monitoring 編集者（roles/monitoring.editor）の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

  必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

  ロールの詳細については、Identity and Access Management を使用してアクセスを制御するをご覧ください。

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

フィルタをサポートするすべてのダッシュボード ウィジェットに適用されるフィルタを作成して固定する手順は次のとおりです。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。
3. ダッシュボードを選択し、ダッシュボード ツールバーに移動して、settings（設定）をクリックします。
4. [フィルタ] セクションで [フィルタを追加] をクリックします。
5. [arrow_drop_down ラベル] をクリックし、ラベルを選択します。たとえば、zone を選択します。
6. 変数の値メニューから複数の値を選択できるようにするには、[複数選択] を選択します。[複数選択] が有効になっていない場合、値メニューから 1 つのオプションしか選択できません。

7. [arrow_drop_down デフォルト値] をクリックし、ラベルのデフォルト値を 1 つ以上選択します。すべての値と一致させるには、* を選択します。

   作成したフィルタは、ダッシュボードのツールバーに追加されます。フィルタ値を一時的に変更するには、フィルタを選択して、メニューから選択します。

8. [完了]、[適用] の順にクリックします。

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

変数を作成する

特定のダッシュボード ウィジェットに適用される変数を作成する手順は次のとおりです。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。
3. ダッシュボードを選択し、ダッシュボード ツールバーに移動して、settings（設定）をクリックします。
4. [変数] セクションで、[変数を追加] をクリックします。

5. 変数のタイプを選択し、ダイアログを完了します。

   ラベルベースの変数を作成するには、[ラベル] を選択します。ラベルキーとラベル値があり、フィルタのように使用できる変数が必要な場合は、このオプションを使用します。使用可能なすべての値のリストは、ダッシュボードに表示される時系列データから動的に取得されます。[グラフへの適用] メニューでは、変数を適用してクエリを変更するウィジェットを選択できます。ウィジェットを編集してクエリを更新することもできます。

   値のみの変数には、次のオプションがあります。

   • SQL: SQL クエリの結果から、可能な値のリストを生成する場合に使用します。

     1 つ以上のデフォルト値を入力し、使用可能なすべての値のリストを生成する SQL クエリを入力します。クエリ結果が 1 つの列を持つテーブルであり、その列のデータ型が文字列で、テーブルの各行に一意の文字列値が含まれていることを確認します。

   • カスタム: 候補値のリストとデフォルト値の両方を指定する場合は、このオプションを使用します。たとえば、[値] フィールドを prod, staging, dev に設定し、[デフォルト値] を prod に設定します。

   • テキスト入力: デフォルトとして適用される値のリストを指定する場合は、このオプションを使用します。

6. [完了]、[適用] の順にクリックします。

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

8. 変数をウィジェットに適用します。ウィジェットのクエリを更新すると、変数の値を変更したときにクエリが変更され、ウィジェットに表示されるデータが変更されます。変数を使用して、ウィジェットを表示するかどうかを制御することもできます。詳細については、このドキュメントの次のセクションをご覧ください。

   • ウィジェットの表示 / 非表示を設定する
   • ウィジェットのクエリを更新する

ウィジェットの表示 / 非表示を設定する

ウィジェットがデータをクエリするときに、変数を使用して、ウィジェットをダッシュボードに表示するかどうかを制御できます。たとえば、ダッシュボードに本番環境システムのデータを表示するウィジェットと、ステージング システムのデータを表示する別のウィジェットのセットが含まれているとします。開発中にデバッグを行う場合、ステージング データのみを表示したいことがあります。変数を使用してダッシュボード ウィジェットの公開設定を構成すると、表示対象を本番環境データのみ、ステージング データのみ、すべてのデータに切り替えることができます。

ウィジェットの表示 / 非表示は、任意のタイプの変数で制御できます。

ウィジェットの公開設定を構成する手順は次のとおりです。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. ダッシュボードを選択します。
3. 公開設定を構成するウィジェットのツールバーに移動し、[edit 編集] をクリックします。
4. [表示] ペインで、[Widget visibility] を開きます。

5. 変数を選択して、ダイアログの項目をすべて入力します。

6. [完了]、[適用] の順にクリックします。

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

   ダッシュボードが更新されます。公開設定コントロールによってダッシュボードのウィジェットが 1 つ以上非表示になっている場合、ダッシュボードにバナーが表示されます。すべてのウィジェットを表示するには、[すべてのウィジェットを表示] をクリックします。

変数を使用してダッシュボード上の 1 つ以上のウィジェットの表示を制御すると、ツールバーの変数名に visibility 表示アイコンが表示されます。

制限事項

ウィジェットの公開設定を構成する場合は、次の制限が適用されます。

• 折りたたみ可能なグループ、セクション ヘッダー、シングルビューなどの組織ウィジェットは常に表示されます。

• ウィジェットの表示 / 非表示コントロールで参照されている変数は削除できます。変数削除アクションでは、変数への参照も削除されます。

• すべてのダッシュボードで変数の作成がサポートされているわけではありません。ただし、ダッシュボードに変数がある場合は、その変数を使用してダッシュボードのウィジェットの表示を管理できます。

ウィジェットのクエリを更新する

このセクションでは、ウィジェットが発行するクエリに変数を含める方法について説明します。その結果、変数の値を変更すると、クエリが変更され、ウィジェットに表示されるデータが変更されます。

• SQL、PromQL、MQL クエリを使用するグラフとログパネル ウィジェットの場合は、ウィジェットを編集してクエリを変更する必要があります。このセクションでは、これらの編集を行う方法について説明します。

• メニューまたはダイレクト フィルタモードを使用して構成したグラフの場合、[グラフへの適用] メニューを使用してウィジェットを選択すると、Monitoring はクエリを編集します。ウィジェットを編集して [フィルタ] フィールドに移動し、変数を選択することもできます。

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

• 変数を逆参照する一般的な構文
• ログパネル ウィジェット
• PromQL クエリで作成するグラフ
• SQL クエリで作成するグラフ
• MQL クエリで作成するグラフ

• Monitoring フィルタクエリで作成するグラフ

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

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

{
  "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",
  ...
}

変数を逆参照する一般的な構文

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

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

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

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

ログパネル ウィジェット

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

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

severity =~ "${value_only_severity_variable}"

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

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

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

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

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

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

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

PromQL クエリで作成するグラフ

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

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

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

zone=~"${my_value_only_variable}"

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

"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
},

zone=~\"${my_value_only_variable}\"

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

SQL クエリで作成するグラフ

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

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

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

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

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

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

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

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

MQL クエリで作成するグラフ

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

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

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

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

resource.zone=~'${my_value_only_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
},

"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
},

resource.zone=~'${my_value_only_variable}'

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

Monitoring フィルタクエリで作成するグラフ

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

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

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_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
},

"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 フィルタによってサンプル変数がどのように解決されるかを示しています。前述のように、変数の値のみを使用する場合は、比較演算子として正規表現を使用する必要があります。

固定されたフィルタまたは変数を変更する

ダッシュボードのツールバーに表示されているフィルタの値を一時的に変更するには、フィルタ名をクリックして、値を入力するか、メニューから選択します。

ダッシュボードに時系列データを表示するテーブルが含まれている場合は、セルの [filter_list ダッシュボードをこの値でフィルタ] ボタンを使用して、一時フィルタを追加したり、永続的なフィルタと変数を変更できます。このボタンを選択すると、新しい一時フィルタが適用されるか、既存のフィルタまたは変数の値が更新されます。テーブル列のラベルキーがフィルタまたは変数のラベルキーと一致すると、既存のフィルタと変数が更新されます。

固定フィルタまたは変数の構成を変更する手順は次のとおりです。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。
3. ダッシュボード ツールバーで、settings（設定）をクリックします。
4. 変更するフィルタまたは変数を見つけて、その定義を開きます。
5. 変更が完了したら、[適用] をクリックします。
6. 変更したダッシュボードを保存するには、ツールバーで [保存] をクリックします。

固定したフィルタまたは変数を削除する

固定フィルタまたは変数を削除するには、次の操作を行います。

1. Google Cloud コンソールで [ ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。
3. ダッシュボード ツールバーで、settings（設定）をクリックします。
4. 削除するフィルタまたは変数を見つけて、[delete 削除] をクリックします。
5. [適用] をクリックします。
6. 変更したダッシュボードを保存するには、ツールバーで [保存] をクリックします。

次のステップ

• グラフデータを確認する
• リソース固有のダッシュボードにアクセスする