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