菜单
文档breadcrumb arrow Grafana Alloybreadcrumb arrow 参考breadcrumb arrow 组件breadcrumb arrow otelcolbreadcrumb arrow otelcol.processor.attributes
开源

otelcol.processor.attributes

otelcol.processor.attributes 接受来自其他 otelcol 组件的遥测数据,并修改 span、日志或指标的属性。它还支持过滤和匹配输入数据,以确定是否应将其包含或排除在属性修改之外。

注意

otelcol.processor.attributes 是上游 OpenTelemetry Collector attributes 处理器的一个包装。如有必要,错误报告或功能请求将被重定向到上游仓库。

您可以通过为 otelcol.processor.attributes 组件指定不同的标签来创建多个实例。

用法

alloy
otelcol.processor.attributes "LABEL" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

参数

otelcol.processor.attributes 不支持任何参数,完全通过内部块进行配置。

otelcol.processor.attributes 定义中支持以下块

层级描述必填
outputoutput配置接收到的遥测数据的发送目的地。
actionaction对传入指标/日志/链路的属性执行的操作。
includeinclude包含在此处理器操作中的数据过滤器。
include > regexpregexp正则表达式缓存设置。
include > attributeattribute要匹配的属性列表。
include > resourceresource要匹配的资源列表。
include > librarylibrary要匹配的实现库列表。
include > log_severitylibrary如果已定义,如何匹配日志记录的 SeverityNumber。
excludeexclude从此处理器操作中排除的数据过滤器
exclude > regexpregexp正则表达式缓存设置。
exclude > attributeattribute要匹配的属性列表。
exclude > resourceresource要匹配的资源列表。
exclude > librarylibrary要匹配的实现库列表。
exclude > log_severitylog_severity如果已定义,如何匹配日志记录的 SeverityNumber。
debug_metricsdebug_metrics配置此组件生成用于监控其状态的指标。

> 符号表示更深的嵌套级别。例如,include > attribute 指的是在 include 块内部定义的 attribute 块。

如果同时指定了 include 块和 exclude 块,则在检查 exclude 属性之前先检查 include 属性。

action 块

action 块配置如何修改 span、日志或指标。

支持以下属性

名称类型描述默认值必填
keystring操作相关的属性。
actionstring执行的操作类型。
value任意类型为 key 填充的值。
patternstring一个正则表达式模式。""
from_attributestring用于填充属性值的输入数据中的属性。""
from_contextstring用于填充属性值的上下文值。""
converted_typestring将属性值转换成的类型。""

value 数据类型必须是数字、字符串或布尔值之一。

action 支持的值为

  • insert:在输入数据中插入一个新属性,当 key 尚不存在时。

    • key 属性是必需的。它指定要操作的属性。
    • valuefrom_attributefrom_context 属性中必须有一个是必需的。
  • update:更新输入数据中已存在的属性。

    • key 属性是必需的。它指定要操作的属性。
    • valuefrom_attributefrom_context 属性中必须有一个是必需的。
  • upsert:在输入数据中插入一个新属性(当 key 尚不存在时),或更新输入数据中已存在的属性。

    • key 属性是必需的。它指定要操作的属性。
    • valuefrom_attributefrom_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_typestring控制如何解释要匹配的项目。
log_bodieslist(string)LogRecord 的 body 字段必须匹配的字符串列表。[]
log_severity_textslist(string)LogRecord 的 severity text 字段必须匹配的字符串列表。[]
metric_nameslist(string)要匹配的指标名称列表。[]
serviceslist(string)要匹配的服务名称列表。[]
span_kindslist(string)要匹配的 span 类型列表。[]
span_nameslist(string)要匹配的 span 名称列表。[]

match_type 是必需的,并且必须设置为 "regexp""strict" 之一。

如果列表中的至少一项匹配,则发生匹配。

以下之一也是必需的

  • 对于 span,必须指定 servicesspan_namesspan_kindsattributeresourcelibrary 之一,并提供非空值,配置才有效。log_bodieslog_severity_textslog_severitymetric_names 属性无效。
  • 对于日志,必须指定 log_bodieslog_severity_textslog_severityattributeresourcelibrary 之一,并提供非空值,配置才有效。span_namesspan_kindsmetric_namesservices 属性无效。
  • 对于指标,必须指定 metric_namesresources 之一,并提供有效的非空值,配置才有效。span_namesspan_kindslog_bodieslog_severity_textslog_severityservicesattributeresourcelibrary 属性无效。

如果配置包含特定信号类型的过滤器,最好只在组件的输出中包含该信号类型。例如,如果在组件的输出中配置了日志,添加 span_names 过滤器可能会导致组件出错。

exclude 块

exclude 块提供了一个选项,根据 span、日志或指标记录的属性,将数据排除在action块处理之外。

注意

exclude 块排除的信号仍会按原样传播到下游组件。如果您不希望将某些信号传播到下游组件,请考虑使用 otelcol.processor.tail_sampling 等处理器。

支持以下参数

名称类型描述默认值必填
match_typestring控制如何解释要匹配的项目。
log_bodieslist(string)LogRecord 的 body 字段必须匹配的字符串列表。[]
log_severity_textslist(string)LogRecord 的 severity text 字段必须匹配的字符串列表。[]
metric_nameslist(string)要匹配的指标名称列表。[]
serviceslist(string)要匹配的服务名称列表。[]
span_kindslist(string)要匹配的 span 类型列表。[]
span_nameslist(string)要匹配的 span 名称列表。[]

match_type 是必需的,并且必须设置为 "regexp""strict" 之一。

如果列表中的至少一项匹配,则发生匹配。

