配置 OBI 指标和追踪属性

您可以配置 OBI 如何装饰指标和追踪的属性。使用 attributes 顶层 YAML 部分来启用和配置属性的设置方式。

OBI 导出的指标文档列出了您可以为每个指标报告的属性。OBI 默认报告一些属性，并隐藏其他属性以控制基数。

对于每个指标，您可以使用 select 子部分来控制要查看的属性。这是一个 map，其中每个键是指标的名称（无论是其 OpenTelemetry 端口还是 Prometheus 端口），每个指标都有两个子属性：include 和 exclude。

• include 是要报告的属性列表。每个属性可以是名称或通配符，例如 k8s.dst.* 以包含所有以 k8s.dst 开头的属性。如果您不提供 include 列表，OBI 将报告默认属性集，有关给定指标的默认属性的更多信息，请参考 OBI 导出的指标。
• exclude 是要从 include 列表或默认属性集中删除的属性名称或通配符列表。

示例

attributes:
  select:
    obi_network_flow_bytes:
      # limit the OTEL_EBPF_network_flow_bytes attributes to only the three attributes
      include:
        - obi.ip
        - src.name
        - dst.port
    sql_client_duration:
      # report all the possible attributes but db_statement
      include: ['*']
      exclude: ['db_statement']
    http_client_request_duration:
      # report the default attribute set but exclude the Kubernetes Pod information
      exclude: ['k8s.pod.*']

此外，您还可以使用通配符作为指标名称，为一组同名指标添加和排除属性。例如：

attributes:
  select:
    http_*:
      include: ['*']
      exclude: ['http_path', 'http_route']
    http_client_*:
      # override http_* exclusion
      include: ['http_path']
    http_server_*:
      # override http_* exclusion
      include: ['http_route']

在上例中，所有名称以 http_ 或 http. 开头的指标都包含所有可能的属性，除了 http_path 和 http_route 或 http.path/http.route。http_client_* 和 http_server_* 部分覆盖了基础配置，为 HTTP 客户端指标启用了 http_path 属性，为 HTTP 服务器指标启用了 http_route。

当指标名称与多个使用通配符的定义匹配时，精确匹配优先于通配符匹配。

分布式追踪和上下文传播

YAML 部分：ebpf

您可以在 YAML 配置的 ebpf 部分或通过环境变量配置该组件。

上下文传播

OBI 会注入出站 HTTP 请求的 Traceparent 头部值，以便将任何传入的上下文传播到下游服务。此上下文传播适用于任何编程语言。

对于 TLS 加密的 HTTP 请求 (HTTPS)，OBI 在 TCP/IP 数据包级别编码 Traceparent 头部值。OBI 必须存在于通信的两端。

TCP/IP 数据包级别的编码使用 Linux Traffic Control (TC)。同样使用 TC 的 eBPF 程序必须与 OBI 正确链接。有关链接程序的更多信息，请参阅 Cilium 兼容性文档。

您可以通过将 context_propagation 设置为 headers 来禁用 TCP/IP 级别编码和 TC 程序。此上下文传播与任何 OpenTelemetry 分布式追踪库完全兼容。

上下文传播值

• all：启用 HTTP 和 IP 选项的上下文传播
• headers：仅通过 HTTP 头部启用上下文传播
• ip：仅通过 IP 选项字段启用上下文传播
• disabled：禁用追踪上下文传播

要在容器化环境（Kubernetes 和 Docker）中使用此选项，您必须：

• 将 OBI 部署为 DaemonSet，并启用主机网络访问 hostNetwork: true
• 将主机的 /sys/fs/cgroup 路径作为本地 /sys/fs/cgroup 路径进行卷挂载
• 授予 OBI 容器 CAP_NET_ADMIN 能力

不支持 gRPC 和 HTTP/2。

有关如何在 Kubernetes 中配置分布式追踪的示例，请参阅我们的 OBI 分布式追踪指南。

跟踪请求头

此选项允许 OBI 处理任何传入的 Traceparent 头部值。如果启用，当 OBI 遇到带有 Traceparent 头部值的传入服务器请求时，它将使用提供的“trace ID”来创建自己的追踪跨度。

此选项不会影响 Go 应用程序，因为 Traceparent 字段始终会被处理。

启用此选项可能会在请求量大的情况下增加性能开销。此选项仅在生成 OBI 追踪时有用；它不会影响指标。

其他属性

heuristic sql detect 选项允许 OBI 通过检查查询语句来检测 SQL 客户端请求，即使协议未直接支持。默认情况下，OBI 通过其二进制协议格式检测 SQL 客户端请求。如果您使用的数据库技术未被 OBI 直接支持，您可以启用此选项以获取数据库客户端遥测。此选项默认不启用，因为它可能导致误报，例如，当应用程序通过 TCP 连接发送 SQL 文本进行日志记录时。目前，OBI 原生支持 PostgreSQL 和 MySQL 的二进制协议。

实例 ID 装饰

YAML 部分：attributes.instance_id

OBI 会用一个唯一的实例 ID 字符串来装饰指标和追踪，以标识每个被检测的应用程序。默认情况下，OBI 使用运行 OBI 的主机名（可以是容器或 Pod 名称），后跟被检测进程的 PID。您可以在 attributes 顶层部分的 instance_id YAML 子部分中覆盖实例 ID 的构成方式。

