本文档采用自动化机器翻译技术翻译。尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。若出现任何内容不一致情况，请以原始英文版本为准，且原始英文版本为权威文本。

将自定义图表添加到组件

概述

SUSE Observability 默认在大多数类型的组件上提供许多指标图表，这些组件代表 Kubernetes 资源。可以在需要时向任何组件集添加额外的指标图表。在向组件添加指标时，有两种选择：

这些指标已经被 SUSE Observability 收集，但默认情况下未在组件上可视化。
这些指标尚未被 SUSE Observability 收集，因此尚不可用。

对于选项 1，以下步骤将指导您如何创建指标绑定，以配置 SUSE Observability 将特定指标添加到特定组件集。

对于选项 2，首先确保这些指标在 SUSE Observability 中可用，通过使用 Prometheus 远程写入协议将它们发送到 SUSE Observability。只有在此之后，才能继续为组件添加指标图表。

步骤

创建指标绑定的步骤：

编写指标绑定的概要
编写拓扑查询 (STQL) 以选择组件
编写所需指标的 PromQL 查询
将正确的时间序列绑定到每个组件
在 SUSE Observability 中创建或更新指标绑定

作为示例，这些步骤将为 Kubernetes 部署的 Replica counts 添加指标绑定。这只是一个示例，这个指标绑定在 SUSE Observability 中默认已经存在。

编写指标绑定的概要

创建一个名为 metric-bindings.yaml 的新 YAML 文件，并将此 YAML 模板添加到其中以创建您自己的指标绑定。在您最喜欢的代码编辑器中打开它，以便在本指南中进行更改。最后将使用 SUSE Observability CLI 来创建和更新 SUSE Observability 中的指标绑定。

nodes:
- _type: MetricBinding
  chartType: line
  enabled: true
  tags: {}
  unit:
  name:
  description:
  priority:
  identifier: urn:custom:metric-binding:...
  queries:
    - expression:
      alias:
  scope:
  layout:
    metricPerspective:
      tab:
      section:
      weight:
    componentSummary:
      weight:

此模板中的字段包括：

_type：SUSE Observability需要知道这是一个指标绑定，因此值始终需要为`MetricBinding`。
chartType：SUSE Observability将支持不同的图表类型（line、bar`等），目前仅支持`line。
enabled：设置为`false`以保留指标绑定，但不向用户显示。
tags：将用于在用户界面中组织指标，可以使用`{}`留空。
unit：查询或查询返回的时间序列中值的单位，用于渲染图表的Y轴。请参阅支持的单元参考以获取所有单元。
name：指标绑定的名称。
description：可选描述，在名称上悬停时显示。
priority：[已弃用] HIGH、MEDIUM`或`LOW`之一。组件上指标的主要排序顺序（按此处提到的顺序），次要排序顺序为`name。
identifier：一个URN（通用资源标识符），用作指标绑定的唯一标识符。它必须以`urn:custom:metric-binding:`开头，其余部分为自由格式，只要在所有指标绑定中是唯一的。
queries：要在图表中显示的指标绑定的查询列表（另请参见以下部分）。
scope：指标绑定的拓扑范围，一个选择将显示此指标绑定的组件的拓扑查询。
layout：如何在不同的视角视图中分组图表，例如在指标视角上。

首先填写所有已知的部分（以部署副本计数为例）。

_type: MetricBinding
chartType: line
enabled: true
tags: {}
unit: short
name: Replica counts
priority: MEDIUM
identifier: urn:custom:metric-binding:my-deployment-replica-counts
queries:
  - expression:
    alias:
scope:

查询和范围部分将在接下来的步骤中填写。请注意，使用的单位是`short`，这将简单地呈现一个数值。如果您还不确定度量的单位，可以保持开放状态，并在编写PromQL查询时决定正确的单位。

编写拓扑查询

使用拓扑视图，http://your-instance/#/views/explore,并选择需要显示新度量的组件。基本视图和高级视图都可以用于进行选择。用于度量绑定的拓扑选择中最常见的字段是`type`（组件类型）和`label`（选择所有标签）。例如，对于部署：

type = "deployment" and label = "stackpack:kubernetes"

类型过滤器选择所有部署，而标签过滤器仅选择由Kubernetes堆栈包创建的组件（标签名称为`stackpack`，标签值为`kubernetes`）。后者也可以省略，以获得相同的结果。

切换到高级模式以复制结果拓扑查询，并将其放入度量绑定的`scope`字段中。

度量绑定仅支持查询过滤器，不支持查询函数，如`withNeighborsOf`，并且无法使用。

编写PromQL查询

