菜单
文档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配置接收到的遥测数据发送的位置。yes
actionaction在传入的指标/日志/跟踪的属性上采取的操作。no
includeinclude为此处理器的操作中的数据设置过滤器。no
include > regexpregexpRegex 缓存设置。no
include > attributeattribute要匹配的属性列表。no
include > resourceresource与资源匹配的项目列表。no
include > librarylibrary与实现库匹配的项目列表。no
include > log_severitylibrary如果定义了,如何匹配日志记录的 SeverityNumber。no
excludeexclude为此处理器的操作之外的数据设置过滤器no
exclude > regexpregexpRegex 缓存设置。no
exclude > attributeattribute要匹配的属性列表。no
exclude > resourceresource与资源匹配的项目列表。no
exclude > librarylibrary与实现库匹配的项目列表。no
exclude > log_severitylog_severity如果定义了,如何匹配日志记录的 SeverityNumber。no
debug_metricsdebug_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属性是必需的。它指定要操作哪个属性。
    • 必须有一个valuefrom_attributefrom_context属性。
  • update:在输入数据中更新属性(如果该键存在)。

    • key属性是必需的。它指定要操作哪个属性。
    • 必须有一个valuefrom_attributefrom_context属性。
  • upsert:要么在输入数据中插入一个不存在的新的属性,要么在输入数据中存在键的地方更新属性。

    • key属性是必需的。它指定要操作哪个属性。
    • 必须有一个valuefrom_attributefrom_context属性。
      • value指定要填充到key的值。
      • from_attribute指定从输入数据中使用的属性来填充值。如果属性不存在,则不执行任何操作。
      • from_context指定用于填充属性值的上下文字符串。如果键以metadata.为前缀,则搜索接收者传输协议以查找附加信息,如gRPC元数据或HTTP标头。如果键以auth.为前缀,则搜索由服务器验证器设置的认证信息。有关可用哪些属性的更多信息,请参阅您管道中服务器验证器的文档。如果键为client.address,则将值设置为客户端地址。如果该键不存在,则不执行任何操作。如果键有多个值,则使用;分隔符连接值。
  • hash:对现有属性值进行散列(SHA1)。

    • key属性和/或pattern属性是必需的。
  • extract:使用正则表达式规则从输入键中提取值到规则中指定的目标键。如果目标键已存在,则将其覆盖。注意:与Span Processor to_attributes设置的行为类似,现有属性作为源。

    • key属性是必需的。它指定要从其中提取值的属性。不更改key的值。
    • pattern属性是必需的。它是从key值的值中提取属性的regex模式。子匹配器必须命名。如果属性已存在,则将覆盖它们。
  • convert:将现有属性转换到指定的类型。

    • key属性是必需的。它指定要操作哪个属性。
    • converted_type属性是必需的,且必须是int、double或string之一。
  • delete:从输入数据中删除属性。

    • key属性和/或pattern属性是必需的。它指定要操作哪个属性。

include block

include块提供了一个根据跨度、日志或度量记录的属性包括数据到action块中。

以下参数受支持:

名称类型描述默认值必须
match_type字符串控制如何对匹配项进行解释。yes
log_bodieslist(string)必须匹配LogRecord体字段的字符串列表。[]no
log_severity_textslist(string)必须与 LogRecord 的严重性文本字段匹配的字符串列表。[]no
metric_nameslist(string)用于匹配指标名称的字符串列表。[]no
serviceslist(string)用于匹配服务名称的项目列表。[]no
span_kindslist(string)用于匹配跨度类型的项目列表。[]no
span_nameslist(string)用于匹配跨度名称的项目列表。[]no

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

如果列表中至少有一个项目匹配,则会发生匹配。

还需要以下之一

  • 对于跨度,必须指定以下之一以具有有效配置:servicesspan_namesspan_kinds属性资源,并且必须用非空值设置。无效的属性是log_bodieslog_severity_textslog_severitymetric_names
  • 对于日志,必须指定以下之一以具有有效配置:log_bodieslog_severity_textslog_severity属性资源,并且必须用非空值设置。无效的属性是span_namesspan_kindsmetric_namesservices
  • 对于指标,必须指定具有有效非空值的 metric_names 以具有有效配置。无效的属性是span_namesspan_kindslog_bodieslog_severity_textslog_severityservices属性资源

