otelcol 处理器 Span

otelcol.processor.span 接受来自其他 otelcol 组件的跟踪遥测数据，并修改Span的名称和属性。它还支持过滤输入数据以确定是否应包括或排除该处理器。

您可以通过提供不同的标签来指定多个 otelcol.processor.span 组件。

用法

otelcol.processor.span "LABEL" {
  output {
    traces  = [...]
  }
}

参数

otelcol.processor.span 不支持任何参数，它完全通过内嵌块进行配置。

块

支持在 otelcol.processor.span 的定义内部以下块：

符号 `>` 表示更深层次的嵌套。例如，`include > attribute` 指的是在 `include` 块内定义的 `attribute` 块。

如果指定了 `include` 块和 `exclude` 块，则先检查 `include` 属性，然后再检查 `exclude` 属性。

name块

`name` 块配置如何重命名Span并添加属性。

支持以下属性：

首先应用 from_attributes 规则，然后应用to-attributes。这两个字段中至少必须设置一个。

from_attributes 表示从其中提取值以生成新span名称的属性键

• 在重命名span时，span中必须包含所有属性键。如果span中缺少任何属性，则将不会进行重命名。
• 根据配置中指定的 from_attributes 的顺序构造新的span名称。

separator 是用于在新的span名称中分隔属性值的字符串。如果没有设置值，则在属性值之间不会使用分隔符。separator 仅与 from_attributes 一起使用；它不与 to-attributes 一起使用。

to_attributes块

to_attributes 块配置如何从span名称创建属性。

支持以下属性：

rules 列表中的每个规则都是一个正则表达式模式字符串。

1. 将span名称与列表中的每个正则表达式进行匹配。
2. 如果匹配，则将正则表达式的所有命名子表达式作为属性提取出来并添加到span中。
3. 子表达式名称成为属性名称，子表达式匹配的部分成为属性值。
4. 将span名称中的匹配部分替换为提取的属性名称。
5. 如果属性已在span中存在，则将覆盖它们。
6. 按照指定的顺序重复对规则中的所有规则进行操作。
7. 每个后续规则作用在处理上一个规则后的输出span名称上。

break_after_match 指定是否在第一个匹配后停止规则处理。如果设置为 false，则将向修改后的span名称继续进行规则处理。

status块

status 块指定了应为此span设置的状态。

支持以下属性：

支持 code 的值有

• Ok
• Error
• Unset

仅在将 code 设置为 Error 时，才应指定 description。

include块

include 块提供了基于span属性包含数据到 name 和 status 块的选项。

支持以下参数

match_type 是必需的，必须设置为 "regexp" 或 "strict"。

如果列表中的至少一个项目匹配，则发生匹配。

必须指定具有非空值的一个参数 services、 span_names、 span_kinds、 attribute、 resource 或 library 才能进行有效的配置。

exclude块

exclude 块提供了基于span属性排除数据到 name 和 status 块的选项。

支持以下参数

match_type 是必需的，必须设置为 "regexp" 或 "strict"。

如果列表中的至少一个项目匹配，则发生匹配。

必须指定具有非空值的一个参数 services、 span_names、 span_kinds、 attribute、 resource 或 library 才能进行有效的配置。

regexp块

此块是 match_type 为 "regexp" 的可选配置。它配置了一个最少最近使用（LRU）缓存。

支持以下参数

启用cache_enabled可能使后续匹配更快。除非也指定了cache_max_num_entries，否则缓存大小不受限制。

如果cache_enabled为false，则忽略cache_max_num_entries。

属性块

此块指定了要匹配的属性。

• 可以定义多个attribute块。
• 如果指定了attribute，则只允许match_type = "strict"。
• 匹配发生时，必须完全匹配所有attribute块。

支持以下参数

如果未设置value，则任何值都将匹配。类型可以是数字、字符串或布尔值。

资源块

此块指定了与资源匹配的项目。

• 可以定义多个resource块。
• 如果输入数据资源与至少一个resource块匹配，则发生匹配。

支持以下参数

如果未设置value，则任何值都将匹配。值的类型可以是数字、字符串或布尔值。

库块

此块指定了与实现库匹配的属性。

