菜单
文档面包屑箭头 Grafana Alloy面包屑箭头 参考面包屑箭头 组件面包屑箭头 otelcol面包屑箭头 otelcol.processor.tail_sampling
开源

otelcol.processor.tail_sampling

otelcol.processor.tail_sampling 根据一组定义的政策采样跟踪。给定跟踪的所有跨度 必须 由同一个收集器实例接收以进行有效的采样决策。

tail_sampling 组件同时使用软限制和硬限制,其中硬限制始终等于或大于软限制。当内存使用量超过软限制时,处理组件将删除数据并将错误返回到管道中的前一个组件。当使用量超过硬限制时,处理程序强制进行垃圾收集以尝试释放内存。当使用量低于软限制时,不会删除数据且不执行强制垃圾收集。

注意otelcol.processor.tail_sampling 是上游 OpenTelemetry Collector Contrib tail_sampling 处理程序的包装器。如果需要,将 bug 报告或功能请求重定向到上游存储库。

可以通过提供不同的标签来指定多个 otelcol.processor.tail_sampling 组件。

用法

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

  output {
    traces  = [...]
  }
}

参数

otelcol.processor.tail_sampling 支持以下参数

名称类型描述默认值必需
decision_wait持续时间从跟踪的第一个跨度开始等待的时间,然后做出采样决策。"30s"
num_tracesint保留在内存中的跟踪数量。50000
expected_new_traces_per_secint预期的新跟踪数量(有助于分配数据结构)。0

decision_wait 确定了要保留在通道上的批次数。它的值必须转换为大于零的秒数。

num_traces 确定了由跟踪 id 组成的跟踪删除通道的缓冲区大小。增加该数量将增加组件的内存使用量,而减少该数量将降低保留在内存中的跟踪的最大数量。

expected_new_traces_per_sec 确定了当前批次的初始切片大小。较大的数字将使用更多内存,但在将跟踪添加到批次时会更高效。

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

层次结构描述必需
decision_cachedecision_cache []配置要保留在 LRU 缓存中的跟踪 ID 数量。
policypolicy []用于做出采样决策的策略。yes
policy > latencylatency该策略将根据跟踪的持续时间进行采样。
policy > numeric_attributenumeric_attribute策略将基于数字属性(资源和记录)进行采样。
策略 > 随机随机策略将采样一定比例的跟踪。
策略 > 状态码状态码策略将基于状态码进行采样。
策略 > 字符串属性字符串属性策略将基于字符串属性(资源和记录)的值匹配进行采样。
策略 > 速率限制速率限制策略将基于速率进行采样。
策略 > 边解析数量边解析数量策略将基于批处理中的最小边解析数量进行采样。
策略 > 布尔属性布尔属性策略将基于布尔属性(资源和记录)进行采样。
策略 > ottl_conditionottl_condition策略将基于给定的布尔 OTTL 条件(边和边事件)进行采样。
策略 > trace_statetrace_state策略将基于 TraceState 值匹配进行采样。
策略 > 和策略将基于多个策略进行采样,创建一个策略。
策略 > 和 > 和子策略和子策略 []一个策略类型下面的策略集。
策略 > 和 > 和子策略 > 延迟latency该策略将根据跟踪的持续时间进行采样。
策略 > 和 > 和子策略 > 数字属性numeric_attribute策略将基于数字属性(资源和记录)进行采样。
策略 > 和 > 和子策略 > 随机随机策略将采样一定比例的跟踪。
策略 > 和 > 和子策略 > 状态码状态码策略将基于状态码进行采样。
策略 > 和 > 和子策略 > 字符串属性字符串属性策略将基于字符串属性(资源和记录)的值匹配进行采样。
策略 > 和 > 和子策略 > 速率限制速率限制策略将基于速率进行采样。
策略 > 和 > 和子策略 > 边解析数量边解析数量策略将基于批处理中的最小边解析数量进行采样。
策略 > 和 > 和子策略 > 布尔属性布尔属性策略将基于布尔属性(资源和记录)进行采样。
策略 > 和 > 和子策略 > ottl_conditionottl_condition策略将基于给定的布尔 OTTL 条件(边和边事件)进行采样。
策略 > 和 > 和子策略 > trace_statetrace_state策略将基于 TraceState 值匹配进行采样。
策略 > 组合组合此策略将基于上述采样器的组合进行采样,每个采样器的排序和速率分配。
策略 > 组合 > 组合子策略组合子策略 []一个组合策略类型下面的策略集。
策略 > 组合 > 组合子策略 > 延迟latency该策略将根据跟踪的持续时间进行采样。
策略 > 组合 > 组合子策略 > 数字属性numeric_attribute策略将基于数字属性(资源和记录)进行采样。
策略 > 组合 > 组合子策略 > 随机随机策略将采样一定比例的跟踪。
策略 > 组合 > 组合子策略 > 状态码状态码策略将基于状态码进行采样。
策略 > 组合 > 组合子策略 > 字符串属性字符串属性策略将基于字符串属性(资源和记录)的值匹配进行采样。
策略 > 组合 > 组合子策略 > 速率限制速率限制策略将基于速率进行采样。
策略 > 组合 > 组合子策略 > 边解析数量边解析数量策略将基于批处理中的最小边解析数量进行采样。
策略 > 组合 > 组合子策略 > 布尔属性布尔属性策略将基于布尔属性(资源和记录)进行采样。
策略 > 组合 > 组合子策略 > ottl_conditionottl_condition策略将基于给定的布尔 OTTL 条件(边和边事件)进行采样。
策略 > 组合 > 组合子策略 > trace_statetrace_state策略将基于 TraceState 值匹配进行采样。
输出输出 []配置接收到的遥测数据发送的位置。yes
debug_metricsdebug_metrics配置此组件生成的监控其状态的指标。

