建立及管理變數和固定篩選器

本文說明如何固定資訊主頁層級的篩選器，讓這些篩選器成為永久篩選器。固定篩選器可讓您修改資訊主頁顯示的資料，不必修改每個小工具，且固定篩選器有預設狀態，會套用至整個資訊主頁。資訊主頁工具列會顯示每個已釘選的篩選器，以及一個選單，可讓您暫時變更篩選器的值。

變數與釘選的篩選器類似，但只適用於特定小工具。本文說明如何建立變數，以及如何透過小工具套用變數。變數可以修改小工具的查詢，也可以控制小工具的顯示設定。資訊主頁工具列會依名稱顯示每個變數，並提供選單，方便您暫時變更變數值。為協助您區分篩選器和變數，工具列中的變數名稱會加上美元符號 $ 前置字元。

本文說明如何使用 Google Cloud 控制台建立變數和釘選篩選器。如要瞭解如何使用 Cloud Monitoring API，請參閱「透過 API 建立及管理資訊主頁：資訊主頁篩選器」。

如要瞭解如何新增及修改臨時分組和篩選條件 (僅適用於目前工作階段)，請參閱「在自訂資訊主頁中新增臨時篩選條件」。

這項功能僅支援 Google Cloud 專案。 如要進行 App Hub 設定，請選取 App Hub 主專案或啟用應用程式的資料夾管理專案。

關於已釘選的篩選器

已釘選的篩選器包含標籤、一或多個預設值，以及所有可能值的清單。系統會根據資訊主頁上顯示的時間序列資料，動態衍生所有可能的值。如要瞭解篩選器的結構，請參閱 DashboardFilter。

您不會將已釘選的篩選器套用至個別小工具。系統會改用下列規則，判斷固定篩選器是否可以變更小工具顯示的資料：

• 如果小工具顯示的資料包含釘選篩選器指定的標籤鍵，且小工具未指定該標籤鍵的值，釘選篩選器就能變更顯示的資料。

  舉例來說，假設您新增了釘選的篩選器 cluster_name: mycluster。 這樣圖表就會自動只顯示具有 cluster_name 標籤，且值為 mycluster 的時間序列。同樣地，記錄面板小工具的查詢會修改為 resource.labels."cluster_name"="mycluster"，圖表也會自動只顯示包含固定篩選器中標籤的時間序列。

• 如果小工具包含相同標籤鍵的篩選器，或是小工具顯示的資料不含固定篩選器中指定的標籤鍵，系統就會忽略固定篩選器。

關於變數

變數有名稱和類型。如要將變數套用至特定小工具，請修改小工具所含的查詢。如要瞭解篩選器的結構，請參閱 DashboardFilter。

在資訊主頁工具列中，變數名稱會加上美元符號 $ 前置字元。 如果同時看到「可見」visibility圖示，表示變數控制至少一個小工具的可見度。

變數可以是標籤變數，也可以只有值：

• 標籤變數就像釘選的篩選器，這些變數包含標籤鍵、一或多個預設標籤值，以及所有可能的標籤值清單。系統會根據資訊主頁上顯示的時間序列資料，動態衍生所有可能的值。

• 僅含值的變數包含一或多個預設值，且可能會列出所有可能的值。如未指定預設值，系統會選取萬用字元運算子 (*) 做為預設值。如要定義所有可能值的集合，您可以提供值陣列，也可以編寫 SQL 查詢。

  僅包含值的變數有三種：自訂、文字輸入和 SQL 查詢。

  • 自訂：如要列舉所有可能的值，並設定一或多個預設值，請使用這個選項。舉例來說，您可能會將所有可能的值清單設為 prod, staging, dev，並將預設值設為 prod。

  • 文字輸入：不知道所有可能值時使用。舉例來說，您可能想依網址篩選，但在建立變數時，您不知道確切的網址清單。接著，當您使用小工具的篩選器選單時，可以輸入新網址，然後儲存目前工作階段的變更，或儲存至變數定義。

  • SQL 查詢：如要使用 SQL 查詢產生可能值的清單，請選取這個選項。這些變數適用於使用 Log Analytics 建立的圖表。

    請確保這些變數的查詢結果是包含一個資料欄的表格，且該資料欄的資料類型為字串，而表格中的每個資料列都包含不重複的字串值：

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    SQL 查詢不得依附變數。

如要將變數套用至小工具，請更新小工具發出的查詢，或更新小工具的顯示狀態。您隨時可以編輯小工具，更新查詢。不過，如果是以標籤為準的變數和某些小工具類型，您可以透過選單選項更新查詢。如要控管小工具的顯示狀態，請編輯小工具。詳情請參閱本文件的下列各節：

• 更新小工具的查詢
• 設定小工具的顯示設定

事前準備

針對要設定篩選器和變數的 Google Cloud 專案，完成下列步驟：

