otelcol.processor.attributes
otelcol.processor.attributes
接受来自其他 otelcol
组件的遥测数据,并修改 span、log 或 metric 的属性。它还支持过滤和匹配输入数据,以确定是否应包含或排除属性修改。
注意
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
块,则先检查 include
属性,然后再检查 exclude
属性。
action 块
action
块配置如何修改 span、log 或 metric。
支持以下属性
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 操作相关的属性。 | 是 | |
action | string | 执行的操作类型。 | 是 | |
value | any | 要为键填充的值。 | 否 | |
pattern | string | 正则表达式模式。 | "" | 否 |
from_attribute | string | 用于填充属性值的输入数据中的属性。 | "" | 否 |
from_context | string | 用于填充属性值的上下文值。 | "" | 否 |
converted_type | string | 要将属性值转换成的类型。 | "" | 否 |
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
块提供了一个选项,可以根据 span、log 或 metric 记录的属性,包含要馈送到 action 块的数据。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
match_type | string | 控制如何解释要匹配的项。 | 是 | |
log_bodies | list(string) | LogRecord 的 body 字段必须匹配的字符串列表。 | [] | 否 |
log_severity_texts | list(string) | LogRecord 的严重性文本字段必须匹配的字符串列表。 | [] | 否 |
metric_names | list(string) | 用于匹配指标名称的字符串列表。 | [] | 否 |
services | list(string) | 用于匹配服务名称的项列表。 | [] | 否 |
span_kinds | list(string) | 用于匹配 span kind 的项列表。 | [] | 否 |
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,
log_bodies
、log_severity_texts
、log_severity
、attribute、resource 或 library 之一必须指定非空值才能进行有效配置。span_names
、span_kinds
、metric_names
和services
属性无效。 - 对于 metric,
metric_names
必须指定有效的非空值才能进行有效配置。span_names
、span_kinds
、log_bodies
、log_severity_texts
、log_severity
、services
、attribute、resource 和 library 属性无效。
如果配置包含特定于特定信号类型的过滤器,则最好仅在组件的输出中包含该信号类型。例如,如果组件的输出中配置了日志,则添加 span_names
过滤器可能会导致组件出错。
exclude 块
exclude
块提供了一个选项,可以根据 span、log 或 metric 记录的属性,排除要馈送到 action 块的数据。
注意
被
exclude
块排除的信号仍将按原样传播到下游组件。如果您不想将某些信号传播到下游组件,请考虑使用诸如 otelcol.processor.tail_sampling 之类的处理器。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
match_type | string | 控制如何解释要匹配的项。 | 是 | |
log_bodies | list(string) | LogRecord 的 body 字段必须匹配的字符串列表。 | [] | 否 |
log_severity_texts | list(string) | LogRecord 的严重性文本字段必须匹配的字符串列表。 | [] | 否 |
metric_names | list(string) | 用于匹配指标名称的字符串列表。 | [] | 否 |
services | list(string) | 用于匹配服务名称的项列表。 | [] | 否 |
span_kinds | list(string) | 用于匹配 span kind 的项列表。 | [] | 否 |
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,
log_bodies
、log_severity_texts
、log_severity
、attribute、resource 或 library 之一必须指定非空值才能进行有效配置。span_names
、span_kinds
、metric_names
和services
属性无效。 - 对于 metric,
metric_names
必须指定有效的非空值才能进行有效配置。span_names
、span_kinds
、log_bodies
、log_severity_texts
、log_severity
、services
、attribute、resource 和 library 属性无效。
如果配置包含特定于特定信号类型的过滤器,则最好仅在组件的输出中包含该信号类型。例如,如果组件的输出中配置了日志,则添加 span_names
过滤器可能会导致组件出错。
regexp 块
此块是 "regexp"
的 match_type
的可选配置。它配置了一个最近最少使用 (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 | 属性键。 | 是 | |
value | any | 要匹配的属性值。 | 否 |
如果未设置 value
,则任何值都将匹配。value
的类型可以是数字、字符串或布尔值。
resource 块
此块指定要匹配资源的项
- 可以定义多个
resource
块。 - 如果输入数据资源与至少一个
resource
块匹配,则发生匹配。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 资源键。 | 是 | |
value | any | 要匹配的资源值。 | 否 |
如果未设置 value
,则任何值都将匹配。value
的类型可以是数字、字符串或布尔值。
library 块
此块指定要匹配实现库的属性
- 可以定义多个
library
块。 - 如果 span 的实现库与至少一个
library
块匹配,则发生匹配。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
name | string | 属性键。 | 是 | |
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 | 否 |
level | string | 控制包装的收集器发出的指标的详细程度。 | "detailed" | 否 |
disable_high_cardinality_metrics
是 Grafana Alloy 等效于 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics
功能门。它会删除可能导致高基数指标的属性。例如,删除了有关 HTTP 和 gRPC 连接的指标中带有 IP 地址和端口号的属性。
注意
如果已配置,
disable_high_cardinality_metrics
仅适用于otelcol.exporter.*
和otelcol.receiver.*
组件。
level
是 Alloy 等效于 OpenTelemetry Collector 中的 telemetry.metrics.level
功能门。可能的值为 "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")
}
}
基于属性排除 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
键/值对。
请注意,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
键/值对。
请注意,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
此处理器将删除 “token” 属性,并模糊处理服务名称与 "auth.*"
匹配且 span 名称与 "login.*"
不匹配的 span 中的 “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
此处理器将删除 “token” 属性,并模糊处理日志正文与 “AUTH.*” 匹配的 span 中的 “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
块中指定级别的日志。此处理器将删除 “token” 属性,并模糊处理严重性至少为 “INFO” 的日志中的 “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
以下示例演示了如何处理严重性文本与正则表达式模式匹配的日志。此处理器将删除 “token” 属性,并模糊处理严重性与 “info” 匹配的日志中的 “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
具有可以被以下组件使用的导出
注意
连接某些组件可能不合理,或者组件可能需要进一步配置才能使连接正常工作。有关更多详细信息,请参阅链接的文档。