菜单
文档breadcrumb arrow Grafana Alloybreadcrumb arrow 参考breadcrumb arrow 组件breadcrumb arrow otelcolbreadcrumb arrow otelcol.processor.tail_sampling
开源 此页面内容适用于开源版本。

otelcol.processor.tail_sampling

otelcol.processor.tail_sampling 根据一组定义的策略对追踪进行采样。要做出有效的采样决策，特定追踪的所有 span 必须由同一采集器实例接收。

注意

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

可以通过为 otelcol.processor.tail_sampling 组件指定不同的标签来定义多个此类组件。

用法

alloy 
otelcol.processor.tail_sampling "LABEL" {
  policy {
    ...
  }
  ...

  output {
    traces  = [...]
  }
}

参数

otelcol.processor.tail_sampling 支持以下参数：

名称类型描述默认值必需
decision_waitduration自追踪的第一个 span 以来，在做出采样决策之前等待的时间。"30s"否
num_tracesint内存中保留的追踪数量。50000否
expected_new_traces_per_secint预期的新追踪数量（有助于分配数据结构）。0否
decision_cacheobject配置采样决策的缓存。{}否

decision_wait 确定在通道上维护的批次数量。其值必须转换为大于零的秒数。

num_traces 确定追踪删除通道的缓冲区大小，该通道由追踪 ID 组成。增加该数字会增加组件的内存使用量，而减少该数字会降低内存中保留的最大追踪数量。

expected_new_traces_per_sec 确定当前批次的初始切片大小。数字越大，使用的内存越多，但在将追踪添加到批次时效率更高。

decision_cache 可以包含两个键：

  • sampled_cache_size：配置要在 LRU 缓存中保留的追踪 ID 数量，用于持久化可能已从内存中释放的追踪的“保留”决策。默认情况下，大小为 0 且缓存处于非活动状态。
  • non_sampled_cache_size：配置要在 LRU 缓存中保留的追踪 ID 数量，用于持久化可能已从内存中释放的追踪的“丢弃”决策。默认情况下，大小为 0 且缓存处于非活动状态。

您可能需要根据预期策略产生的“保留”与“丢弃”决策数量来调整 decision_cache 的大小。例如，如果预期大多数追踪将被丢弃，则可以分配更大的 non_sampled_cache_size。此外，当使用 decision_cache 时，将其配置为远高于 num_traces 的值，以便追踪 ID 的决策保留时间长于追踪的 span 数据。

块

otelcol.processor.tail_sampling 定义中支持以下块：

层级块描述必需
policypolicy用于做出采样决策的策略。是
policy > latencylatency策略基于追踪的持续时间进行采样。否
policy > numeric_attributenumeric_attribute策略基于数字属性（资源和记录）进行采样。否
policy > probabilisticprobabilistic策略按一定百分比对追踪进行采样。否
policy > status_codestatus_code策略基于状态码进行采样。否
policy > string_attributestring_attribute策略基于字符串属性（资源和记录）值匹配进行采样。否
policy > rate_limitingrate_limiting策略基于速率进行采样。否
policy > span_countspan_count策略基于批次中的最小 span 数量进行采样。否
policy > boolean_attributeboolean_attribute策略基于布尔属性（资源和记录）进行采样。否
policy > ottl_conditionottl_condition策略基于给定的布尔 OTTL 条件（span 和 span 事件）进行采样。否
policy > trace_statetrace_state策略基于 TraceState 值匹配进行采样。否
policy > andand策略基于多个策略进行采样，创建一个 and 策略。否
policy > and > and_sub_policyand_sub_policyand 策略类型下的一组策略。否
policy > and > and_sub_policy > latencylatency策略基于追踪的持续时间进行采样。否
policy > and > and_sub_policy > numeric_attributenumeric_attribute策略基于数字属性（资源和记录）进行采样。否
policy > and > and_sub_policy > probabilisticprobabilistic策略按一定百分比对追踪进行采样。否
policy > and > and_sub_policy > status_codestatus_code策略基于状态码进行采样。否
policy > and > and_sub_policy > string_attributestring_attribute策略基于字符串属性（资源和记录）值匹配进行采样。否
policy > and > and_sub_policy > rate_limitingrate_limiting策略基于速率进行采样。否
policy > and > and_sub_policy > span_countspan_count策略基于批次中的最小 span 数量进行采样。否
policy > and > and_sub_policy > boolean_attributeboolean_attribute策略基于布尔属性（资源和记录）进行采样。否
policy > and > and_sub_policy > ottl_conditionottl_condition策略基于给定的布尔 OTTL 条件（span 和 span 事件）进行采样。否
policy > and > and_sub_policy > trace_statetrace_state策略基于 TraceState 值匹配进行采样。否
policy > compositecomposite策略基于上述采样器的组合进行采样，并按采样器分配顺序和速率。否
policy > composite > composite_sub_policycomposite_sub_policycomposite 策略类型下的一组策略。否
policy > composite > composite_sub_policy > latencylatency策略基于追踪的持续时间进行采样。否
policy > composite > composite_sub_policy > numeric_attributenumeric_attribute策略基于数字属性（资源和记录）进行采样。否
policy > composite > composite_sub_policy > probabilisticprobabilistic策略按一定百分比对追踪进行采样。否
policy > composite > composite_sub_policy > status_codestatus_code策略基于状态码进行采样。否
policy > composite > composite_sub_policy > string_attributestring_attribute策略基于字符串属性（资源和记录）值匹配进行采样。否
policy > composite > composite_sub_policy > rate_limitingrate_limiting策略基于速率进行采样。否
policy > composite > composite_sub_policy > span_countspan_count策略基于批次中的最小 span 数量进行采样。否
policy > composite > composite_sub_policy > boolean_attributeboolean_attribute策略基于布尔属性（资源和记录）进行采样。否
policy > composite > composite_sub_policy > ottl_conditionottl_condition策略基于给定的布尔 OTTL 条件（span 和 span 事件）进行采样。否
policy > composite > composite_sub_policy > trace_statetrace_state策略基于 TraceState 值匹配进行采样。否
outputoutput配置将接收到的遥测数据发送到何处。是
debug_metricsdebug_metrics配置此组件生成的用于监控其状态的指标。否

