文档 Beyla 配置 指标属性

配置 Beyla 指标和跟踪属性

Grafana Beyla 允许配置如何修饰某些指标和跟踪属性。在顶级 YAML 部分 attributes 下，您可以启用其他子部分来配置如何设置某些属性。

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

对于每个指标，您可以通过 select 子部分控制要查看哪些属性。这是一个映射，其中每个键是指标的名称（OpenTelemetry 或 Prometheus 端口中），每个指标有两个子属性：include 和 exclude。

• include 是需要报告的属性列表。每个属性可以是属性名称或通配符（例如，k8s.dst.* 表示包含所有以 k8s.dst 开头的属性）。如果未提供 include 列表，则报告默认属性集（有关给定指标的默认属性的更多信息，请参阅Beyla 导出的指标）。
• exclude 是一个属性名称/通配符列表，包含要从 include 列表（或默认属性集）中删除的属性。

示例

yaml 复制

attributes:
  select:
    beyla_network_flow_bytes:
      # limit the beyla_network_flow_bytes attributes to only the three attributes
      include:
        - beyla.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.*"]

此外，您可以使用“*”通配符作为指标名称，为具有相同名称的指标组添加和排除属性。例如：

yaml 复制

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 属性。

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

分布式跟踪和上下文传播

已弃用。请改用 context_propagation。

启用为出站 HTTP 请求注入 Traceparent 标头值，允许 Beyla 将任何传入的上下文传播到下游服务。此上下文传播支持适用于任何编程语言。

对于 TLS 加密的 HTTP 请求 (HTTPS)，Traceparent 标头值在 TCP/IP 数据包级别编码，并且要求通信的两端都存在 Beyla。

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

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

上下文传播值

为了使此选项在容器化环境（Kubernetes 和 Docker）中正常工作，必须指定以下配置：

• Beyla 必须部署为具有主机网络访问权限（hostNetwork: true）的 DaemonSet。
• 必须将主机的 /sys/fs/cgroup 路径卷挂载为本地 /sys/fs/cgroup 路径。
• 必须向 Beyla 容器授予 CAP_NET_ADMIN 能力。

目前不支持 gRPC 和 HTTP2。

有关如何在 Kubernetes 中配置分布式跟踪的示例，请参阅我们的使用 Beyla 进行分布式跟踪指南。

启用请求头的跟踪，以处理任何传入的“Traceparent”标头值。如果启用此选项，当 Beyla 遇到带有“Traceparent”标头值的传入服务器请求时，它将使用提供的“trace id”创建自己的跟踪跨度。

此选项对 Go 应用程序没有影响，在 Go 应用程序中，“Traceparent”字段始终会被处理，无需额外跟踪请求头。

在高请求量场景中启用此选项可能会增加性能开销。此选项仅在生成 Beyla 跟踪时有用，不影响 Beyla 指标的生成。

其他属性

默认情况下，Beyla 通过检测各种 SQL 客户端请求的特定二进制协议格式来检测它们。然而，SQL 数据库客户端通常以一种格式发送查询，Beyla 可以在不知道精确二进制协议的情况下检测查询语句。如果您使用的数据库技术不受 Beyla 直接支持，您可以启用此选项以获取数据库客户端遥测数据。此选项默认未启用，因为它可能导致误报，例如，应用程序通过 TCP 连接发送 SQL 文本用于日志记录。目前支持的无需此选项的协议是 Postgres 和 MySQL 二进制协议。

实例 ID 修饰

指标和跟踪使用唯一的实例 ID 字符串进行修饰，该字符串标识每个被插桩的应用。默认情况下，Beyla 使用运行 Beyla 的主机名（可以是容器或 Pod 名称），后跟被插桩进程的 PID；但您可以在顶级 sections 的 attributes 下的 instance_id YAML 子 section 中覆盖实例 ID 的组成方式。

例如：

yaml 复制

attributes:
  instance_id:
    dns: false

如果设置为 true，它将尝试通过网络 DNS 解析 Beyla 的本地主机名。如果设置为 false，它将使用本地主机名。

如果设置，实例 ID 的主机部分将使用提供的字符串，而不是尝试自动解析主机名。

此选项优先于 dns。

Kubernetes 修饰器

如果您在 Kubernetes 环境中运行 Beyla，可以将其配置为使用标准 OpenTelemetry 标签修饰跟踪和指标

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

在 YAML 中，此 section 命名为 kubernetes，位于顶级 attributes section 下。例如：

yaml 复制

attributes:
  kubernetes:
    enable: true

请务必注意，启用此功能需要事先为 Beyla Pod 提供一些额外的权限。请查阅 “在 Kubernetes 中运行 Beyla”页面中的“配置 Kubernetes 元数据修饰部分”。

如果设置为 true，Beyla 将使用 Kubernetes 元数据修饰指标和跟踪。

如果设置为 false，Kubernetes 元数据修饰器将禁用。

如果设置为 autodetect，Beyla 将尝试自动检测是否在 Kubernetes 中运行，如果是，则启用元数据修饰。

这是一个标准的 Kubernetes 配置环境变量，用于告诉 Beyla 在哪里找到 Kubernetes 配置，以便尝试与 Kubernetes 集群建立通信。

通常不需要更改此值。

接受的值是包含 node 和 service 的列表。

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

当 Beyla 在非常大的集群中以 DaemonSet 方式部署时，所有 Beyla 实例创建多个 informer 可能会导致 Kubernetes API 过载。

禁用一些 informer 会导致报告的元数据不完整，但会减轻 Kubernetes API 的负载。

Pod informer 不能禁用。为此，您应该禁用整个 Kubernetes 元数据修饰。

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

此选项减少了用于存储元数据的内存，但某些指标（例如网络字节或服务图指标）将丢失位于不同节点的源 Pod 或目标 Pod 的元数据。

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

Beyla 订阅以立即接收资源的任何元数据更新。此外，Beyla 会按此属性指定的频率定期重新同步整个 Kubernetes 元数据。

值越大，Kubernetes API 服务的负载越小。