decision_cache block

decision_cache块配置要保留在LRU缓存中的跟踪ID数量,持久化可能已被释放出内存的跟踪的“保留”决策。

以下参数被支持

名称类型描述默认值必需
sampled_cache_size数字在缓存中保留的跟踪ID数量。0

sampled_cache_size设置为0时,缓存处于非活动状态。

使用decision_cache时,将sampled_cache_size配置得远高于num_traces,以便跟踪ID的决策比跟踪的边数据保留更长时间。

policy block

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

以下参数被支持

名称类型描述默认值必需
name字符串分配给策略的定制名称。yes
type字符串适用于此策略的合法策略类型。yes

每个策略产生一个决策,处理器评估它们以做出最终的决策

  • 当有“反转不采样”决策时,跟踪将不被采样。
  • 当有“样本”决策时,追踪将被采样。
  • 当有“反样本”决策且没有“不采样”决策时,追踪将被采样。
  • 在其他所有情况下,追踪将不采样。

"反"决策是基于“invert_match”属性做出的决策,例如来自字符串标签策略的决策。

延迟块

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

以下参数被支持

名称类型描述默认值必需
threshold_ms数字采样的低延迟阈值,以毫秒为单位。yes
upper_threshold_ms数字采样的高延迟阈值,以毫秒为单位。0

为了使追踪被采样,其延迟应大于threshold_ms且小于或等于upper_threshold_ms

upper_threshold_ms0将导致采样任何大于threshold_ms的内容的策略。

numeric_attribute块

numeric_attribute块配置一个类型为numeric_attribute的策略。该策略基于数值属性(资源和记录)进行采样。

以下参数被支持

名称类型描述默认值必需
key字符串与过滤器匹配的标记。yes
min_value数字被考虑为匹配的属性的最低值。yes
max_value数字被考虑为匹配的属性的最高值。yes
invert_matchbool指示值必须不匹配属性值。false

probabilistic块

probabilistic块配置一个类型为probabilistic的策略。该策略采样一定比例的追踪。

以下参数被支持

名称类型描述默认值必需
sampling_percentage数字追踪采样的百分比率。yes
hash_salt字符串见下。

使用hash_salt配置哈希盐。在多个收集层有不同采样率的情况下,这很重要。如果多个收集器使用不同的采样率使用相同的盐,那么即使收集器有不同的采样率,一个层通过,另一个可能也会通过。配置不同的盐可以避免这种情况。

status_code块

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

以下参数被支持

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

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

string_attribute块

string_attribute块配置一个类型为string_attribute的策略。该策略基于字符串属性的值匹配进行采样(资源记录)。两种精确匹配和正则表达式值匹配都受支持。

以下参数被支持

