IBM Cloud Docs
使用 PromQL

使用 PromQL

使用 Prometheus 查询语言 (PromQL) 来选择和聚集 Prometheus的时间序列度量数据。

有关 PromQL的更多信息，请参阅 开放式源代码文档。

创建 PromQL 查询

在现有仪表板中为度量创建 PromQL 查询。

  1. 从 监视仪表板中，单击服务实例的 打开仪表板。
  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。 要使用 UI 中选择的时间范围，请指定 $__range。 要使用基于 UI 中选择的时间范围的时间间隔，请指定 $__interval。 随着时间范围在 UI 中发生更改，此查询中的 $__range 和 $__interval 变量将自动更新。 有关更多信息，请参阅 将仪表板作用域应用于 PromQL 查询。
    • 分段: 选择一个值以分段聚集的 PromQL 数据，例如 kubernetes_cluster_name。
  7. 单击运行查询。
  8. 通过配置任何其他 选项(例如，返回数据的单元以及显示数据的方式) 来微调结果。

应用仪表板作用域

要限定从 PromQL 查询构建的面板的作用域，必须在查询中使用作用域变量。

对于可以在查询中指定的基于时间的作用域，存在两个预定义变量。 当在 UI 中更改虚线的时间范围时，将自动更新这些变量。

  • $__range: 表示在仪表板 UI 中选择的时间范围。 例如，可以使用此变量来计算所选时间范围的平均值。
  • $__interval: 表示基于仪表板 UI 中选择的时间范围的时间间隔。 例如，您可以使用此变量来调整不同操作的时间范围，例如随时间变化的速率或平均值。

例如，假设您使用以下查询来返回所有主机的 CPU 使用率百分比:

avg_over_time(host_cpu_used_percent[$__interval])

此查询使用 $__interval 变量，该变量根据仪表板 UI 中选择的时间范围将数据范围限定为动态时间间隔。

您还可以在查询中指定自己的变量以限定其输出的范围。 例如，要进一步将先前查询的作用域限定为特定标签 (例如 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 文档。