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

otelcol.processor.tail_sampling

otelcol.processor.tail_sampling 基于一组定义的策略采样跟踪。对于给定的跟踪,所有跨度必须由相同的收集器实例接收,才能进行有效的采样决策。

注意

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在做出采样决策之前,从跟踪的第一个跨度开始等待的时间。"30s"
num_tracesint内存中保留的跟踪数。50000
expected_new_traces_per_secint预期的新跟踪数量(有助于分配数据结构)。0
decision_cacheobject配置要保留在 LRU 缓存中的跟踪 ID 数量。{}

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

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

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

decision_cache 需要一个键 sampled_cache_size,其值表示要保留在缓存中的跟踪ID数量。当 sampled_cache_size 设置为 0 时,缓存将不活跃。当使用 decision_cache 时,请确保将 sampled_cache_size 设置为一个远大于 num_traces 的值,以便跟踪ID的决策比跟踪的跨度数据保持更长时间。

以下块在 otelcol.processor.tail_sampling 的定义内受支持:

层次结构描述必需
策略策略用于做出采样决策的策略。
策略 > 延迟延迟该策略基于跟踪的持续时间进行采样。
策略 > 数字属性数字属性该策略基于数字属性(资源和记录)的数量进行采样。
策略 > 概率概率该策略采样跟踪的一定百分比。
策略 > 状态码状态码该策略基于状态码进行采样。
策略 > 字符串属性字符串属性该策略基于字符串属性(资源和记录)值匹配进行采样。
策略 > 速率限制速率限制该策略基于速率进行采样。
策略 > 跨度计数跨度计数该策略基于批次中的最小跨度数进行采样。
策略 > 布尔属性布尔属性该策略基于布尔属性(资源和记录)进行采样。
策略 > OTTL条件OTTL条件该策略基于给定的布尔OTTL条件(跨度和跨度事件)进行采样。
策略 > 跟踪状态跟踪状态该策略基于TraceState值匹配进行采样。
策略 > 和该策略基于多个策略进行采样,创建了一个 and 策略。
策略 > 和 > and_sub_policyand_sub_policy一个 and 策略类型下的策略集合。
策略 > 和 > and_sub_policy > 延迟延迟该策略基于跟踪的持续时间进行采样。
策略 > 和 > and_sub_policy > 数字属性数字属性该策略基于数字属性(资源和记录)进行采样。
策略 > 和 > and_sub_policy > 概率概率该策略采样跟踪的一定百分比。
策略 > 和 > and_sub_policy > 状态码状态码该策略基于状态码进行采样。
策略 > 和 > and_sub_policy > 字符串属性字符串属性该策略基于字符串属性(资源和记录)值匹配进行采样。
策略 > 和 > and_sub_policy > 速率限制速率限制该策略基于速率进行采样。
策略 > 和 > and_sub_policy > 跨度计数跨度计数该策略基于批次中的最小跨度数进行采样。
策略 > 和 > and_sub_policy > 布尔属性布尔属性该策略基于布尔属性(资源和记录)进行采样。
策略 > 和 > and_sub_policy > OTTL条件OTTL条件该策略基于给定的布尔OTTL条件(跨度和跨度事件)进行采样。
策略 > 和 > and_sub_policy > 跟踪状态跟踪状态该策略基于TraceState值匹配进行采样。
策略 > 组合组合该策略基于上述采样器的组合进行采样,每个采样器有排序和速率分配。
策略 > 组合 > composite_sub_policycomposite_sub_policy一个 composite 策略类型下的策略集合。
策略 > 组合 > composite_sub_policy > 延迟延迟该策略基于跟踪的持续时间进行采样。
策略 > 组合 > composite_sub_policy > 数字属性数字属性该策略基于数字属性(资源和记录)进行采样。
策略 > 组合 > 组合子策略 > 概率概率该策略采样跟踪的一定百分比。
策略 > 组合 > 组合子策略 > 状态码状态码该策略基于状态码进行采样。
策略 > 组合 > 组合子策略 > 字符串属性字符串属性该策略基于字符串属性(资源和记录)值匹配进行采样。
策略 > 组合 > 组合子策略 > 速率限制速率限制该策略基于速率进行采样。
策略 > 组合 > 组合子策略 > 跨度计数跨度计数该策略基于批次中的最小跨度数进行采样。
策略 > 组合 > 组合子策略 > 布尔属性布尔属性该策略基于布尔属性(资源和记录)进行采样。
策略 > 组合 > 组合子策略 > ottl条件OTTL条件该策略基于给定的布尔OTTL条件(跨度和跨度事件)进行采样。
策略 > 组合 > 组合子策略 > 跟踪状态跟踪状态该策略基于TraceState值匹配进行采样。
输出输出配置接收到的遥测数据发送到的位置。
debug_metricsdebug_metrics配置此组件生成以监控其状态的指标。

策略块

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

支持以下参数

