菜单
文档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_policy“and” 策略类型下的一组策略。
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_policy“composite” 策略类型下的一组策略。
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 块。

支持以下参数

名称类型描述默认值必需
namestring赋予策略的自定义名称。
typestring此策略的有效策略类型。

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

  • 当存在 “反向非采样” 决策时,追踪将不被采样。
  • 当存在 “采样” 决策时,追踪将被采样。
  • 当存在 “反向采样” 决策且没有 “非采样” 决策时,追踪将被采样。
  • 在所有其他情况下,追踪会被采样。

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

latency 块

latency 块配置类型为 latency 的策略。该策略基于追踪的持续时间进行采样。持续时间通过查看最早的开始时间和最晚的结束时间来确定,而无需考虑中间发生了什么。

支持以下参数

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

对于要采样的追踪,其延迟应大于 threshold_ms 且小于或等于 upper_threshold_ms

upper_threshold_ms0 将导致策略采样任何大于 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在与属性值匹配时使用的布尔值 (truefalse)。
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 中丢弃。

应至少指定 spanspanevent 之一。也可以同时指定 spanspanevent

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 块。

支持以下参数

名称类型描述默认值必需
namestring赋予策略的自定义名称。
typestring此策略的有效策略类型。

composite 块

composite 块配置类型为 composite 的策略。此策略基于上述采样器的组合进行采样,并具有每个采样器的排序和速率分配。速率分配为每个策略顺序分配一定百分比的 span。例如,如果 max_total_spans_per_second 设置为 100,则 rate_allocation 设置如下

  1. test-composite-policy-1 = max_total_spans_per_second 的 50% = 50 spans_per_second
  2. test-composite-policy-2 = max_total_spans_per_second 的 25% = 25 spans_per_second
  3. 为了确保剩余容量被填满,请使用 always_sample 作为其中一个策略。

composite_sub_policy 块

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

支持以下参数

名称类型描述默认值必需
namestring赋予策略的自定义名称。
typestring此策略的有效策略类型。

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 中 telemetry.disableHighCardinalityMetrics 功能门控的等效项。它会删除可能导致高基数指标的属性。例如,HTTP 和 gRPC 连接指标中包含 IP 地址和端口号的属性将被删除。

注意

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

level 是 Alloy 中 telemetry.metrics.level 功能门控的等效项。可能的值为 "none""basic""normal""detailed"

导出的字段

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

名称类型描述
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 具有可以被以下组件使用的导出

注意

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