转到您的 SUSE Observability 实例的度量探索器，http://your-instance/#/metrics,并使用它查询感兴趣的度量。探索器具有度量、标签、标签值的自动补全功能，还包括PromQL函数和运算符，以帮助您。从短时间范围开始，例如一小时，以获得最佳结果。

对于副本的总数，请使用`kubernetes_state_deployment_replicas`度量。为了使此度量的图表对时间序列数据具有代表性，请扩展查询以使用`${__interval}`参数进行聚合：

max_over_time(kubernetes_state_deployment_replicas[${__interval}])

在这种特定情况下，使用`max_over_time`以确保图表始终显示任何给定时间的最高副本数。对于较长的时间范围，这意味着短暂的副本下降不会被显示，为了强调最低副本数，请使用`min_over_time`。

将查询复制到度量绑定的`queries`字段中第一个条目的`expression`属性。将 Total replicas 用作别名。这是将在图表图例中显示的名称。

在 SUSE Observability 中，指标图表的大小会自动决定图表中显示的指标的粒度。可以调整 PromQL 查询，以最佳利用此行为，从而获得指标的代表性图表。撰写 PromQL 以用于图表详细解释了这一点。

将正确的时间序列绑定到每个组件。

所有字段填写完整的指标绑定：

_type: MetricBinding
chartType: line
enabled: true
tags: {}
unit: short
name: Replica counts
priority: MEDIUM
identifier: urn:custom:metric-binding:my-deployment-replica-counts
queries:
  - expression: max_over_time(kubernetes_state_deployment_replicas[${__interval}])
    alias: Total replicas
scope: type = "deployment" and label = "stackpack:kubernetes"

在 SUSE Observability 中创建它并查看部署组件上的 "副本计数" 图表会得到意外的结果。图表显示所有部署的副本计数。从逻辑上讲，人们会期望只有 1 个时间序列：该特定部署的副本计数。

要修复此问题，请使用组件的信息使 PromQL 查询针对特定组件。根据足够的指标标签进行过滤，以仅选择该组件的特定时间序列。这就是将正确的时间序列绑定到组件的 "绑定"。对于任何有经验制作 Grafana 仪表板的人来说，这类似于在仪表板上用于查询的带参数的仪表板。让我们将指标绑定中的查询更改为：