例如

attributes:
  instance_id:
    dns: false

DNS

如果设置为 true，OBI 会尝试将本地主机名解析到网络 DNS。如果设置为 false，它会使用本地主机名。

覆盖主机名

如果设置了此选项，OBI 将使用提供的字符串作为实例 ID 的主机部分，而不是尝试解析主机名。此选项优先于 dns。

Kubernetes 装饰器

YAML 部分：attributes.kubernetes

您可以在 YAML 配置的 attributes.kubernetes 部分或通过环境变量配置该组件。

要启用此功能，您必须向 OBI Pod 提供额外的权限。请参阅 “在 Kubernetes 中运行 OBI” 页面中的 “配置 Kubernetes 元数据装饰”部分。

如果将此选项设置为 true，OBI 将使用 Kubernetes 元数据来装饰指标和追踪。如果设置为 false，OBI 将禁用 Kubernetes 元数据装饰器。如果设置为 autodetect，OBI 将尝试检测它是否在 Kubernetes 中运行，如果是，则启用元数据装饰。

例如

attributes:
  kubernetes:
    enable: true

启用 Kubernetes

如果您在 Kubernetes 环境中运行 OBI，您可以配置它以使用标准的 OpenTelemetry 标签来装饰追踪和指标

• k8s.namespace.name
• k8s.deployment.name
• k8s.statefulset.name
• k8s.replicaset.name
• k8s.daemonset.name
• k8s.node.name
• k8s.pod.name
• k8s.container.name
• k8s.pod.uid
• k8s.pod.start_time
• k8s.cluster.name
• k8s.owner.name

Kubernetes 配置路径

这是一个标准的 Kubernetes 配置环境变量。使用它来告知 OBI 在哪里找到用于与 Kubernetes 集群通信的 Kubernetes 配置。通常，您不需要更改此值。

禁用 Informer

可接受的值是一个列表，可能包含 node 和 service。

此选项允许您选择性地禁用一些 Kubernetes Informer，这些 Informer 会持续监听 Kubernetes API 以获取装饰网络指标或应用程序指标和追踪所需的元数据。

当您在非常大的集群中将 OBI 部署为 DaemonSet 时，所有 OBI 实例创建的多个 Informer 可能会使 Kubernetes API 过载。

禁用某些 Informer 会导致报告的元数据不完整，但会减少 Kubernetes API 的负载。

您不能禁用 Pods Informer。要做到这一点，请禁用整个 Kubernetes 元数据装饰。

Meta 限制本地节点

如果为 true，OBI 仅存储运行 OBI 实例的节点上的 Pod 和 Node 元数据。

此选项会减少存储元数据使用的内存，但某些指标（如网络字节或服务图指标）将不包含来自不同节点上目标 Pod 的元数据。

Informer 同步超时

这是 OBI 在开始装饰指标和追踪之前等待获取所有 Kubernetes 元数据的最长时间。如果达到此超时，OBI 将正常启动，但元数据属性可能不完整，直到所有 Kubernetes 元数据在后台更新。

Informer 重同步周期

OBI 会立即接收关于资源元数据的任何更新。此外，OBI 会以您通过此属性指定的频率定期重新同步所有 Kubernetes 元数据。较高的值会减少 Kubernetes API 服务的负载。

服务名称模板

您可以使用 Go 模板来模板化服务名称。这允许您创建条件性或扩展的服务名称。

模板可用的上下文如下：

Meta: (*informer.ObjectMeta)
  Name: (string)
  Namespace: (string)
  Labels:
    label1: lv1
    label2: lv2
  Annotations:
    Anno1: av1
    Anno2: av2
  Pod: (*PodInfo)
  ...

ContainerName: (string)

您可以在 kubecache informer.pb.go 源文件中找到完整的对象和结构。

服务名称模板示例

{{- .Meta.Namespace }}/{{ index .Meta.Labels "app.kubernetes.io/name" }}/{{ index .Meta.Labels "app.kubernetes.io/component" -}}{{ if .ContainerName }}/{{ .ContainerName -}}{{ end -}}

或

{{- .Meta.Namespace }}/{{ index .Meta.Labels "app.kubernetes.io/name" }}/{{ index .Meta.Labels "app.kubernetes.io/component" -}}

在此示例中，仅使用第一行并进行修剪，以防止服务名称中出现空格。

额外组属性

OBI 允许您使用 extra_group_attributes 配置来增强您的指标，添加自定义属性。这为您提供了灵活性，可以在指标中包含标准集以外的附加元数据。

要使用此功能，请指定组名以及您想包含在该组中的属性列表。

目前，仅支持 k8s_app_meta 组。此组包含 Kubernetes 特定元数据，如 Pod 名称、命名空间、容器名称、Pod UID 等。

配置示例

attributes:
  kubernetes:
    enable: true
  extra_group_attributes:
    k8s_app_meta: ['k8s.app.version']

在此示例中：

• 将 k8s.app.version 添加到 extra_group_attributes > k8s_app_meta 块中，会导致 k8s.app.version 标签出现在指标中。
• 您也可以在 Kubernetes manifest 中定义带有 resource.opentelemetry.io/ 前缀和 k8s.app.version 后缀的注解，这些注解会自动包含在指标中。

下表描述了默认的组属性。

下表描述了指标及其关联的组。