policy 块

policy 块配置了组件使用的采样策略。至少需要一个 policy 块。

支持以下参数：

名称类型描述默认值必需
名称string为策略指定的自定义名称。是
类型string此策略的有效策略类型。是

每个策略都会产生一个决策，处理器会评估这些决策以做出最终决策：

  • 当出现“反转的不采样”决策时，该追踪不被采样。
  • 当出现“采样”决策时，该追踪被采样。
  • 当出现“反转的采样”决策且没有“不采样”决策时，该追踪被采样。
  • 在所有其他情况下，该追踪不被采样。

“反转”决策是基于“invert_match”属性做出的决策，例如来自字符串、数字或布尔标签策略的决策。

latency 块

latency 块配置类型为 latency 的策略。该策略基于追踪的持续时间进行采样。持续时间是通过查看最早的开始时间和最晚的结束时间确定的，不考虑其间发生的事情。

支持以下参数：

名称类型描述默认值必需
threshold_msnumber采样的较低延迟阈值，单位为毫秒。是
upper_threshold_msnumber采样的较高延迟阈值，单位为毫秒。0否

要对追踪进行采样，其延迟应大于 threshold_ms 且小于或等于 upper_threshold_ms。

将 upper_threshold_ms 设置为 0 将导致策略采样任何大于 threshold_ms 的追踪。

numeric_attribute 块

numeric_attribute 块配置类型为 numeric_attribute 的策略。该策略基于数字属性（资源和记录）进行采样。

支持以下参数：

名称类型描述默认值必需
keystring过滤器匹配的标签。是
min_valuenumber被视为匹配的属性最小值。是
max_valuenumber被视为匹配的属性最大值。是
invert_matchbool指示值不得与属性值匹配。false否

probabilistic 块

probabilistic 块配置类型为 probabilistic 的策略。该策略按一定百分比对追踪进行采样。

支持以下参数：

名称类型描述默认值必需
sampling_percentagenumber追踪的采样百分比率。是
hash_saltstring见下文。否

使用 hash_salt 配置哈希盐。这在多层采集器具有不同采样率的场景中非常重要。如果多个采集器使用相同的盐但采样率不同，通过一层可能会通过另一层，即使采集器具有不同的采样率。配置不同的盐可以避免这种情况。

status_code 块

status_code 块配置类型为 status_code 的策略。该策略基于状态码进行采样。

支持以下参数：

名称类型描述默认值必需
status_codeslist(string)包含可配置设置，用于创建状态码过滤器采样策略评估器。是

status_codes 的值必须是“OK”、“ERROR”或“UNSET”。

string_attribute 块

string_attribute 块配置类型为 string_attribute 的策略。该策略基于字符串属性（资源和记录）值匹配进行采样。支持精确匹配和正则表达式匹配。

支持以下参数：

名称类型描述默认值必需
keystring过滤器匹配的标签。是
valueslist(string)匹配属性值时使用的一组值或正则表达式。是
enabled_regex_matchingbool确定是否通过正则表达式字符串匹配属性值。false否
cache_max_sizestring最近最少使用 (LRU) 缓存的最大属性条目数量，该缓存存储在 values 中定义的正则表达式的匹配结果。否
invert_matchbool指示值或正则表达式不得与属性值匹配。false否

