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

otelcol.processor.attributes

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

注意

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、log 或 metric。

支持以下属性

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

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 块提供了一个选项,可以根据 span、log 或 metric 记录的属性,包含要馈送到 action 块的数据。

支持以下参数

名称类型描述默认值必需
match_typestring控制如何解释要匹配的项。
log_bodieslist(string)LogRecord 的 body 字段必须匹配的字符串列表。[]
log_severity_textslist(string)LogRecord 的严重性文本字段必须匹配的字符串列表。[]
metric_nameslist(string)用于匹配指标名称的字符串列表。[]
serviceslist(string)用于匹配服务名称的项列表。[]
span_kindslist(string)用于匹配 span kind 的项列表。[]
span_nameslist(string)用于匹配 span 名称的项列表。[]

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

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

以下项之一也是必需的

  • 对于 span,servicesspan_namesspan_kindsattributeresourcelibrary 之一必须指定非空值才能进行有效配置。log_bodieslog_severity_textslog_severitymetric_names 属性无效。
  • 对于 log,log_bodieslog_severity_textslog_severityattributeresourcelibrary 之一必须指定非空值才能进行有效配置。span_namesspan_kindsmetric_namesservices 属性无效。
  • 对于 metric,metric_names 必须指定有效的非空值才能进行有效配置。span_namesspan_kindslog_bodieslog_severity_textslog_severityservicesattributeresourcelibrary 属性无效。

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

exclude 块

exclude 块提供了一个选项,可以根据 span、log 或 metric 记录的属性,排除要馈送到 action 块的数据。

注意

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

支持以下参数

名称类型描述默认值必需
match_typestring控制如何解释要匹配的项。
log_bodieslist(string)LogRecord 的 body 字段必须匹配的字符串列表。[]
log_severity_textslist(string)LogRecord 的严重性文本字段必须匹配的字符串列表。[]
metric_nameslist(string)用于匹配指标名称的字符串列表。[]
serviceslist(string)用于匹配服务名称的项列表。[]
span_kindslist(string)用于匹配 span kind 的项列表。[]
span_nameslist(string)用于匹配 span 名称的项列表。[]

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

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

以下项之一也是必需的

  • 对于 span,servicesspan_namesspan_kindsattributeresourcelibrary 之一必须指定非空值才能进行有效配置。log_bodieslog_severity_textslog_severitymetric_names 属性无效。
  • 对于 log,log_bodieslog_severity_textslog_severityattributeresourcelibrary 之一必须指定非空值才能进行有效配置。span_namesspan_kindsmetric_namesservices 属性无效。
  • 对于 metric,metric_names 必须指定有效的非空值才能进行有效配置。span_namesspan_kindslog_bodieslog_severity_textslog_severityservicesattributeresourcelibrary 属性无效。

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

regexp 块

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

支持以下参数

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

启用 cache_enabled 可以使后续匹配更快。缓存大小不受限制,除非也指定了 cache_max_num_entries

如果 cache_enabled 为 false,则忽略 cache_max_num_entries

attribute 块

此块指定要匹配的属性

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

支持以下参数

名称类型描述默认值必需
keystring属性键。
valueany要匹配的属性值。

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

resource 块

此块指定要匹配资源的项

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

支持以下参数

名称类型描述默认值必需
keystring资源键。
valueany要匹配的资源值。

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

library 块

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

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

支持以下参数

名称类型描述默认值必需
namestring属性键。
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
levelstring控制包装的收集器发出的指标的详细程度。"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"

导出的字段

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

名称类型描述
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 键/值对。

请注意,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 键/值对。

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

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

此处理器将删除 “token” 属性,并模糊处理日志正文与 “AUTH.*” 匹配的 span 中的 “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 块中指定级别的日志。此处理器将删除 “token” 属性,并模糊处理严重性至少为 “INFO” 的日志中的 “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

以下示例演示了如何处理严重性文本与正则表达式模式匹配的日志。此处理器将删除 “token” 属性,并模糊处理严重性与 “info” 匹配的日志中的 “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 具有可以被以下组件使用的导出

注意

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