名称类型描述默认值必需
key字符串与过滤器匹配的标记。yes
valueslist(string)用于与属性值匹配的一组值或正则表达式。yes
enabled_regex_matchingbool确定是否按正则表达式字符串匹配属性值。false
cache_max_size字符串values中定义的正则表达式匹配结果的Least Recently Used (LRU) 缓存中存储的属性条目数的最小值。
invert_matchbool指示值或正则表达式不允许与属性值匹配。false

rate_limiting块

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

以下参数被支持

名称类型描述默认值必需
spans_per_second数字每秒最多处理的跨度数。yes

span_count块

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

以下参数被支持

名称类型描述默认值必需
min_spans数字追踪中的最小跨度数。yes
max_spans数字追踪中的最大跨度数。0

max_spans设置为0,如果您不希望根据跟踪中的最大跨度数限制策略样本。

boolean_attribute区块

boolean_attribute区块配置类型为boolean_attribute的策略。策略样本基于布尔属性(资源和记录)。

以下参数被支持

名称类型描述默认值必需
key字符串用于匹配的属性键。yes
bool匹配属性值时使用的布尔值(truefalse)。yes

ottl_condition区块

ottl_condition区块配置类型为ottl_condition的策略。策略样本基于给定的布尔OTTL条件(跨度和高跨度事件)。

以下参数被支持

名称类型描述默认值必需
error_mode字符串如果OTTL条件评估失败,则进行错误处理。yes
跨度list(string)跨度的OTTL条件。[]
高跨度事件list(string)高跨度事件的OTTL条件。[]

error_mode支持的值包括:

  • ignore:忽略条件返回的错误,记录它们,并继续到下一个条件。这是推荐的模式。
  • silent:忽略条件返回的错误,不记录它们,并继续到下一个条件。
  • propagate:将错误返回到管道。这将导致从Alloy中删除有效负载。

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

trace_state区块

trace_state区块配置类型为trace_state的策略。策略样本基于TraceState值匹配。

以下参数被支持

名称类型描述默认值必需
key字符串与过滤器匹配的标记。yes
valueslist(string)设置当匹配trace_state值时使用的值集。yes

and区块

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

and_sub_policy区块

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

以下参数被支持

名称类型描述默认值必需
name字符串分配给策略的定制名称。yes
type字符串适用于此策略的合法策略类型。yes

composite区块

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

  1. test-composite-policy-1 = max_total_spans_per_second的50% = 每秒50个跨度
  2. test-composite-policy-2 = max_total_spans_per_second的25% = 每秒25个跨度
  3. 为确保剩余容量得到填充,请使用always_sample作为策略之一。

composite_sub_policy区块

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

以下参数被支持

名称类型描述默认值必需
name字符串分配给策略的定制名称。yes
type字符串适用于此策略的合法策略类型。yes

output区块

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

以下参数被支持

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

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

debug_metrics区块

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

以下参数被支持

名称类型描述默认值必需
disable_high_cardinality_metricsboolean是否禁用某些高基数指标。true
level字符串控制包装收集器发出的指标的详细程度。详细

disable_high_cardinality_metrics 是 Grafana Alloy 与 OpenTelemetry Collector 中 telemetry.disableHighCardinalityMetrics 功能开关的等价项。它移除可能导致高基数指标的属性。例如,删除了关于 HTTP 和 gRPC 连接的指标中包含 IP 地址和端口号的属性。

注意

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

level 是 Grafana Alloy 与 OpenTelemetry Collector 中 telemetry.metrics.level 功能开关的等价项。可能的值是 "none""basic""normal""detailed"

导出字段

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

名称类型描述
输入otelcol.Consumer其他组件可以使用此值发送遥测数据。

input 接受来自任何遥测信号(指标、日志或跟踪)的 otelcol.Consumer 数据。

组件健康

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

调试信息

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

示例

此示例在将迹数据发送到 otelcol.exporter.otlp 以进行进一步处理之前将其批量处理。此示例展示了用于演示如何设置每种类型的不可行数量策略。

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

otelcol.processor.tail_sampling "default" {
  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 = env("OTLP_SERVER_ENDPOINT")
  }
}

兼容组件

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

  • 导出 OpenTelemetry otelcol.Consumer 的组件

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

  • 消费 OpenTelemetry otelcol.Consumer 的组件

注意

连接某些组件可能不合理,或组件可能需要进一步配置才能正确连接。请参阅相关文档以获取更多详情。