max_over_time(kubernetes_state_deployment_replicas{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}", deployment="${name}"}[${__interval}])

现在 PromQL 查询根据 3 个标签进行过滤，cluster_name、namespace 和 deployment。而不是为这些标签指定实际值，而是使用对组件字段的变量引用。在这种情况下，使用标签 cluster-name 和 namespace，通过 ${tags.cluster-name} 和 ${tags.namespace} 引用。此外，组件名称通过`${name}`引用。

支持的变量引用包括：

任何组件标签，使用`${tags.<label-name>}`
组件名称，使用`${name}`

集群名称、名称空间以及组件类型和名称的组合通常足以从Kubernetes中选择特定组件的指标。这些标签或类似标签通常在大多数指标和组件上可用。

在 SUSE Observability 中创建或更新指标绑定

使用 SUSE Observability CLI 在 SUSE Observability 中创建指标绑定。确保`metric-bindings.yaml`已保存并且看起来像这样：

nodes:
- _type: MetricBinding
  chartType: line
  enabled: true
  tags: {}
  unit: short
  name: Replica counts
  priority: MEDIUM
  identifier: urn:custom:metric-binding:my-deployment-replica-counts
  queries:
    - expression: max_over_time(kubernetes_state_deployment_replicas{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}", deployment="${name}"}[${__interval}])
      alias: Total replicas
  scope: type = "deployment" and label = "stackpack:kubernetes"

使用SUSE Observability CLI创建指标绑定：

sts settings apply -f metric-bindings.yaml

通过在 SUSE Observability 中打开部署的指标视角验证结果。如果您对结果不满意，只需在YAML文件中更改指标绑定，然后再次运行命令以更新它。节点列表支持添加多个指标绑定。只需按照之前的步骤向YAML数组中添加另一个指标绑定条目。

标识符用作指标绑定的唯一键。更改标识符将创建一个新的指标绑定，而不是更新现有的指标绑定。

`sts settings`命令有更多选项，例如它可以列出所有指标绑定：

sts settings list --type MetricBinding

最后，要删除指标绑定，请使用

sts settings delete --ids <id>

此命令中的 <id> 不是标识符，而是 Id 输出中 sts settings list 列的数字。

推荐的工作方式是将指标绑定（以及在 SUSE Observability 中创建的任何其他自定义资源）存储为 YAML 文件，并放在 Git 储存库中。从那里，可以手动应用更改，或者通过在 CI/CD 系统中使用 SUSE Observability CLI 完全自动化，例如 GitHub Actions 或 GitLab Pipelines。

其他选项

图表中有超过 1 个时间序列。

指标绑定只有 1 个单元（它绘制在图表的 y 轴上）。因此，您应该仅将产生相同单元的时间序列的查询组合在 1 个指标绑定中。有时可能可以转换单元。例如，处理器使用率可能以毫核或核的形式报告，毫核可以通过乘以 1000 转换为核，如此 (<original-query>) * 1000。

有 2 种方法可以在单个指标绑定中获取超过 1 个时间序列，并因此显示在一个图表中：

编写一个返回单个组件多个时间序列的PromQL查询
向指标绑定添加更多PromQL查询

对于第一个选项，下一节中给出了一个示例。第二个选项对于比较相关指标可能很有用。一些典型的用例：

比较总副本数与期望和可用副本数
资源使用情况：限制、请求和在单个图表中的使用情况

要向指标绑定添加更多查询，只需重复步骤 3. 和 4.，并将查询作为查询列表中的额外条目添加。对于部署副本计数，有几个相关指标可以包含在同一图表中：

nodes:
- _type: MetricBinding
  chartType: line
  enabled: true
  tags: {}
  unit: short
  name: Replica counts
  priority: MEDIUM
  identifier: urn:custom:metric-binding:my-deployment-replica-counts
  queries:
    - expression: max_over_time(kubernetes_state_deployment_replicas{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}", deployment="${name}"}[${__interval}])
      alias: Total replicas
    - expression: max_over_time(kubernetes_state_deployment_replicas_available{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}",  deployment="${name}"}[${__interval}])
      alias: Available - ${cluster_name} - ${namespace} - ${deployment}
    - expression: max_over_time(kubernetes_state_deployment_replicas_unavailable{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}",  deployment="${name}"}[${__interval}])
      alias: Unavailable - ${cluster_name} - ${namespace} - ${deployment}
    - expression: min_over_time(kubernetes_state_deployment_replicas_desired{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}",  deployment="${name}"}[${__interval}])
      alias: Desired - ${cluster_name} - ${namespace} - ${deployment}
  scope: type = "deployment" and label = "stackpack:kubernetes"

在别名中使用指标标签。

当单个查询返回每个组件多个时间序列时，这将在图表中显示为多条线。但在图例中，它们将使用相同的别名。为了能够区分不同的时间序列，别名可以使用 ${label} 语法包含对指标标签的引用。例如，这里是一个关于 pod 上 "容器重启" 指标的指标绑定，请注意一个 pod 可以有多个容器：

type: MetricBinding
chartType: line
enabled: true
id: -1
identifier: urn:custom:metric-binding:my-pod-restart-count
name: Container restarts
priority: MEDIUM
queries:
- alias: Restarts - ${container}
  expression: max by (cluster_name, namespace, pod_name, container) (kubernetes_state_container_restarts{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}", pod_name="${name}"})
scope: (label = "stackpack:kubernetes" and type = "pod")
unit: short

请注意，alias 引用了该指标的 container 标签。确保查询结果中存在该标签，当标签缺失时，${container} 将作为原样文本呈现，以帮助故障排除。

布局

每个组件可以与各种技术或协议相关联，例如 k8s、网络、运行时（例如 JVM）、协议（HTTP、AMQP）等。因此，每个组件可以显示多种不同的指标。为了更易于阅读，SUSE Observability 可以将这些图表组织成选项卡和部分。要在特定的选项卡或部分中显示图表 (MetricBinding)，您需要配置布局属性。任何没有指定布局的 MetricsBinding 将显示在名为 Other 的选项卡和部分中。

以下是一个示例配置：

layout:
  metricPerspective:
    tab: Kubernetes Pod
    section: Performance
    weight: 2
  componentSummary:
    weight: 2

字段：

layout.metricPerspective - 定义在 Metrics Perspective 上显示的指标。指标被分组到选项卡中，然后是部分。
layout.metricPerspective.tab - 选项卡名称。选项卡按字母顺序排序。
layout.metricPerspective.section - 部分名称。部分按字母顺序排序。
layout.metricPerspective.weight - 部分中的指标主要按权重（升序）排序，其次按名称（字母顺序）排序。
layout.componentSummary - 指定在选择组件时在 Components details 侧边栏中显示的指标。仅当定义了此属性时，图表才会出现。
layout.componentSummary.weight - 这代表了图表的权重。图表按权重升序排序，然后显示前三个图表。