以下之一也是必需的

  • 对于 span,必须指定 servicesspan_namesspan_kindsattributeresourcelibrary 之一,并提供非空值,配置才有效。log_bodieslog_severity_textslog_severitymetric_names 属性无效。
  • 对于日志,必须指定 log_bodieslog_severity_textslog_severityattributeresourcelibrary 之一,并提供非空值,配置才有效。span_namesspan_kindsmetric_namesservices 属性无效。
  • 对于指标,必须指定 metric_names,并提供有效的非空值,配置才有效。span_namesspan_kindslog_bodieslog_severity_textslog_severityservicesattributeresourcelibrary 属性无效。

如果配置包含特定信号类型的过滤器,最好只在组件的输出中包含该信号类型。例如,如果在组件的输出中配置了日志,添加 span_names 过滤器可能会导致组件出错。

regexp 块

此块是 match_type"regexp" 的可选配置。它配置一个最近最少使用 (LRU) 缓存。

支持以下参数

名称类型描述默认值必填
cache_enabledbool确定是否对匹配结果进行 LRU 缓存。false
cache_max_num_entriesint存储匹配结果的 LRU 缓存的最大条目数。0

启用 cache_enabled 可以加快后续匹配速度。除非同时指定了 cache_max_num_entries,否则缓存大小不受限制。

如果 cache_enabled 为 false,则忽略 cache_max_num_entries

attribute 块

此块指定要匹配的属性

  • 可以定义多个 attribute 块。
  • 如果指定了 attribute,则只允许 match_type = "strict"
  • 所有 attribute 块必须完全匹配才能发生匹配。

支持以下参数

名称类型描述默认值必填
keystring属性 key。
value任意类型要匹配的属性 value。

如果未设置 value,则任何值都将匹配。value 的类型可以是数字、字符串或布尔值。

resource 块

此块指定要匹配的资源项目

  • 可以定义多个 resource 块。
  • 如果输入数据资源匹配至少一个 resource 块,则发生匹配。

支持以下参数

名称类型描述默认值必填
keystring资源 key。
value任意类型要匹配的资源 value。

如果未设置 value,则任何值都将匹配。value 的类型可以是数字、字符串或布尔值。

library 块

此块指定要匹配的实现库属性

  • 可以定义多个 library 块。
  • 如果 span 的实现库匹配至少一个 library 块,则发生匹配。

支持以下参数

名称类型描述默认值必填
namestring属性 key。
versionstring要匹配的版本。null

如果 version 未设置,则任何版本都匹配。如果 version 设置为空字符串,则只匹配同样为空字符串的库版本。

log_severity 块

此块定义如何根据日志记录的 SeverityNumber 字段进行匹配。

支持以下参数

名称类型描述默认值必填
match_undefinedbool是否匹配严重性为“未定义”的日志。
minstring允许匹配的最低严重性。

如果 match_undefined 为 true,则严重性未定义的条目将匹配。

下表列出了 OTel 支持的严重性。min 的值应是“日志严重性”列中的一个值。

日志严重性严重性编号
TRACE1
TRACE22
TRACE33
TRACE44
DEBUG5
DEBUG26
DEBUG37
DEBUG48
INFO9
INFO210
INFO311
INFO412
WARN13
WARN214
WARN315
WARN416
ERROR17
ERROR218
ERROR319
ERROR420
FATAL21
FATAL222
FATAL323
FATAL424

例如,如果在 log_severity 块中的 min 属性设置为“INFO”,则 INFO、WARN、ERROR 和 FATAL 级别的日志将匹配。

output 块

output 块配置一组组件,用于将处理后的遥测数据转发到。

支持以下参数

名称类型描述默认值必填
logslist(otelcol.Consumer)发送日志的消费者列表。[]
metricslist(otelcol.Consumer)发送指标的消费者列表。[]
traceslist(otelcol.Consumer)发送链路的消费者列表。[]

必须指定 output 块,但其所有参数都是可选的。默认情况下,遥测数据会被丢弃。相应地配置 metricslogstraces 参数,以将遥测数据发送到其他组件。

debug_metrics 块

debug_metrics 块配置此组件生成用于监控其状态的指标。

支持以下参数

名称类型描述默认值必填
disable_high_cardinality_metricsboolean是否禁用某些高基数指标。true

disable_high_cardinality_metrics 在 Grafana Alloy 中等同于 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics 功能开关。它移除了可能导致高基数指标的属性。例如,HTTP 和 gRPC 连接指标中包含 IP 地址和端口号的属性将被移除。

注意

如果配置,disable_high_cardinality_metrics 仅适用于 otelcol.exporter.*otelcol.receiver.* 组件。

导出字段

以下字段已导出,可供其他组件引用

名称类型描述
inputotelcol.Consumer其他组件可用于发送遥测数据的值。

input 接受任何遥测信号(指标、日志或链路)的 otelcol.Consumer 数据。

组件健康状况

仅当 otelcol.processor.attributes 配置无效时,才报告其不健康。

调试信息

otelcol.processor.attributes 不暴露任何组件特定的调试信息。

示例

action 块的各种用法

alloy
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 块中只配置了链路。

alloy
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 属性不用于指标,这就是为什么组件输出中没有配置指标。

alloy
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 属性不用于指标,这就是为什么组件输出中没有配置指标。

alloy
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”属性。

请注意,由于 servicesspan_names 属性的存在,此配置仅适用于链路信号。这就是为什么 output 块中只配置了链路。

alloy
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”属性。

alloy
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 块中只配置了日志。

alloy
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 块中只配置了日志。

alloy
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 块中只配置了日志。

alloy
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 块中只配置了指标。

alloy
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 包含可被以下组件消费的导出

注意

连接某些组件可能不合理,或组件可能需要进一步配置才能使连接正常工作。请参阅链接的文档了解更多详细信息。