otelcol.processor.tail_sampling
otelcol.processor.tail_sampling
基于一组定义的策略采样跟踪。对于给定的跟踪,所有跨度必须由相同的收集器实例接收,才能进行有效的采样决策。
注意
otelcol.processor.tail_sampling
是 OpenTelemetry Collector Contribtail_sampling
处理器的一个包装器。如有必要,错误报告或功能请求将被重定向到上游存储库。
可以通过不同的标签指定多个 otelcol.processor.tail_sampling
组件。
用法
otelcol.processor.tail_sampling "LABEL" {
policy {
...
}
...
output {
traces = [...]
}
}
参数
otelcol.processor.tail_sampling
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
decision_wait | duration | 在做出采样决策之前,从跟踪的第一个跨度开始等待的时间。 | "30s" | 否 |
num_traces | int | 内存中保留的跟踪数。 | 50000 | 否 |
expected_new_traces_per_sec | int | 预期的新跟踪数量(有助于分配数据结构)。 | 0 | 否 |
decision_cache | object | 配置要保留在 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_policy | and_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_policy | composite_sub_policy | 一个 composite 策略类型下的策略集合。 | 否 |
策略 > 组合 > composite_sub_policy > 延迟 | 延迟 | 该策略基于跟踪的持续时间进行采样。 | 否 |
策略 > 组合 > composite_sub_policy > 数字属性 | 数字属性 | 该策略基于数字属性(资源和记录)进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 概率 | 概率 | 该策略采样跟踪的一定百分比。 | 否 |
策略 > 组合 > 组合子策略 > 状态码 | 状态码 | 该策略基于状态码进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 字符串属性 | 字符串属性 | 该策略基于字符串属性(资源和记录)值匹配进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 速率限制 | 速率限制 | 该策略基于速率进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 跨度计数 | 跨度计数 | 该策略基于批次中的最小跨度数进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 布尔属性 | 布尔属性 | 该策略基于布尔属性(资源和记录)进行采样。 | 否 |
策略 > 组合 > 组合子策略 > ottl条件 | OTTL条件 | 该策略基于给定的布尔OTTL条件(跨度和跨度事件)进行采样。 | 否 |
策略 > 组合 > 组合子策略 > 跟踪状态 | 跟踪状态 | 该策略基于TraceState值匹配进行采样。 | 否 |
输出 | 输出 | 配置接收到的遥测数据发送到的位置。 | 是 |
debug_metrics | debug_metrics | 配置此组件生成以监控其状态的指标。 | 否 |
策略块
策略
块配置组件使用的采样策略。至少需要一个 策略
块。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
名称 | 字符串 | 分配给策略的自定义名称。 | 是 | |
类型 | 字符串 | 此策略的有效策略类型。 | 是 |
每个策略都产生一个决策,处理器评估这些决策以做出最终决策
- 当存在“反转不采样”决策时,跟踪不会被采样。
- 当存在“采样”决策时,跟踪会被采样。
- 当存在“反转采样”决策而没有“不采样”决策时,跟踪会被采样。
- 在其他所有情况下,跟踪不会被采样。
“反转”决策是基于“invert_match”属性做出的决策,例如字符串、数值或布尔标签策略中的那种。
延迟块
延迟
块配置一个类型为 延迟
的策略。策略根据跟踪的持续时间进行采样。持续时间通过查看最早开始时间和最晚结束时间来确定,不考虑其间发生的事情。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
阈值_ms | 数字 | 采样下限延迟阈值,以毫秒为单位。 | 是 | |
upper_threshold_ms | 数字 | 采样上限延迟阈值,以毫秒为单位。 | 0 | 否 |
为了采样跟踪,其延迟应大于 threshold_ms
且小于或等于 upper_threshold_ms
。
upper_threshold_ms
的 0
将导致一个采样所有大于 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
设置如下:
- test-composite-policy-1 = 50% 的 max_total_spans_per_second = 50 spans_per_second
- test-composite-policy-2 = 25% 的 max_total_spans_per_second = 25 spans_per_second
- 为确保剩余容量被填满,使用 always_sample 作为策略之一。
composite_sub_policy 块
composite_sub_policy
块配置了由 composite
块使用的采样策略。在 composite
块内部至少需要有一个 composite_sub_policy
块。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
名称 | 字符串 | 分配给策略的自定义名称。 | 是 | |
类型 | 字符串 | 此策略的有效策略类型。 | 是 |
输出块
output
块配置了一组组件,用于将结果遥测数据转发到。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
日志 | list(otelcol.Consumer) | 要发送日志的消费者列表。 | [] | 否 |
度量 | list(otelcol.Consumer) | 要发送度量的消费者列表。 | [] | 否 |
跟踪 | list(otelcol.Consumer) | 要发送跟踪的消费者列表。 | [] | 否 |
您必须指定 output
块,但所有其参数都是可选的。默认情况下,遥测数据将被丢弃。根据需要配置 metrics
、logs
和 traces
参数,以将遥测数据发送到其他组件。
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"
。
导出字段
以下字段被导出,并可由其他组件引用
名称 | 类型 | 描述 |
---|---|---|
input | 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_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
的导出可以被以下组件消费
注意
连接某些组件可能不合理,或者组件可能需要进一步配置才能正确连接。请参阅相关文档获取更多详细信息。