rate_limiting 块

rate_limiting 块配置类型为 rate_limiting 的策略。该策略基于速率进行采样。

支持以下参数：

名称类型描述默认值必需
spans_per_secondnumber设置每秒可处理的最大 span 数量。是

span_count 块

span_count 块配置类型为 span_count 的策略。该策略基于批次中的最小 span 数量进行采样。如果批次中所有追踪的 span 数量都少于阈值，则该批次不被采样。

支持以下参数：

名称类型描述默认值必需
min_spansnumber追踪中的最小 span 数量。是
max_spansnumber追踪中的最大 span 数量。0否

如果不想基于追踪中的最大 span 数量来限制策略采样，请将 max_spans 设置为 0。

boolean_attribute 块

boolean_attribute 块配置类型为 boolean_attribute 的策略。该策略基于布尔属性（资源和记录）进行采样。

支持以下参数：

名称类型描述默认值必需
keystring要匹配的属性键。是
valuebool匹配属性值时使用的布尔值（true 或 false）。是
invert_matchbool指示值不得与属性值匹配。false否

ottl_condition 块

ottl_condition 块配置类型为 ottl_condition 的策略。该策略基于给定的布尔 OTTL 条件（span 和 span 事件）进行采样。

支持以下参数：

名称类型描述默认值必需
error_modestring如果 OTTL 条件评估失败时的错误处理。是
spanlist(string)span 的 OTTL 条件。[]否
spaneventlist(string)span 事件的 OTTL 条件。[]否

error_mode 支持的值有：

  • ignore：忽略条件返回的错误，记录下来，然后继续下一个条件。这是推荐的模式。
  • silent：忽略条件返回的错误，不记录日志，然后继续下一个条件。
  • propagate：将错误向上传播到管线。这将导致载荷从 Alloy 中丢弃。

必须至少指定 span 或 spanevent 中的一个。span 和 spanevent 也可以同时指定。

trace_state 块

trace_state 块配置类型为 trace_state 的策略。该策略基于 TraceState 值匹配进行采样。

支持以下参数：

名称类型描述默认值必需
keystring过滤器匹配的标签。是
valueslist(string)匹配 trace_state 值时使用的一组值。是

and 块

and 块配置类型为 and 的策略。该策略通过创建一个 and 策略基于多个策略进行采样。

and_sub_policy 块

and_sub_policy 块配置 and 块使用的采样策略。在 and 块内至少需要一个 and_sub_policy 块。

支持以下参数：

名称类型描述默认值必需
名称string为策略指定的自定义名称。是
类型string此策略的有效策略类型。是

composite 块

composite 块配置类型为 composite 的策略。该策略基于上述采样器的组合进行采样，并按采样器分配顺序和速率。速率分配按策略顺序分配一定百分比的 span。例如，如果 max_total_spans_per_second 设置为 100，则 rate_allocation 设置如下：

  1. test-composite-policy-1 = max_total_spans_per_second 的 50% = 每秒 50 个 span
  2. test-composite-policy-2 = max_total_spans_per_second 的 25% = 每秒 25 个 span
  3. 为确保填满剩余容量，请使用 always_sample 作为策略之一。

composite_sub_policy 块

composite_sub_policy 块配置 composite 块使用的采样策略。在 composite 块内至少需要一个composite_sub_policy 块。

支持以下参数：

名称类型描述默认值必需
名称string为策略指定的自定义名称。是
类型string此策略的有效策略类型。是

output 块

output 块配置将结果遥测数据转发到的一组组件。

支持以下参数：

名称类型描述默认值必需
logslist(otelcol.Consumer)发送日志的消费者列表。[]否
metricslist(otelcol.Consumer)list(otelcol.Consumer)[]否
traceslist(otelcol.Consumer)list(otelcol.Consumer)[]否

必须指定 output 块，但其所有参数都是可选的。默认情况下，遥测数据会被丢弃。请根据需要配置 metrics、logs 和 traces 参数，以便将遥测数据发送到其他组件。

debug_metrics 块

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

支持以下参数：

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

disable_high_cardinality_metrics 相当于 OpenTelemetry Collector 中 telemetry.disableHighCardinalityMetrics 功能门的 Grafana Alloy 版本。它会移除可能导致高基数指标的属性。例如，会移除关于 HTTP 和 gRPC 连接的指标中包含 IP 地址和端口号的属性。

注意

如果配置了 disable_high_cardinality_metrics，它仅适用于 otelcol.exporter.* 和 otelcol.receiver.* 组件。

导出字段

导出以下字段，其他组件可以引用：

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

input 接受用于任何遥测信号（指标、日志或追踪）的 otelcol.Consumer 数据。

