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
包含可被以下组件消费的导出
注意
连接某些组件可能不合理,或组件可能需要进一步配置才能使连接正常工作。请参阅链接的文档了解更多详细信息。