菜单
文档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 块,则先检查 include 属性,然后再检查 exclude 属性。

action 块

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

以下属性受支持

名称类型描述默认值必需
key字符串动作相关的属性。
action字符串执行的操作类型。
value任何用于键的填充值。
pattern字符串正则表达式模式。""
from_attribute字符串用于填充属性值的输入数据的属性。""
from_context字符串用于填充属性值的上下文值。""
converted_type字符串将属性值转换为的类型。""

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

action 的支持值

  • insert:在键不存在的情况下,在输入数据中插入新的属性。

    • key 属性是必需的。它指定要执行的属性。
    • 必需的 valuefrom_attributefrom_context 属性之一。
  • update:在键存在的情况下,更新输入数据中的属性。

    • key 属性是必需的。它指定要执行的属性。
    • 必需的 valuefrom_attributefrom_context 属性之一。
  • upsert:在输入数据中不存在键时插入新属性,或者在键存在时更新属性。

    • key 属性是必需的。它指定要执行的属性。
    • 必须提供 valuefrom_attributefrom_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"

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

以下之一也是必需的:

  • 对于跨度,必须指定 servicesspan_namesspan_kindsattributeresourcelibrary 之一,并使用非空值进行有效配置。无效的属性是 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字符串控制如何解释要匹配的项目。
log_bodies字符串列表必须与 LogRecord 的主体字段匹配的字符串列表。[]
log_severity_texts字符串列表必须与 LogRecord 的严重性文本字段匹配的字符串列表。[]
metric_names字符串列表与指标名称匹配的字符串列表。[]
services字符串列表与服务名称匹配的项目列表。[]
span_kinds字符串列表与跨度类型匹配的项目列表。[]
span_names字符串列表与跨度名称匹配的项目列表。[]

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

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

以下之一也是必需的:

  • 对于跨度,必须指定 servicesspan_namesspan_kindsattributeresourcelibrary 之一,并使用非空值进行有效配置。无效的属性是 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过滤器可能导致组件在配置组件的输出日志时出错。

正则表达式块

此块是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,应选择“日志严重性”列中的值之一。

日志严重性严重性编号
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 块配置了一组组件,用于将结果遥测数据转发到这些组件。

支持以下参数:

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

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

调试度量块

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"

导出字段

以下字段被导出,并可由其他组件引用

名称类型描述
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")
  }
}

基于属性排除跨度

例如,以下跨度匹配属性而不会被处理器处理

  • 跨度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 块中只配置跟踪的原因。

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

根据正则表达式和服务包含和排除跨度

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

根据日志主体正则表达式包含跨度

此处理器将删除“token”属性,并将日志主体匹配“AUTH.*”的跨度中的“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 有可以被以下组件消费的导出

注意

连接某些组件可能没有意义,或者组件可能需要进一步的配置才能正确连接。请参阅相关文档以获取更多详细信息。