otelcol.processor.attributes
otelcol.processor.attributes 接受来自其他 otelcol 组件的遥测数据,并修改 span、日志或指标的属性。它还支持过滤和匹配输入数据,以确定是否应将其包含或排除在属性修改之外。
注意
otelcol.processor.attributes是上游 OpenTelemetry Collectorattributes处理器的一个包装。如有必要,错误报告或功能请求将被重定向到上游仓库。
您可以通过为 otelcol.processor.attributes 组件指定不同的标签来创建多个实例。
用法
otelcol.processor.attributes "LABEL" {
output {
metrics = [...]
logs = [...]
traces = [...]
}
}参数
otelcol.processor.attributes 不支持任何参数,完全通过内部块进行配置。
块
otelcol.processor.attributes 定义中支持以下块
| 层级 | 块 | 描述 | 必填 |
|---|---|---|---|
| output | output | 配置接收到的遥测数据的发送目的地。 | 是 |
| action | action | 对传入指标/日志/链路的属性执行的操作。 | 否 |
| include | include | 包含在此处理器操作中的数据过滤器。 | 否 |
| include > regexp | regexp | 正则表达式缓存设置。 | 否 |
| include > attribute | attribute | 要匹配的属性列表。 | 否 |
| include > resource | resource | 要匹配的资源列表。 | 否 |
| include > library | library | 要匹配的实现库列表。 | 否 |
| include > log_severity | library | 如果已定义,如何匹配日志记录的 SeverityNumber。 | 否 |
| exclude | exclude | 从此处理器操作中排除的数据过滤器 | 否 |
| exclude > regexp | regexp | 正则表达式缓存设置。 | 否 |
| exclude > attribute | attribute | 要匹配的属性列表。 | 否 |
| exclude > resource | resource | 要匹配的资源列表。 | 否 |
| exclude > library | library | 要匹配的实现库列表。 | 否 |
| exclude > log_severity | log_severity | 如果已定义,如何匹配日志记录的 SeverityNumber。 | 否 |
| debug_metrics | debug_metrics | 配置此组件生成用于监控其状态的指标。 | 否 |
> 符号表示更深的嵌套级别。例如,include > attribute 指的是在 include 块内部定义的 attribute 块。
如果同时指定了 include 块和 exclude 块,则在检查 exclude 属性之前先检查 include 属性。
action 块
action 块配置如何修改 span、日志或指标。
支持以下属性
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
key | string | 操作相关的属性。 | 是 | |
action | string | 执行的操作类型。 | 是 | |
value | 任意类型 | 为 key 填充的值。 | 否 | |
pattern | string | 一个正则表达式模式。 | "" | 否 |
from_attribute | string | 用于填充属性值的输入数据中的属性。 | "" | 否 |
from_context | string | 用于填充属性值的上下文值。 | "" | 否 |
converted_type | string | 将属性值转换成的类型。 | "" | 否 |
value 数据类型必须是数字、字符串或布尔值之一。
action 支持的值为
insert:在输入数据中插入一个新属性,当 key 尚不存在时。key属性是必需的。它指定要操作的属性。value、from_attribute或from_context属性中必须有一个是必需的。
update:更新输入数据中已存在的属性。key属性是必需的。它指定要操作的属性。value、from_attribute或from_context属性中必须有一个是必需的。
upsert:在输入数据中插入一个新属性(当 key 尚不存在时),或更新输入数据中已存在的属性。key属性是必需的。它指定要操作的属性。value、from_attribute或from_context属性中必须有一个是必需的value指定要为 key 填充的值。from_attribute指定用于填充值的输入数据中的属性。如果属性不存在,则不执行任何操作。from_context指定用于填充属性值的上下文值。如果 key 以metadata.为前缀,则在接收器的传输协议中搜索额外信息,例如 gRPC Metadata 或 HTTP Headers。如果 key 以auth.为前缀,则在服务器认证器设置的认证信息中搜索值。有关可用属性的更多信息,请参阅管道中服务器认证器的文档。如果 key 是client.address,则该值将设置为客户端地址。如果 key 不存在,则不执行任何操作。如果 key 有多个值,这些值将用;分隔符连接。
hash:对现有属性值进行哈希处理 (SHA1)。key属性和/或pattern属性是必需的。
extract:使用正则表达式规则从输入 key 中提取值到规则中指定的目标 key。如果目标 key 已存在,则会被覆盖。注意:其行为类似于 Span Processor 中的to_attributes设置,将现有属性作为源。key属性是必需的。它指定要从中提取值的属性。key的值不会被更改。pattern属性是必需的。它是用于从key的值中提取属性的正则表达式模式。子匹配项必须命名。如果属性已存在,则会被覆盖。
convert:将现有属性转换为指定类型。key属性是必需的。它指定要操作的属性。converted_type属性是必需的,并且必须是 int、double 或 string 之一。
delete:从输入数据中删除一个属性。key属性和/或pattern属性是必需的。它指定要操作的属性。
include 块
include 块提供了一个选项,根据 span、日志或指标记录的属性,将数据包含在action块中进行处理。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
match_type | string | 控制如何解释要匹配的项目。 | 是 | |
log_bodies | list(string) | LogRecord 的 body 字段必须匹配的字符串列表。 | [] | 否 |
log_severity_texts | list(string) | LogRecord 的 severity text 字段必须匹配的字符串列表。 | [] | 否 |
metric_names | list(string) | 要匹配的指标名称列表。 | [] | 否 |
services | list(string) | 要匹配的服务名称列表。 | [] | 否 |
span_kinds | list(string) | 要匹配的 span 类型列表。 | [] | 否 |
span_names | list(string) | 要匹配的 span 名称列表。 | [] | 否 |
match_type 是必需的,并且必须设置为 "regexp" 或 "strict" 之一。
如果列表中的至少一项匹配,则发生匹配。
以下之一也是必需的
- 对于 span,必须指定
services、span_names、span_kinds、attribute、resource 或 library 之一,并提供非空值,配置才有效。log_bodies、log_severity_texts、log_severity和metric_names属性无效。 - 对于日志,必须指定
log_bodies、log_severity_texts、log_severity、attribute、resource 或 library 之一,并提供非空值,配置才有效。span_names、span_kinds、metric_names和services属性无效。 - 对于指标,必须指定
metric_names或resources之一,并提供有效的非空值,配置才有效。span_names、span_kinds、log_bodies、log_severity_texts、log_severity、services、attribute、resource 和 library 属性无效。
如果配置包含特定信号类型的过滤器,最好只在组件的输出中包含该信号类型。例如,如果在组件的输出中配置了日志,添加 span_names 过滤器可能会导致组件出错。
exclude 块
exclude 块提供了一个选项,根据 span、日志或指标记录的属性,将数据排除在action块处理之外。
注意
被
exclude块排除的信号仍会按原样传播到下游组件。如果您不希望将某些信号传播到下游组件,请考虑使用 otelcol.processor.tail_sampling 等处理器。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
match_type | string | 控制如何解释要匹配的项目。 | 是 | |
log_bodies | list(string) | LogRecord 的 body 字段必须匹配的字符串列表。 | [] | 否 |
log_severity_texts | list(string) | LogRecord 的 severity text 字段必须匹配的字符串列表。 | [] | 否 |
metric_names | list(string) | 要匹配的指标名称列表。 | [] | 否 |
services | list(string) | 要匹配的服务名称列表。 | [] | 否 |
span_kinds | list(string) | 要匹配的 span 类型列表。 | [] | 否 |
span_names | list(string) | 要匹配的 span 名称列表。 | [] | 否 |
match_type 是必需的,并且必须设置为 "regexp" 或 "strict" 之一。
如果列表中的至少一项匹配,则发生匹配。
以下之一也是必需的
- 对于 span,必须指定
services、span_names、span_kinds、attribute、resource 或 library 之一,并提供非空值,配置才有效。log_bodies、log_severity_texts、log_severity和metric_names属性无效。 - 对于日志,必须指定
log_bodies、log_severity_texts、log_severity、attribute、resource 或 library 之一,并提供非空值,配置才有效。span_names、span_kinds、metric_names和services属性无效。 - 对于指标,必须指定
metric_names,并提供有效的非空值,配置才有效。span_names、span_kinds、log_bodies、log_severity_texts、log_severity、services、attribute、resource 和 library 属性无效。
如果配置包含特定信号类型的过滤器,最好只在组件的输出中包含该信号类型。例如,如果在组件的输出中配置了日志,添加 span_names 过滤器可能会导致组件出错。
regexp 块
此块是 match_type 为 "regexp" 的可选配置。它配置一个最近最少使用 (LRU) 缓存。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
cache_enabled | bool | 确定是否对匹配结果进行 LRU 缓存。 | false | 否 |
cache_max_num_entries | int | 存储匹配结果的 LRU 缓存的最大条目数。 | 0 | 否 |
启用 cache_enabled 可以加快后续匹配速度。除非同时指定了 cache_max_num_entries,否则缓存大小不受限制。
如果 cache_enabled 为 false,则忽略 cache_max_num_entries。
attribute 块
此块指定要匹配的属性
- 可以定义多个
attribute块。 - 如果指定了
attribute,则只允许match_type = "strict"。 - 所有
attribute块必须完全匹配才能发生匹配。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
key | string | 属性 key。 | 是 | |
value | 任意类型 | 要匹配的属性 value。 | 否 |
如果未设置 value,则任何值都将匹配。value 的类型可以是数字、字符串或布尔值。
resource 块
此块指定要匹配的资源项目
- 可以定义多个
resource块。 - 如果输入数据资源匹配至少一个
resource块,则发生匹配。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
key | string | 资源 key。 | 是 | |
value | 任意类型 | 要匹配的资源 value。 | 否 |
如果未设置 value,则任何值都将匹配。value 的类型可以是数字、字符串或布尔值。
library 块
此块指定要匹配的实现库属性
- 可以定义多个
library块。 - 如果 span 的实现库匹配至少一个
library块,则发生匹配。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
name | string | 属性 key。 | 是 | |
version | string | 要匹配的版本。 | null | 否 |
如果 version 未设置,则任何版本都匹配。如果 version 设置为空字符串,则只匹配同样为空字符串的库版本。
log_severity 块
此块定义如何根据日志记录的 SeverityNumber 字段进行匹配。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
match_undefined | bool | 是否匹配严重性为“未定义”的日志。 | 是 | |
min | string | 允许匹配的最低严重性。 | 是 |
如果 match_undefined 为 true,则严重性未定义的条目将匹配。
下表列出了 OTel 支持的严重性。min 的值应是“日志严重性”列中的一个值。
| 日志严重性 | 严重性编号 |
|---|---|
| TRACE | 1 |
| TRACE2 | 2 |
| TRACE3 | 3 |
| TRACE4 | 4 |
| DEBUG | 5 |
| DEBUG2 | 6 |
| DEBUG3 | 7 |
| DEBUG4 | 8 |
| INFO | 9 |
| INFO2 | 10 |
| INFO3 | 11 |
| INFO4 | 12 |
| WARN | 13 |
| WARN2 | 14 |
| WARN3 | 15 |
| WARN4 | 16 |
| ERROR | 17 |
| ERROR2 | 18 |
| ERROR3 | 19 |
| ERROR4 | 20 |
| FATAL | 21 |
| FATAL2 | 22 |
| FATAL3 | 23 |
| FATAL4 | 24 |
例如,如果在 log_severity 块中的 min 属性设置为“INFO”,则 INFO、WARN、ERROR 和 FATAL 级别的日志将匹配。
output 块
output 块配置一组组件,用于将处理后的遥测数据转发到。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
logs | list(otelcol.Consumer) | 发送日志的消费者列表。 | [] | 否 |
metrics | list(otelcol.Consumer) | 发送指标的消费者列表。 | [] | 否 |
traces | list(otelcol.Consumer) | 发送链路的消费者列表。 | [] | 否 |
必须指定 output 块,但其所有参数都是可选的。默认情况下,遥测数据会被丢弃。相应地配置 metrics、logs 和 traces 参数,以将遥测数据发送到其他组件。
debug_metrics 块
debug_metrics 块配置此组件生成用于监控其状态的指标。
支持以下参数
| 名称 | 类型 | 描述 | 默认值 | 必填 |
|---|---|---|---|---|
disable_high_cardinality_metrics | boolean | 是否禁用某些高基数指标。 | true | 否 |
disable_high_cardinality_metrics 在 Grafana Alloy 中等同于 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics 功能开关。它移除了可能导致高基数指标的属性。例如,HTTP 和 gRPC 连接指标中包含 IP 地址和端口号的属性将被移除。
注意
如果配置,
disable_high_cardinality_metrics仅适用于otelcol.exporter.*和otelcol.receiver.*组件。
导出字段
以下字段已导出,可供其他组件引用
| 名称 | 类型 | 描述 |
|---|---|---|
input | otelcol.Consumer | 其他组件可用于发送遥测数据的值。 |
input 接受任何遥测信号(指标、日志或链路)的 otelcol.Consumer 数据。
组件健康状况
仅当 otelcol.processor.attributes 配置无效时,才报告其不健康。
调试信息
otelcol.processor.attributes 不暴露任何组件特定的调试信息。
示例
action 块的各种用法
otelcol.receiver.otlp "default" {
http {}
grpc {}
output {
metrics = [otelcol.processor.attributes.default.input]
logs = [otelcol.processor.attributes.default.input]
traces = [otelcol.processor.attributes.default.input]
}
}
otelcol.processor.attributes "default" {
// Inserts a new attribute "attribute1" to spans where
// the key "attribute1" doesn't exist.
// The type of `attribute1` is inferred by the configuration.
// `123` is an integer and is stored as an integer in the attributes.
action {
key = "attribute1"
value = 123
action = "insert"
}
// Inserts a new attribute with a key of "string key" and
// a string value of "anotherkey".
action {
key = "string key"
value = "anotherkey"
action = "insert"
}
// Setting an attribute on all spans.
// Any spans that already had `region` now have value `planet-earth`.
// This can be done to set properties for all traces without
// requiring an instrumentation change.
action {
key = "region"
value = "planet-earth"
action = "upsert"
}
// The following demonstrates copying a value to a new key.
// If a span doesn't contain `user_key`, no new attribute `new_user_key` is created.
action {
key = "new_user_key"
from_attribute = "user_key"
action = "upsert"
}
// Hashing existing attribute values.
action {
key = "user.email"
action = "hash"
}
// Uses the value from key `example_user_key` to upsert attributes
// to the target keys specified in the `pattern`.
// (Insert attributes for target keys that do not exist and update keys that exist.)
// Given example_user_key = /api/v1/document/12345678/update/v1
// then the following attributes will be inserted:
// new_example_user_key: 12345678
// version: v1
//
// Note: Similar to the Span Processor, if a target key already exists,
// it will be updated.
//
// Note: The regex pattern is enclosed in backticks instead of quotation marks.
// This constitutes a raw Alloy syntax string, and lets us avoid the need to escape backslash characters.
action {
key = "example_user_key"
pattern = `\/api\/v1\/document\/(?P<new_user_key>.*)\/update\/(?P<version>.*)$`
action = "extract"
}
// Converting the type of an existing attribute value.
action {
key = "http.status_code"
converted_type = "int"
action = "convert"
}
// Deleting keys from an attribute.
action {
key = "credit_card"
action = "delete"
}
output {
metrics = [otelcol.exporter.otlp.default.input]
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}
otelcol.exporter.otlp "default" {
client {
endpoint = sys.env("OTLP_ENDPOINT")
}
}根据属性排除 span
例如,以下 span 匹配属性并且不会被处理器处理
- Span1 名称:“svcB”,属性:{env: “dev”, test_request: 123, credit_card: 1234}
- Span2 名称:“svcA”,属性:{env: “dev”, test_request: false}
以下 span 不匹配属性,并且处理器操作将应用于它们
- Span3 名称:“svcB”,属性:{env: 1, test_request: “dev”, credit_card: 1234}
- Span4 名称:“svcC”,属性:{env: “dev”, test_request: false}
请注意,由于 services 属性的存在,此配置仅适用于链路信号。这就是为什么 output 块中只配置了链路。
otelcol.processor.attributes "default" {
exclude {
match_type = "strict"
services = ["svcA", "svcB"]
attribute {
key = "env"
value = "dev"
}
attribute {
key = "test_request"
}
}
action {
key = "credit_card"
action = "delete"
}
action {
key = "duplicate_key"
action = "delete"
}
output {
traces = [otelcol.exporter.otlp.default.input]
}
}根据资源排除 span
“strict” match_type 意味着我们必须严格匹配 resource 的 key/value 对。
请注意,resource 属性不用于指标,这就是为什么组件输出中没有配置指标。
otelcol.processor.attributes "default" {
exclude {
match_type = "strict"
resource {
key = "host.type"
value = "n1-standard-1"
}
}
action {
key = "credit_card"
action = "delete"
}
action {
key = "duplicate_key"
action = "delete"
}
output {
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}根据特定库版本排除 span
“strict” match_type 意味着我们必须严格匹配 library 的 key/value 对。
请注意,library 属性不用于指标,这就是为什么组件输出中没有配置指标。
otelcol.processor.attributes "default" {
exclude {
match_type = "strict"
library {
name = "mongo-java-driver"
version = "3.8.0"
}
}
action {
key = "credit_card"
action = "delete"
}
action {
key = "duplicate_key"
action = "delete"
}
output {
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}根据正则表达式和服务包含和排除 span
此处理器将移除服务名称匹配 "auth.*" 且 span 名称不匹配 "login.*" 的 span 中的“token”属性,并混淆“password”属性。
请注意,由于 services 和 span_names 属性的存在,此配置仅适用于链路信号。这就是为什么 output 块中只配置了链路。
otelcol.processor.attributes "default" {
// Specifies the span properties that must exist for the processor to be applied.
include {
// "match_type" defines that "services" is an array of regexp-es.
match_type = "regexp"
// The span service name must match "auth.*" pattern.
services = ["auth.*"]
}
exclude {
// "match_type" defines that "span_names" is an array of regexp-es.
match_type = "regexp"
// The span name must not match "login.*" pattern.
span_names = ["login.*"]
}
action {
key = "password"
action = "update"
value = "obfuscated"
}
action {
key = "token"
action = "delete"
}
output {
traces = [otelcol.exporter.otlp.default.input]
}
}根据正则表达式和属性包含 span
以下示例展示了如何处理属性匹配正则表达式模式的 span。此处理器将混淆“db.statement”属性匹配正则表达式模式的 span 中的“db.statement”属性。
otelcol.processor.attributes "default" {
include {
// "match_type" of "regexp" defines that the "value" attributes
// in the "attribute" blocks are regexp-es.
match_type = "regexp"
// This attribute ('db.statement') must exist in the span and match
// the regex ('SELECT \* FROM USERS.*') for a match.
attribute {
key = "db.statement"
value = "SELECT \* FROM USERS.*"
}
}
action {
key = "db.statement"
action = "update"
value = "SELECT * FROM USERS [obfuscated]"
}
output {
metrics = [otelcol.exporter.otlp.default.input]
logs = [otelcol.exporter.otlp.default.input]
traces = [otelcol.exporter.otlp.default.input]
}
}根据日志体正则表达式包含 span
此处理器将移除日志体匹配“AUTH.*”的 span 中的“token”属性,并混淆“password”属性。
请注意,由于 log_bodies 属性的存在,此配置仅适用于日志信号。这就是为什么 output 块中只配置了日志。
otelcol.processor.attributes "default" {
include {
match_type = "regexp"
log_bodies = ["AUTH.*"]
}
action {
key = "password"
action = "update"
value = "obfuscated"
}
action {
key = "token"
action = "delete"
}
output {
logs = [otelcol.exporter.otlp.default.input]
}
}根据日志严重性正则表达式包含 span
以下示例展示了如何处理严重性级别等于或高于 log_severity 块中指定级别的日志。此处理器将移除严重性至少为“INFO”的日志中的“token”属性,并混淆“password”属性。
请注意,由于 log_severity 属性的存在,此配置仅适用于日志信号。这就是为什么 output 块中只配置了日志。
otelcol.processor.attributes "default" {
include {
match_type = "regexp"
log_severity {
min = "INFO"
match_undefined = true
}
}
action {
key = "password"
action = "update"
value = "obfuscated"
}
action {
key = "token"
action = "delete"
}
output {
logs = [otelcol.exporter.otlp.default.input]
}
}根据日志严重性文本正则表达式包含 span
以下示例展示了如何处理严重性文本匹配正则表达式模式的日志。此处理器将移除严重性匹配“info”的日志中的“token”属性,并混淆“password”属性。
请注意,由于 log_severity_texts 属性的存在,此配置仅适用于日志信号。这就是为什么 output 块中只配置了日志。
otelcol.processor.attributes "default" {
include {
match_type = "regexp"
log_severity_texts = ["info.*"]
}
action {
key = "password"
action = "update"
value = "obfuscated"
}
action {
key = "token"
action = "delete"
}
output {
logs = [otelcol.exporter.otlp.default.input]
}
}根据指标名称包含指标
以下示例展示了如何处理名称以“counter”开头的指标。此处理器将向指标添加一个名为“important_label”,值为“label_val”的标签。如果该标签已存在,其值将被更新。
请注意,由于 metric_names 属性的存在,此配置仅适用于指标信号。这就是为什么 output 块中只配置了指标。
otelcol.processor.attributes "default" {
include {
match_type = "regexp"
metric_names = ["counter.*"]
}
action {
key = "important_label"
action = "upsert"
value = "label_val"
}
output {
metrics = [otelcol.exporter.otlp.default.input]
}
}兼容组件
otelcol.processor.attributes 可以接受来自以下组件的参数
otelcol.processor.attributes 包含可被以下组件消费的导出
注意
连接某些组件可能不合理,或组件可能需要进一步配置才能使连接正常工作。请参阅链接的文档了解更多详细信息。