• 如要取得透過 Google Cloud 控制台新增或修改變數或釘選篩選器所需的權限，請要求管理員授予專案的監控編輯者 (roles/monitoring.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

  您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

  如要進一步瞭解角色，請參閱「使用身分與存取權管理功能控管存取權」一文。

建立並釘選篩選器

如要建立並釘選篩選器，以便套用至所有支援篩選器的資訊主頁小工具，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如為「App Hub」設定，請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
3. 選取資訊主頁，前往資訊主頁工具列，然後按一下「設定」settings。
4. 在「篩選器」部分中，按一下「新增篩選器」。
5. 按一下「標籤」arrow_drop_down，然後選取標籤。舉例來說，您可以選取 zone。
6. 如要讓使用者從變數的值選單中選取多個值，請選取「多選」。如果未啟用「複選」，使用者只能從值選單中選取一個選項。

7. 按一下「預設值」arrow_drop_down，然後選取標籤的預設值。如要比對所有值，請選取 *。

   篩選條件建立完成後，就會新增至資訊主頁工具列。如要暫時變更篩選器值，請選取篩選器，然後從選單中選取項目。

8. 依序點選「完成」和「套用」。

9. 如要儲存修改後的資訊主頁，請按一下工具列中的「儲存」。

建立變數

如要建立適用於特定資訊主頁小工具的變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如為「App Hub」設定，請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
3. 選取資訊主頁，前往資訊主頁工具列，然後按一下「設定」settings。
4. 在「變數」部分中，按一下「新增變數」。

5. 選取變數類型，然後完成對話方塊。

   如要建立以標籤為準的變數，請選取「標籤」。如要建立含有標籤鍵和標籤值的變數，並將該變數做為篩選器使用，請選取這個選項。系統會根據資訊主頁上顯示的時間序列資料，動態衍生所有可能的值。「套用至圖表」選單可讓您選取要透過變數修改查詢的 widget。您也可以編輯小工具來更新查詢。

   如果是僅限值的變數，您可以採取下列做法：

   • SQL：如要使用 SQL 查詢結果生成所有可能值的清單，請選取這個選項。

     輸入一或多個預設值，並輸入可產生所有可能值清單的 SQL 查詢。確認查詢結果是只有一個資料欄的資料表，且該資料欄的資料類型為字串，而資料表中的每個資料列都包含不重複的字串值。

   • 自訂：如要指定可能值的清單和預設值，請使用這個選項。舉例來說，您可以將「值」欄位設為 prod, staging, dev，並將「預設值」設為 prod。

   • 文字輸入：如要指定預設套用的值清單，請使用這個選項。

6. 依序點選「完成」和「套用」。

7. 如要儲存修改後的資訊主頁，請按一下工具列中的「儲存」。

8. 將變數套用至小工具。如果您更新小工具的查詢，變更變數值時，查詢就會修改，小工具顯示的資料也會隨之變更。您也可以使用變數控制小工具是否顯示。詳情請參閱本文的下列章節：

   • 設定小工具的顯示設定
   • 更新小工具的查詢

設定小工具的顯示設定

小工具查詢資料時，您可以使用變數控制小工具是否顯示在資訊主頁上。舉例來說，假設資訊主頁包含顯示生產系統資料的小工具，以及顯示暫存系統資料的另一組小工具。在開發期間進行偵錯時，您可能只想查看暫存資料。使用變數設定資訊主頁小工具的顯示狀態，即可只顯示正式版資料、只顯示測試版資料，或顯示所有資料。

任何類型的變數都可以控制小工具的顯示或隱藏狀態。

如要設定小工具的顯示狀態，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 選取資訊主頁。
3. 前往要設定顯示狀態的小工具工具列，然後按一下「編輯」edit。
4. 在「顯示」窗格中，展開「小工具顯示設定」。

5. 選取變數並完成對話方塊。

6. 依序點選「完成」和「套用」。

7. 如要儲存修改後的資訊主頁，請按一下工具列中的「儲存」。

   資訊主頁會重新整理，如果資訊主頁上至少有一個小工具因顯示設定而隱藏，資訊主頁就會顯示橫幅。如要查看所有小工具，請按一下「顯示所有小工具」。

使用變數控管資訊主頁上至少一個小工具的顯示設定時，工具列中的變數名稱會標註 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 子句來參照變數值。所有變數的名稱都必須加上「at」符號做為前置字元，例如： @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 查詢的圖表使用以標籤為基礎的變數，請附加管道 (|)，然後按照一般語法中列出的指引操作。

使用選單導向介面建立圖表來顯示時間序列資料時，系統會將您的選取項目轉換為 Monitoring 篩選器

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 篩選查詢的圖表

如要更新圖表，讓以監控篩選器形式的查詢依附於以標籤為準的變數，請按照「一般語法」一節的指引操作。

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

下表說明監控篩選器如何解析範例變數。如先前所述，如果只使用變數的值，您必須使用規則運算式做為比較運算子：

修改已釘選的篩選器或變數

如要暫時變更資訊主頁工具列上顯示的任何篩選器值，請按一下篩選器名稱，然後輸入值或從選單中選取。

如果資訊主頁包含顯示時間序列資料的表格，您可以使用儲存格的「將資訊主頁篩選為這個值」filter_list按鈕，新增臨時篩選器或修改永久篩選器和變數。選取這個按鈕時，系統會套用新的暫時篩選器，或是更新現有篩選器或變數的值。如果資料表資料欄的標籤鍵與篩選器或變數的標籤鍵相符，系統就會更新現有篩選器和變數。

如要變更已釘選的篩選器或變數設定，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如為「App Hub」設定，請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
3. 在資訊主頁工具列中，按一下 settings「設定」。
4. 找出要修改的篩選器或變數，然後展開其定義。
5. 完成修改後，按一下「套用」。
6. 如要儲存修改後的資訊主頁，請按一下工具列中的「儲存」。

刪除已釘選的篩選器或變數

如要刪除已釘選的篩選器或變數，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在 Google Cloud 控制台的工具列中，選取您的 Google Cloud 專案。如為「App Hub」設定，請選取 App Hub 主機專案或已啟用應用程式的資料夾管理專案。
3. 在資訊主頁工具列中，按一下 settings「設定」。
4. 找出要移除的篩選器或變數，然後按一下 delete「刪除」。
5. 按一下 [套用]。
6. 如要儲存修改後的資訊主頁，請按一下工具列中的「儲存」。

後續步驟

• 探索圖表資料
• 存取特定資源的資訊主頁