名称类型描述默认值必需
名称字符串分配给策略的自定义名称。
类型字符串此策略的有效策略类型。

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

  • 当存在“反转不采样”决策时,跟踪不会被采样。
  • 当存在“采样”决策时,跟踪会被采样。
  • 当存在“反转采样”决策而没有“不采样”决策时,跟踪会被采样。
  • 在其他所有情况下,跟踪不会被采样。

“反转”决策是基于“invert_match”属性做出的决策,例如字符串、数值或布尔标签策略中的那种。

延迟块

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

支持以下参数

名称类型描述默认值必需
阈值_ms数字采样下限延迟阈值,以毫秒为单位。
upper_threshold_ms数字采样上限延迟阈值,以毫秒为单位。0

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

upper_threshold_ms0 将导致一个采样所有大于 threshold_ms 的策略。

numeric_attribute 块

numeric_attribute 块配置一个类型为 numeric_attribute 的策略。策略根据数字属性(资源和记录)进行采样。

支持以下参数

名称类型描述默认值必需
字符串与过滤器匹配的标签。
min_value数字属性的最低值,被认为是匹配。
max_value数字属性的最高值,被认为是匹配。
invert_match布尔值指示值必须不与属性值匹配。false

概率块

概率 块配置一个类型为 概率 的策略。策略采样一定比例的跟踪。

支持以下参数

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

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

status_code块

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

支持以下参数

名称类型描述默认值必需
status_codes字符串列表包含创建状态码过滤器采样策略评估器的可配置设置。

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

string_attribute块

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

支持以下参数

名称类型描述默认值必需
字符串与过滤器匹配的标签。
values字符串列表匹配属性值时使用的值或正则表达式的集合。
enabled_regex_matching布尔值确定是否通过正则表达式字符串匹配属性值。false
cache_max_size字符串Least Recently Used (LRU) Cache存储从《code>values中定义的正则表达式匹配结果的属性条目最大数量。
invert_match布尔值指示值或正则表达式不得与属性值匹配。false

rate_limiting块

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

支持以下参数

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

span_count块

《code>span_count块配置了一个类型为《code>span_count的策略。该策略基于批次中的最小span数量进行采样。如果批次中的所有跟踪都没有比阈值更多的span,则该批次不会被采样。

支持以下参数

名称类型描述默认值必需
min_spans数字跟踪中的最小span数量。
max_spans数字跟踪中的最大span数量。0

将《code>max_spans设置为《code>0,如果不想根据跟踪中的最大span数量限制策略采样。

boolean_attribute块

《code>boolean_attribute块配置了一个类型为《code>boolean_attribute的策略。该策略基于布尔属性(资源记录)进行采样。

支持以下参数

名称类型描述默认值必需
字符串匹配属性键。
value布尔值匹配属性值时使用的布尔值(《code>true或《code>false)。
invert_match布尔值指示值必须不与属性值匹配。false

ottl_condition块

《code>ottl_condition块配置了一个类型为《code>ottl_condition的策略。该策略基于给定的布尔OTTL条件(span span事件)进行采样。

支持以下参数

名称类型描述默认值必需
error_mode字符串如果OTTL条件评估失败时的错误处理。
span字符串列表span的OTTL条件。[]
spanevent字符串列表span事件的OTTL条件。[]

《code>error_mode支持的值包括:

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

至少应指定《code>span或《code>spanevent之一。也可以同时指定《code>span和《code>spanevent。

trace_state块

《code>trace_state块配置了一个类型为《code>trace_state的策略。该策略基于TraceState值匹配进行采样。

支持以下参数

名称类型描述默认值必需
字符串与过滤器匹配的标签。
values字符串列表匹配trace_state值时使用的值集合。

and块

《code>and块配置了一个类型为《code>and的策略。通过创建一个《code>and策略来根据多个策略进行采样。

and_sub_policy 块

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

支持以下参数

名称类型描述默认值必需
名称字符串分配给策略的自定义名称。
类型字符串此策略的有效策略类型。

组合块

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

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

composite_sub_policy 块

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

支持以下参数

名称类型描述默认值必需
名称字符串分配给策略的自定义名称。
类型字符串此策略的有效策略类型。

输出块

output 块配置了一组组件,用于将结果遥测数据转发到。

支持以下参数

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

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

debug_metrics 块

debug_metrics 块配置了此组件生成的用于监控其状态的度量。

支持以下参数

名称类型描述默认值必需
disable_high_cardinality_metrics布尔值是否禁用某些高基数度量。true
level字符串控制包装收集器发出的度量的详细程度。"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.tail_sampling 仅在提供无效配置时报告为不健康。

调试信息

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

示例

此示例在将跟踪数据发送到 otelcol.exporter.otlp 以进行进一步处理之前,对 Alloy 中的跟踪数据进行批处理。此示例展示了不切实际的策略数量,目的是演示如何设置每种类型。

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

otelcol.processor.tail_sampling "default" {
  decision_cache = {
    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 的导出可以被以下组件消费

注意

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