组件健康状态

仅在配置无效时，otelcol.processor.tail_sampling 会报告为不健康。

调试信息

otelcol.processor.tail_sampling 不公开任何组件特定的调试信息。

示例

此示例将 Alloy 中的追踪数据批量处理后发送到 otelcol.exporter.otlp 进行进一步处理。此示例展示了数量不切实际的策略，仅用于演示如何设置每种类型。

alloy 
tracing {
  sampling_fraction = 1
  write_to          = [otelcol.processor.tail_sampling.default.input]
}

otelcol.processor.tail_sampling "default" {
  decision_cache = {
    sampled_cache_size     = 100000,
    non_sampled_cache_size = 100000,
    }
  decision_wait               = "10s"
  num_traces                  = 100
  expected_new_traces_per_sec = 10

  policy {
    name = "test-policy-1"
    type = "always_sample"
  }

  policy {
    name = "test-policy-2"
    type = "latency"

    latency {
      threshold_ms = 5000
    }
  }

  policy {
    name = "test-policy-3"
    type = "numeric_attribute"

    numeric_attribute {
      key       = "key1"
      min_value = 50
      max_value = 100
    }
  }

  policy {
    name = "test-policy-4"
    type = "probabilistic"

    probabilistic {
      sampling_percentage = 10
    }
  }

  policy {
    name = "test-policy-5"
    type = "status_code"

    status_code {
      status_codes = ["ERROR", "UNSET"]
    }
  }

  policy {
    name = "test-policy-6"
    type = "string_attribute"

    string_attribute {
      key    = "key2"
      values = ["value1", "value2"]
    }
  }

  policy {
    name = "test-policy-7"
    type = "string_attribute"

    string_attribute {
      key                    = "key2"
      values                 = ["value1", "val*"]
      enabled_regex_matching = true
      cache_max_size         = 10
    }
  }

  policy {
    name = "test-policy-8"
    type = "rate_limiting"

    rate_limiting {
      spans_per_second = 35
    }
  }

  policy {
    name = "test-policy-9"
    type = "string_attribute"

    string_attribute {
      key                    = "http.url"
      values                 = ["/health", "/metrics"]
      enabled_regex_matching = true
      invert_match           = true
    }
  }

  policy {
    name = "test-policy-10"
    type = "span_count"

    span_count {
      min_spans = 2
    }
  }

  policy {
    name = "test-policy-11"
    type = "trace_state"

    trace_state {
      key    = "key3"
      values = ["value1", "value2"]
    }
  }

  policy {
    name = "test-policy-12"
    type = "ottl_condition"
    ottl_condition {
      error_mode = "ignore"
      span = [
        "attributes[\"test_attr_key_1\"] == \"test_attr_val_1\"",
        "attributes[\"test_attr_key_2\"] != \"test_attr_val_1\"",
      ]
      spanevent = [
        "name != \"test_span_event_name\"",
        "attributes[\"test_event_attr_key_2\"] != \"test_event_attr_val_1\"",
      ]
    }
  }

  policy {
    name = "and-policy-1"
    type = "and"

    and {
      and_sub_policy {
        name = "test-and-policy-1"
        type = "numeric_attribute"

        numeric_attribute {
          key       = "key1"
          min_value = 50
          max_value = 100
        }
      }

      and_sub_policy {
        name = "test-and-policy-2"
        type = "string_attribute"

        string_attribute {
          key    = "key1"
          values = ["value1", "value2"]
        }
      }
    }
  }

  policy {
    name = "composite-policy-1"
    type = "composite"

    composite {
      max_total_spans_per_second = 1000
      policy_order               = ["test-composite-policy-1", "test-composite-policy-2", "test-composite-policy-3"]

      composite_sub_policy {
        name = "test-composite-policy-1"
        type = "numeric_attribute"

        numeric_attribute {
          key       = "key1"
          min_value = 50
          max_value = 100
        }
      }

      composite_sub_policy {
        name = "test-composite-policy-2"
        type = "string_attribute"

        string_attribute {
          key    = "key1"
          values = ["value1", "value2"]
        }
      }

      composite_sub_policy {
        name = "test-composite-policy-3"
        type = "always_sample"
      }

      rate_allocation {
        policy  = "test-composite-policy-1"
        percent = 50
      }

      rate_allocation {
        policy  = "test-composite-policy-2"
        percent = 50
      }
    }
  }

  output {
    traces = [otelcol.exporter.otlp.production.input]
  }
}

otelcol.exporter.otlp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

兼容组件

otelcol.processor.tail_sampling 可以接受来自以下组件的参数：

otelcol.processor.tail_sampling 具有可被以下组件消费的导出：

注意

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