• 可以定义多个library块。
• 如果跨度实现库与至少一个library块匹配，则发生匹配。

支持以下参数

如果未设置version，则任何版本都将匹配。如果将version设置为空字符串，则它仅匹配库版本，也是一个空字符串。

输出块

output块配置了一系列组件，将这些结果遥测数据转发到。

支持以下参数

您必须指定output块，但所有其参数都是可选的。默认情况下，遥测数据会被丢弃。根据需要配置traces参数，将遥测数据发送到其他组件。

调试指标块

debug_metrics块配置了该组件生成的指标以监控其状态。

支持以下参数

disable_high_cardinality_metrics是Grafana Alloy对应于OpenTelemetry Collector中的telemetry.disableHighCardinalityMetrics功能开关。它移除了可能导致高基数指标的属性。例如，从HTTP和gRPC连接的指标中移除了包含IP地址和端口号的属性。

level是Grafana Alloy对应于OpenTelemetry Collector中的telemetry.metrics.level功能开关。可能的值有"none"、"basic"、"normal"和"detailed"。

导出行列

以下字段被导出且可以被其他组件引用

input接受用于跟踪遥测信号的OTLP格式的otelcol.Consumer数据。不支持日志和指标。

组件健康状态

otelcol.processor.attributes只有在其配置无效时才会报告为不健康。

调试信息

otelcol.processor.attributes不会公开任何特定于组件的调试信息。

例子

从属性值创建新的跨度名称

本例根据属性值 db.svc、operation 和 id（依次）创建一个新的 span 名称，并以值 :: 分隔。需要指定所有属性键才能让处理器重命名 span。

otelcol.processor.span "default" {
  name {
    separator        = "::"
    from_attributes  = ["db.svc", "operation", "id"]
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

对于以下属性键/值对 span，上述配置将 span 名称更改为 "location::get::1234"。

json 复制

{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

对于以下属性键/值对 span，上述配置不会更改 span 名称。这是因为未设置属性键 operation。

json 复制

{
  "db.svc": "location",
  "id": "1234"
}

从属性值创建新的 span 名称（无分隔符）

otelcol.processor.span "default" {
  name {
    from_attributes = ["db.svc", "operation", "id"]
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

对于以下属性键/值对 span，上述配置将 span 名称更改为 "locationget1234"。

json 复制

{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

重命名 span 名称并添加属性

以下配置的示例输入和输出

1. 假设输入 span 名称是 /api/v1/document/12345678/update。
2. span 名称将更改为 /api/v1/document/{documentId}/update。
3. 将添加一个新的属性 "documentId"="12345678"。

otelcol.processor.span "default" {
  name {
    to_attributes {
      rules = ["^\\/api\\/v1\\/document\\/(?P<documentId>.*)\\/update$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

过滤、重命名 span 名称并添加属性

本例在 span 满足以下属性时将其名称更改为 {operation_website} 并添加属性 {Key: operation_website, Value: <原 span 名称> }：

• 服务名称包含单词 banks。
• span 名称包含字符串中的任何位置的 /。
• span 名称不是 donot/change。

otelcol.processor.span "default" {
  include {
    match_type = "regexp"
    services   = ["banks"]
    span_names = ["^(.*?)/(.*?)$"]
  }
  exclude {
    match_type = "strict"
    span_names = ["donot/change"]
  }
  name {
    to_attributes {
      rules = ["(?P<operation_website>.*?)$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

设置状态

本例将 span 的状态更改为“错误”并设置错误描述。

otelcol.processor.span "default" {
  status {
    code        = "Error"
    description = "some additional error description"
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

基于属性值设置状态

本例仅在属性 http.status_code 等于 400 时设置状态为成功。

otelcol.processor.span "default" {
  include {
    match_type = "strict"
    attribute {
      key   = "http.status_code"
      value = 400
    }
  }
  status {
    code = "Ok"
  }

  output {
      traces = [otelcol.exporter.otlp.default.input]
  }
}

兼容组件

otelcol.processor.span 可以接受来自以下组件的参数

• 导出 OpenTelemetry otelcol.Consumer 的组件

otelcol.processor.span 拥有可以由以下组件消耗的导出

• 消耗 OpenTelemetry otelcol.Consumer 的组件