IBM Cloud Docs
使用 PromQL

使用 PromQL

使用 Prometheus 查詢語言 (PromQL) 來選取及聚集 Prometheus的時間序列度量資料。

如需 PromQL的相關資訊，請參閱 開放程式碼文件。

建立 PromQL 查詢

在現有儀表板中建立度量值的 PromQL 查詢。

  1. 從 Monitoring 儀表板中，按一下服務實例的 開啟儀表板。
  2. 從 儀表板中，選取包含您要查詢之度量值的儀表板。
  3. 對於儀表板中的一個畫面，按一下 編輯 圖示。
  4. 選取 PromQL 查詢類型。
  5. 在查詢表單中，輸入 顯示 資料，例如查詢名稱和時間序列名稱。
  6. 輸入 PromQL 查詢，例如 avg(avg_over_time(host_cpu_used_percent[$__interval])) by(kubernetes_cluster_name)。 在查詢中指定下列欄位:
    • 度量: 指定您要查詢的度量，例如 host_cpu_used_percent。 附註: 表格上產生的值是最新度量值。
    • 時間範圍: 指定時間範圍或時間間隔，例如 5m。 若要使用在使用者介面中選取的時間範圍，請指定 $__range。 若要使用基於使用者介面中所選取時間範圍的時間間隔，請指定 $__interval。 此查詢中的 $__range 及 $__interval 變數會在使用者介面中變更時間範圍時自動更新。 如需相關資訊，請參閱 將儀表板範圍套用至 PromQL 查詢。
    • 分段: 選擇一個值來分段聚集的 PromQL 資料，例如 kubernetes_cluster_name。
  7. 按一下執行查詢。
  8. 透過配置任何其他 _選項_來細部調整結果，例如傳回資料的單位以及資料的顯示方式。

套用儀表板範圍

若要設定從 PromQL 查詢建置的畫面範圍，您必須在查詢內使用 scope 變數。

您可以在查詢中指定的時間型範圍有兩個預先定義的變數。 當使用者介面中虛線的時間範圍變更時，這些變數會自動更新。

  • $__range: 代表在儀表板使用者介面中選取的時間範圍。 例如，您可以使用此變數來計算所選時間範圍的平均值。
  • $__interval: 代表基於儀表板使用者介面中所選取時間範圍的間隔。 例如，您可以使用此變數來調整不同作業的時間範圍，例如隨時間變化的比率或平均值。

例如，假設您使用下列查詢來傳回所有主機的 CPU 使用率百分比:

avg_over_time(host_cpu_used_percent[$__interval])

此查詢使用 $__interval 變數，該變數會根據在儀表板使用者介面中選取的時間範圍，將資料範圍設定為動態時間間隔。

您也可以在查詢中指定您自己的變數，以設定其輸出範圍。 例如，若要進一步將先前查詢的範圍限定為特定標籤 (例如 hostname)，您必須先 在儀表板層次定義範圍變數。 然後，您可以在查詢中指定該變數:

avg_over_time(host_cpu_used_percent{host_name=$hostname}[$__interval])

使用標籤

當您執行 PromQL 查詢時，會傳回最少一組標籤的資料。 若要新增更多標籤 (例如叢集名稱)，請使用向量比對作業。

Prometheus 會傳回值為 1 且具有數個 labels.Joining 資訊度量值與非資訊度量值的標籤可提供有用的見解，例如應用程式中的度量值。 您可以使用向量比對作業 (類似於 SQL 結合)，將資訊標籤新增至度量值資料。

範例: 依叢集過濾應用程式度量值

在此範例中，應用程式傳回的度量值會依叢集過濾。 PromQL 會聚集叢集的該度量值，方法是在範圍中只選取一個叢集。

sum (myapp_metric * on (container_id) kube_pod_container_info{cluster=$cluster})

此查詢:

  • 僅根據 cluster 標籤及特定時間序列，過濾特定叢集 (設為儀表板變數的 $cluster) 的 kube_pod_container_info 資訊度量值。
  • 當 container_id 標籤具有相同的值時，將 myapp_metric 非資訊度量值與已過濾的 kube_pod_container_info 資訊度量值進行比對。 值會相乘，但因為資訊度量值的值為 1，所以結果保持不變。 叢集標籤會新增至產生的資料。
  • 使用 sum 函數聚集值 myapp_metric 的時間序列，並傳回結果。

範例: 過濾帳戶及區域所使用的平均 CPU

在此範例中，計算特定 IBM Cloud 帳戶及地區的平均 CPU 使用率 (百分比)。

avg by(region,account_id) (host_cpu_used_percent * on (host_mac) group_left(region,account_id) sysdig_cloud_provider_info{account_id=~$account, region=~$region})

此查詢:

  • 僅針對根據 region 和 account_id 標籤設定為儀表板變數的特定區域 ($region) 和帳戶 ($account) 過濾 sysdig_cloud_provider_info 資訊度量值。
  • 當 host_mac 標籤具有相同的值時，將 host_cpu_used_percent 非資訊度量值與已過濾的 sysdig_cloud_provider_info 資訊度量值進行比對。 值會相乘，但因為資訊度量值的值為 1，所以結果保持不變。 區域和帳戶標籤會新增至產生的資料。
  • 依帳戶和地區計算新度量值的平均值。

cURL 範例，用於擷取最新度量值

若要取得度量的最新值，請僅指定度量名稱。 會傳回不超過 5 分鐘之前產生的最新值。

例如，若要取得 host_cpu_used_percent 的最新值:

curl <SYSDIG_REST_API_ENDPOINT>/prometheus/api/v1/query?query=sysdig_host_cpu_used_percent -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "SysdigTeamID: $TEAM_ID" -H "content-type: application/json"

其中

  • <SYSDIG_REST_API_ENDPOINT> 指出 REST API 呼叫所設定的端點目標。 如需相關資訊，請參閱 監視 REST API 端點。 例如，us-south 中可用實例的公用端點如下: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 來傳遞多個標頭。

    Authorization 和 IBMInstanceID 是鑑別所需的標頭。

    SysdigTeamID 是選用項目。 當您指定此標頭時，會將要求限制為指定團隊可用的資料和資源。

    若要取得 AUTH_TOKEN 及 GUID，請參閱 IAM 記號的標頭。

所有儀表板都支援完整 PromQL API。 如需 PromQL可能之功能的相關資訊，請參閱 Prometheus 文件。