如果配置中包含针对特定信号类型特定的过滤器,最好仅将特定信号类型包含在组件的输出中。例如,添加一个span_names过滤器可能导致组件在配置组件的输出时出错。

排除块

exclude块提供了一个选项,可以根据跨度、日志或指标记录的属性排除数据被传送到操作块。

注意

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

以下参数受支持:

名称类型描述默认值必须
match_type字符串控制如何对匹配项进行解释。yes
log_bodieslist(string)必须匹配LogRecord体字段的字符串列表。[]no
log_severity_textslist(string)必须与 LogRecord 的严重性文本字段匹配的字符串列表。[]no
metric_nameslist(string)用于匹配指标名称的字符串列表。[]no
serviceslist(string)用于匹配服务名称的项目列表。[]no
span_kindslist(string)用于匹配跨度类型的项目列表。[]no
span_nameslist(string)用于匹配跨度名称的项目列表。[]no

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

如果列表中至少有一个项目匹配,则会发生匹配。

还需要以下之一

  • 对于跨度,必须指定以下之一以具有有效配置:servicesspan_namesspan_kinds属性资源,并且必须用非空值设置。无效的属性是log_bodieslog_severity_textslog_severitymetric_names
  • 对于日志,必须指定以下之一以具有有效配置:log_bodieslog_severity_textslog_severity属性资源,并且必须用非空值设置。无效的属性是span_namesspan_kindsmetric_namesservices
  • 对于指标,必须指定具有有效非空值的 metric_names 以具有有效配置。无效的属性是span_namesspan_kindslog_bodieslog_severity_textslog_severityservices属性资源

如果配置中包含针对特定信号类型特定的过滤器,最好仅将特定信号类型包含在组件的输出中。例如,添加一个span_names过滤器可能导致组件在配置组件的输出时出错。

regexp块

此块是match_type设置为"regexp"时的可选配置。它配置了最近最少使用(LRU)缓存。

以下参数受支持:

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

启用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
版本字符串用于匹配的版本。nullno

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

log_severity 块

此块定义了根据日志记录的 SeverityNumber 字段进行匹配的方式。

以下参数受支持:

名称类型描述默认值必须
match_undefinedbool是否将“undefined”严重程度的日志匹配。yes
最小值字符串可能匹配的最低严重程度。yes

如果 match_undefined 为真,则未定义严重程度的条目将匹配。

以下表格列出了 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 块配置了一组组件,以将结果遥测数据转发到。

以下参数受支持:

名称类型描述默认值必须
日志list(otelcol.Consumer)要发送日志的消费者列表。[]no
度量list(otelcol.Consumer)要发送度量的消费者列表。[]no
跟踪list(otelcol.Consumer)要发送跟踪的消费者列表。[]no

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

debug_metrics 块

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

以下参数受支持:

名称类型描述默认值必须
disable_high_cardinality_metrics布尔值是否禁用某些高基数指标。trueno
级别字符串控制封装收集器发出的指标的详细程度。"详细"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 不公开任何特定于组件的调试信息。

示例

“操作”块的多种用法

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 = 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 块中只配置了跟踪。

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]
    }
}

基于资源排除跨度

“严格”的 match_type 表示我们必须严格匹配 resource 键/值对。

请注意,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]
    }
}

基于特定库版本排除跨度

“严格”的 match_type 表示我们必须严格匹配 library 键/值对。

请注意,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]
    }
}

基于正则表达式和服务的包括和排除跨度

此处理器将在服务名匹配 "auth.*" 且跨度名称不匹配 "login.*" 的跨度中删除“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]
    }
}

基于正则表达式和属性的包括跨度

以下演示了如何处理匹配正则表达式模式的属性。此处理器将在“db.statement”属性与正则表达式模式匹配的跨度中混淆“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]
    }
}

基于日志体正则表达式的包括跨度

此处理器将在日志体匹配“AUTH.*”的跨度中删除“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]
    }
}

基于日志严重性正则表达式的包括跨度

以下演示了如何处理与 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]
    }
}

基于日志严重性文本正则表达式的包括跨度

以下演示了如何处理严重文本匹配正则表达式模式的日志。此处理器将在严重性与“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 的输出可以被以下组件消耗

注意

连接某些组件可能不合理,或组件可能需要进一步配置才能正确连接。有关更多信息,请参阅链接文档。