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 | 配置接收到的遥测数据发送的位置。 | yes |
action | action | 在传入的指标/日志/跟踪的属性上采取的操作。 | no |
include | include | 为此处理器的操作中的数据设置过滤器。 | no |
include > regexp | regexp | Regex 缓存设置。 | no |
include > attribute | attribute | 要匹配的属性列表。 | no |
include > resource | resource | 与资源匹配的项目列表。 | no |
include > library | library | 与实现库匹配的项目列表。 | no |
include > log_severity | library | 如果定义了,如何匹配日志记录的 SeverityNumber。 | no |
exclude | exclude | 为此处理器的操作之外的数据设置过滤器 | no |
exclude > regexp | regexp | Regex 缓存设置。 | no |
exclude > attribute | attribute | 要匹配的属性列表。 | no |
exclude > resource | resource | 与资源匹配的项目列表。 | no |
exclude > library | library | 与实现库匹配的项目列表。 | no |
exclude > log_severity | log_severity | 如果定义了,如何匹配日志记录的 SeverityNumber。 | no |
debug_metrics | debug_metrics | 配置此组件生成的指标,以监视其状态。 | no |
“>”符号表示更深的嵌套层级。例如,include > attribute
指的是在 include
块内部定义的 attribute
块。
如果都指定了 include
块和 exclude
块,则先检查 include
属性,然后再检查 exclude
属性。
action block
action
块配置如何修改span、日志或指标。
以下属性受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
key | 字符串 | 与操作相关的属性。 | yes | |
action | 字符串 | 执行的动作类型。 | yes | |
值 | 任何值 | 要填充到key的值。 | no | |
模式 | 字符串 | 正则表达式模式。 | "" | no |
from_attribute | 字符串 | 用于填充属性值的输入数据的属性。 | "" | no |
from_context | 字符串 | 用于填充属性值的上下文字符串。 | "" | no |
converted_type | 字符串 | 转换属性值的类型。 | "" | no |
value
数据类型必须是数字、字符串或布尔值。
action
支持的值有:
insert
:在输入数据中插入新的属性(如果该键尚不存在)。key
属性是必需的。它指定要操作哪个属性。- 必须有一个
value
、from_attribute
或from_context
属性。
update
:在输入数据中更新属性(如果该键存在)。key
属性是必需的。它指定要操作哪个属性。- 必须有一个
value
、from_attribute
或from_context
属性。
upsert
:要么在输入数据中插入一个不存在的新的属性,要么在输入数据中存在键的地方更新属性。key
属性是必需的。它指定要操作哪个属性。- 必须有一个
value
、from_attribute
或from_context
属性。value
指定要填充到key的值。from_attribute
指定从输入数据中使用的属性来填充值。如果属性不存在,则不执行任何操作。from_context
指定用于填充属性值的上下文字符串。如果键以metadata.
为前缀,则搜索接收者传输协议以查找附加信息,如gRPC元数据或HTTP标头。如果键以auth.
为前缀,则搜索由服务器验证器设置的认证信息。有关可用哪些属性的更多信息,请参阅您管道中服务器验证器的文档。如果键为client.address
,则将值设置为客户端地址。如果该键不存在,则不执行任何操作。如果键有多个值,则使用;
分隔符连接值。
hash
:对现有属性值进行散列(SHA1)。key
属性和/或pattern
属性是必需的。
extract
:使用正则表达式规则从输入键中提取值到规则中指定的目标键。如果目标键已存在,则将其覆盖。注意:与Span Processorto_attributes
设置的行为类似,现有属性作为源。key
属性是必需的。它指定要从其中提取值的属性。不更改key
的值。pattern
属性是必需的。它是从key
值的值中提取属性的regex模式。子匹配器必须命名。如果属性已存在,则将覆盖它们。
convert
:将现有属性转换到指定的类型。key
属性是必需的。它指定要操作哪个属性。converted_type
属性是必需的,且必须是int、double或string之一。
delete
:从输入数据中删除属性。key
属性和/或pattern
属性是必需的。它指定要操作哪个属性。
include block
include
块提供了一个根据跨度、日志或度量记录的属性包括数据到action块中。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
match_type | 字符串 | 控制如何对匹配项进行解释。 | yes | |
log_bodies | list(string) | 必须匹配LogRecord体字段的字符串列表。 | [] | no |
log_severity_texts | list(string) | 必须与 LogRecord 的严重性文本字段匹配的字符串列表。 | [] | no |
metric_names | list(string) | 用于匹配指标名称的字符串列表。 | [] | no |
services | list(string) | 用于匹配服务名称的项目列表。 | [] | no |
span_kinds | list(string) | 用于匹配跨度类型的项目列表。 | [] | no |
span_names | list(string) | 用于匹配跨度名称的项目列表。 | [] | no |
match_type
是必需的,并且必须设置为 "regexp"
或 "strict"
。
如果列表中至少有一个项目匹配,则会发生匹配。
还需要以下之一
- 对于跨度,必须指定以下之一以具有有效配置:
services
、span_names
、span_kinds
、属性、资源或库,并且必须用非空值设置。无效的属性是log_bodies
、log_severity_texts
、log_severity
和metric_names
。 - 对于日志,必须指定以下之一以具有有效配置:
log_bodies
、log_severity_texts
、log_severity
、属性、资源或库,并且必须用非空值设置。无效的属性是span_names
、span_kinds
、metric_names
和services
。 - 对于指标,必须指定具有有效非空值的
metric_names
以具有有效配置。无效的属性是span_names
、span_kinds
、log_bodies
、log_severity_texts
、log_severity
、services
、属性、资源和库。
如果配置中包含针对特定信号类型特定的过滤器,最好仅将特定信号类型包含在组件的输出中。例如,添加一个span_names
过滤器可能导致组件在配置组件的输出时出错。
排除块
exclude
块提供了一个选项,可以根据跨度、日志或指标记录的属性排除数据被传送到操作块。
注意
被exclude
块排除的信号将按原样传播到下游组件。如果您不希望将某些信号传播到下游组件,请考虑使用类似otelcol.processor.tail_sampling的处理器。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
match_type | 字符串 | 控制如何对匹配项进行解释。 | yes | |
log_bodies | list(string) | 必须匹配LogRecord体字段的字符串列表。 | [] | no |
log_severity_texts | list(string) | 必须与 LogRecord 的严重性文本字段匹配的字符串列表。 | [] | no |
metric_names | list(string) | 用于匹配指标名称的字符串列表。 | [] | no |
services | list(string) | 用于匹配服务名称的项目列表。 | [] | no |
span_kinds | list(string) | 用于匹配跨度类型的项目列表。 | [] | no |
span_names | list(string) | 用于匹配跨度名称的项目列表。 | [] | no |
match_type
是必需的,并且必须设置为 "regexp"
或 "strict"
。
如果列表中至少有一个项目匹配,则会发生匹配。
还需要以下之一
- 对于跨度,必须指定以下之一以具有有效配置:
services
、span_names
、span_kinds
、属性、资源或库,并且必须用非空值设置。无效的属性是log_bodies
、log_severity_texts
、log_severity
和metric_names
。 - 对于日志,必须指定以下之一以具有有效配置:
log_bodies
、log_severity_texts
、log_severity
、属性、资源或库,并且必须用非空值设置。无效的属性是span_names
、span_kinds
、metric_names
和services
。 - 对于指标,必须指定具有有效非空值的
metric_names
以具有有效配置。无效的属性是span_names
、span_kinds
、log_bodies
、log_severity_texts
、log_severity
、services
、属性、资源和库。
如果配置中包含针对特定信号类型特定的过滤器,最好仅将特定信号类型包含在组件的输出中。例如,添加一个span_names
过滤器可能导致组件在配置组件的输出时出错。
regexp块
此块是match_type
设置为"regexp"
时的可选配置。它配置了最近最少使用(LRU)缓存。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
cache_enabled | bool | 确定是否缓存匹配结果。 | false | no |
cache_max_num_entries | int | 存储匹配结果的LRU缓存的最大条目数。 | 0 | no |
启用cache_enabled
可能会使后续匹配更快。除非指定了cache_max_num_entries
,否则缓存大小无限。
如果cache_enabled
为false,则忽略cache_max_num_entries
。
属性块
此块指定要匹配的属性
- 可以定义多个
attribute
块。 - 如果指定了
attribute
,则只允许match_type
为"strict"
。 - 所有
attribute
块必须完全匹配才能发生匹配。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
key | 字符串 | 属性键 | yes | |
值 | 任何值 | 要匹配的属性值。 | no |
如果未设置value
,则任何值都将匹配。value
的类型可以是数字、字符串或布尔值。
资源块
此块指定要匹配的资源
- 可以定义多个
resource
块。 - 如果输入数据资源与至少一个
resource
块匹配,则会发生匹配。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
key | 字符串 | 资源键 | yes | |
值 | 任何值 | 要匹配的资源值。 | no |
如果未设置value
,则任何值都将匹配。value
的类型可以是数字、字符串或布尔值。
库块
这个块指定用于匹配实现库的属性。
- 可以定义多个
library
块。 - 如果跨度实现的库与至少一个
library
块匹配,则发生匹配。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
名称 | 字符串 | 属性键 | yes | |
版本 | 字符串 | 用于匹配的版本。 | null | no |
如果 version
未设置,则匹配任何版本。如果 version
设置为空字符串,则只匹配也是空字符串的库版本。
log_severity 块
此块定义了根据日志记录的 SeverityNumber 字段进行匹配的方式。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
match_undefined | bool | 是否将“undefined”严重程度的日志匹配。 | yes | |
最小值 | 字符串 | 可能匹配的最低严重程度。 | yes |
如果 match_undefined
为真,则未定义严重程度的条目将匹配。
以下表格列出了 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
块配置了一组组件,以将结果遥测数据转发到。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
日志 | list(otelcol.Consumer) | 要发送日志的消费者列表。 | [] | no |
度量 | list(otelcol.Consumer) | 要发送度量的消费者列表。 | [] | no |
跟踪 | list(otelcol.Consumer) | 要发送跟踪的消费者列表。 | [] | no |
您必须指定 output
块,但所有其参数都是可选的。默认情况下,遥测数据会被丢弃。根据需要配置 metrics
、logs
和 traces
参数,以将遥测数据发送到其他组件。
debug_metrics 块
debug_metrics
块配置了此组件生成的指标以监控其状态。
以下参数受支持:
名称 | 类型 | 描述 | 默认值 | 必须 |
---|---|---|---|---|
disable_high_cardinality_metrics | 布尔值 | 是否禁用某些高基数指标。 | true | no |
级别 | 字符串 | 控制封装收集器发出的指标的详细程度。 | "详细" | no |
disable_high_cardinality_metrics
是 Grafana Alloy 在 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics
功能门控的等价物。它删除可能引起高基数指标的属性。例如,从有关 HTTP 和 gRPC 连接的指标中删除具有 IP 地址和端口号的属性。
注意
如果配置了disable_high_cardinality_metrics
,则仅适用于otelcol.exporter.*
和otelcol.receiver.*
组件。
level
是 OpenTelemetry Collector 中 telemetry.metrics.level
功能门控的 Alloy 等价物。可能的值是 "none"
、"basic"
、"normal"
和 "detailed"
。
导出字段
以下字段被导出,其他组件可以引用
名称 | 类型 | 描述 |
---|---|---|
输入 | otelcol.Consumer | 其他组件可以使用该值将遥测数据发送到。 |
input
接受任何遥测信号(度量、日志或跟踪)的 otelcol.Consumer
数据。
组件健康
只有在不提供有效配置的情况下才会报告 otelcol.processor.attributes
为不健康。
调试信息
otelcol.processor.attributes
不公开任何特定于组件的调试信息。
示例
“操作”块的多种用法
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 = env("OTLP_ENDPOINT")
}
}
基于属性排除跨度
例如,以下跨度匹配属性且不会被处理器处理
- 跨度 1 名称: “svcB”,属性: {env: “dev”,test_request: 123,credit_card: 1234}
- 跨度 2 名称: “svcA”,属性: {env: “dev”,test_request: false}
以下跨度不匹配属性,并将处理器的操作应用于它
- 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]
}
}
基于资源排除跨度
“严格”的 match_type
表示我们必须严格匹配 resource
键/值对。
请注意,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]
}
}
基于特定库版本排除跨度
“严格”的 match_type
表示我们必须严格匹配 library
键/值对。
请注意,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]
}
}
基于正则表达式和服务的包括和排除跨度
此处理器将在服务名匹配 "auth.*"
且跨度名称不匹配 "login.*"
的跨度中删除“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]
}
}
基于正则表达式和属性的包括跨度
以下演示了如何处理匹配正则表达式模式的属性。此处理器将在“db.statement”属性与正则表达式模式匹配的跨度中混淆“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]
}
}
基于日志体正则表达式的包括跨度
此处理器将在日志体匹配“AUTH.*”的跨度中删除“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]
}
}
基于日志严重性正则表达式的包括跨度
以下演示了如何处理与 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]
}
}
基于日志严重性文本正则表达式的包括跨度
以下演示了如何处理严重文本匹配正则表达式模式的日志。此处理器将在严重性与“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
的输出可以被以下组件消耗
注意
连接某些组件可能不合理,或组件可能需要进一步配置才能正确连接。有关更多信息,请参阅链接文档。