otelcol.processor.tail_sampling
otelcol.processor.tail_sampling
基于一组定义的策略对追踪进行采样。给定追踪的所有 span必须由同一收集器实例接收,才能做出有效的采样决策。
注意
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 | 自追踪的第一个 span 以来,做出采样决策的等待时间。 | "30s" | 否 |
num_traces | int | 内存中保留的追踪数量。 | 50000 | 否 |
expected_new_traces_per_sec | int | 预期的新追踪数量(有助于分配数据结构)。 | 0 | 否 |
decision_cache | object | 配置采样决策的缓存。 | {} | 否 |
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
的定义中支持以下块
层级结构 | 块 | 描述 | 必需 |
---|---|---|---|
policy | policy | 用于做出采样决策的策略。 | 是 |
policy > latency | latency | 该策略基于追踪的持续时间进行采样。 | 否 |
policy > numeric_attribute | numeric_attribute | 该策略基于数字属性(资源和记录)进行采样。 | 否 |
policy > probabilistic | probabilistic | 该策略对一定百分比的追踪进行采样。 | 否 |
policy > status_code | status_code | 该策略基于状态代码进行采样。 | 否 |
policy > string_attribute | string_attribute | 该策略基于字符串属性(资源和记录)值匹配进行采样。 | 否 |
policy > rate_limiting | rate_limiting | 该策略基于速率进行采样。 | 否 |
policy > span_count | span_count | 该策略基于批次内的最小 span 数量进行采样。 | 否 |
policy > boolean_attribute | boolean_attribute | 该策略基于布尔属性(资源和记录)进行采样。 | 否 |
policy > ottl_condition | ottl_condition | 该策略基于给定的布尔 OTTL 条件(span 和 span 事件)进行采样。 | 否 |
policy > trace_state | trace_state | 该策略基于 TraceState 值匹配进行采样。 | 否 |
policy > and | and | 该策略基于多个策略进行采样,创建 “and” 策略。 | 否 |
policy > and > and_sub_policy | and_sub_policy | “and” 策略类型下的一组策略。 | 否 |
policy > and > and_sub_policy > latency | latency | 该策略基于追踪的持续时间进行采样。 | 否 |
policy > and > and_sub_policy > numeric_attribute | numeric_attribute | 该策略基于数字属性(资源和记录)进行采样。 | 否 |
policy > and > and_sub_policy > probabilistic | probabilistic | 该策略对一定百分比的追踪进行采样。 | 否 |
policy > and > and_sub_policy > status_code | status_code | 该策略基于状态代码进行采样。 | 否 |
policy > and > and_sub_policy > string_attribute | string_attribute | 该策略基于字符串属性(资源和记录)值匹配进行采样。 | 否 |
policy > and > and_sub_policy > rate_limiting | rate_limiting | 该策略基于速率进行采样。 | 否 |
policy > and > and_sub_policy > span_count | span_count | 该策略基于批次内的最小 span 数量进行采样。 | 否 |
policy > and > and_sub_policy > boolean_attribute | boolean_attribute | 该策略基于布尔属性(资源和记录)进行采样。 | 否 |
policy > and > and_sub_policy > ottl_condition | ottl_condition | 该策略基于给定的布尔 OTTL 条件(span 和 span 事件)进行采样。 | 否 |
policy > and > and_sub_policy > trace_state | trace_state | 该策略基于 TraceState 值匹配进行采样。 | 否 |
policy > composite | composite | 该策略基于上述采样器的组合进行采样,并具有每个采样器的排序和速率分配。 | 否 |
policy > composite > composite_sub_policy | composite_sub_policy | “composite” 策略类型下的一组策略。 | 否 |
policy > composite > composite_sub_policy > latency | latency | 该策略基于追踪的持续时间进行采样。 | 否 |
policy > composite > composite_sub_policy > numeric_attribute | numeric_attribute | 该策略基于数字属性(资源和记录)进行采样。 | 否 |
policy > composite > composite_sub_policy > probabilistic | probabilistic | 该策略对一定百分比的追踪进行采样。 | 否 |
policy > composite > composite_sub_policy > status_code | status_code | 该策略基于状态代码进行采样。 | 否 |
policy > composite > composite_sub_policy > string_attribute | string_attribute | 该策略基于字符串属性(资源和记录)值匹配进行采样。 | 否 |
policy > composite > composite_sub_policy > rate_limiting | rate_limiting | 该策略基于速率进行采样。 | 否 |
policy > composite > composite_sub_policy > span_count | span_count | 该策略基于批次内的最小 span 数量进行采样。 | 否 |
policy > composite > composite_sub_policy > boolean_attribute | boolean_attribute | 该策略基于布尔属性(资源和记录)进行采样。 | 否 |
policy > composite > composite_sub_policy > ottl_condition | ottl_condition | 该策略基于给定的布尔 OTTL 条件(span 和 span 事件)进行采样。 | 否 |
policy > composite > composite_sub_policy > trace_state | trace_state | 该策略基于 TraceState 值匹配进行采样。 | 否 |
output | output | 配置将接收到的遥测数据发送到哪里。 | 是 |
debug_metrics | debug_metrics | 配置此组件生成的用于监控其状态的指标。 | 否 |
policy 块
policy
块配置组件使用的采样策略。至少需要一个 policy
块。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
name | string | 赋予策略的自定义名称。 | 是 | |
type | string | 此策略的有效策略类型。 | 是 |
每个策略都会产生一个决策,处理器会评估这些决策以做出最终决策
- 当存在 “反向非采样” 决策时,追踪将不被采样。
- 当存在 “采样” 决策时,追踪将被采样。
- 当存在 “反向采样” 决策且没有 “非采样” 决策时,追踪将被采样。
- 在所有其他情况下,追踪不会被采样。
“反向” 决策是基于 “invert_match” 属性做出的决策,例如来自字符串、数字或布尔标签策略的决策。
latency 块
latency
块配置类型为 latency
的策略。该策略基于追踪的持续时间进行采样。持续时间通过查看最早的开始时间和最晚的结束时间来确定,而无需考虑中间发生了什么。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
threshold_ms | number | 采样的较低延迟阈值,以毫秒为单位。 | 是 | |
upper_threshold_ms | number | 采样的较高延迟阈值,以毫秒为单位。 | 0 | 否 |
对于要采样的追踪,其延迟应大于 threshold_ms
且小于或等于 upper_threshold_ms
。
upper_threshold_ms
为 0
将导致策略采样任何大于 threshold_ms
的值。
numeric_attribute 块
numeric_attribute
块配置类型为 numeric_attribute
的策略。该策略基于数字属性(资源和记录)进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 过滤器与之匹配的标签。 | 是 | |
min_value | number | 被视为匹配的属性的最小值。 | 是 | |
max_value | number | 被视为匹配的属性的最大值。 | 是 | |
invert_match | bool | 指示值不得与属性值匹配。 | false | 否 |
probabilistic 块
probabilistic
块配置类型为 probabilistic
的策略。该策略对一定百分比的追踪进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
sampling_percentage | number | 追踪被采样的百分比率。 | 是 | |
hash_salt | string | 见下文。 | 否 |
使用 hash_salt
配置哈希盐。这在多层收集器具有不同采样率的场景中非常重要。如果多个收集器使用相同的盐但采样率不同,则通过一层可能也会通过另一层,即使收集器的采样率不同。配置不同的盐可以避免这种情况。
status_code 块
status_code
块配置类型为 status_code
的策略。该策略基于状态代码进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
status_codes | list(string) | 包含用于创建状态代码过滤器采样策略评估器的可配置设置。 | 是 |
status_codes
值必须为 “OK”、“ERROR” 或 “UNSET”。
string_attribute 块
string_attribute
块配置类型为 string_attribute
的策略。该策略基于字符串属性(资源和记录)值匹配进行采样。同时支持精确值匹配和正则表达式值匹配。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 过滤器与之匹配的标签。 | 是 | |
values | list(string) | 用于与属性值匹配的值或正则表达式集。 | 是 | |
enabled_regex_matching | bool | 确定是否通过正则表达式字符串匹配属性值。 | false | 否 |
cache_max_size | string | 最近最少使用 (LRU) 缓存的最大属性条目数,该缓存存储在 values 中定义的正则表达式的匹配结果。 | 否 | |
invert_match | bool | 指示值或正则表达式不得与属性值匹配。 | false | 否 |
rate_limiting 块
rate_limiting
块配置类型为 rate_limiting
的策略。该策略基于速率进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
spans_per_second | number | 设置每秒可以处理的最大 span 数量。 | 是 |
span_count 块
span_count
块配置类型为 span_count
的策略。该策略基于批次内的最小 span 数量进行采样。如果批次内所有追踪的 span 数量都少于阈值,则该批次将不被采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
min_spans | number | 追踪中的最小 span 数量。 | 是 | |
max_spans | number | 追踪中的最大 span 数量。 | 0 | 否 |
如果您不想根据追踪中的最大 span 数量限制策略采样,请将 max_spans
设置为 0
。
boolean_attribute 块
boolean_attribute
块配置类型为 boolean_attribute
的策略。该策略基于布尔属性(资源和记录)进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 要匹配的属性键。 | 是 | |
value | bool | 在与属性值匹配时使用的布尔值 (true 或 false )。 | 是 | |
invert_match | bool | 指示值不得与属性值匹配。 | false | 否 |
ottl_condition 块
ottl_condition
块配置类型为 ottl_condition
的策略。该策略基于给定的布尔 OTTL 条件(span 和 span 事件)进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
error_mode | string | 如果 OTTL 条件评估失败,则进行错误处理。 | 是 | |
span | list(string) | span 的 OTTL 条件。 | [] | 否 |
spanevent | list(string) | span 事件的 OTTL 条件。 | [] | 否 |
error_mode
支持的值为
ignore
:忽略条件返回的错误,记录错误,并继续下一个条件。这是推荐模式。silent
:忽略条件返回的错误,不记录错误,并继续下一个条件。propagate
:将错误返回到管道上游。这将导致有效负载从 Alloy 中丢弃。
应至少指定 span
或 spanevent
之一。也可以同时指定 span
和 spanevent
。
trace_state 块
trace_state
块配置类型为 trace_state
的策略。该策略基于 TraceState 值匹配进行采样。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
key | string | 过滤器与之匹配的标签。 | 是 | |
values | list(string) | 用于与 trace_state 值匹配的值集。 | 是 |
and 块
and
块配置类型为 and
的策略。该策略通过创建 “and” 策略基于多个策略进行采样。
and_sub_policy 块
and_sub_policy
块配置由 and
块使用的采样策略。在 and
块内至少需要一个 and_sub_policy
块。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
name | string | 赋予策略的自定义名称。 | 是 | |
type | string | 此策略的有效策略类型。 | 是 |
composite 块
composite
块配置类型为 composite
的策略。此策略基于上述采样器的组合进行采样,并具有每个采样器的排序和速率分配。速率分配为每个策略顺序分配一定百分比的 span。例如,如果 max_total_spans_per_second
设置为 100,则 rate_allocation
设置如下
- test-composite-policy-1 = max_total_spans_per_second 的 50% = 50 spans_per_second
- test-composite-policy-2 = max_total_spans_per_second 的 25% = 25 spans_per_second
- 为了确保剩余容量被填满,请使用 always_sample 作为其中一个策略。
composite_sub_policy 块
composite_sub_policy
块配置由 composite
块使用的采样策略。在 composite
块内至少需要一个 composite_sub_policy
块。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
name | string | 赋予策略的自定义名称。 | 是 | |
type | string | 此策略的有效策略类型。 | 是 |
output 块
output
块配置一组组件,用于将生成的遥测数据转发到这些组件。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
logs | list(otelcol.Consumer) | 要将日志发送到的消费者列表。 | [] | 否 |
metrics | list(otelcol.Consumer) | 要将指标发送到的消费者列表。 | [] | 否 |
traces | list(otelcol.Consumer) | 要将追踪发送到的消费者列表。 | [] | 否 |
您必须指定 output
块,但其所有参数都是可选的。默认情况下,遥测数据将被丢弃。相应地配置 metrics
、logs
和 traces
参数,以将遥测数据发送到其他组件。
debug_metrics 块
debug_metrics
块配置此组件生成的用于监控其状态的指标。
支持以下参数
名称 | 类型 | 描述 | 默认值 | 必需 |
---|---|---|---|---|
disable_high_cardinality_metrics | boolean | 是否禁用某些高基数指标。 | true | 否 |
level | string | 控制包装的收集器发出的指标的详细程度。 | "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"
。
导出的字段
以下字段已导出,可以被其他组件引用
名称 | 类型 | 描述 |
---|---|---|
input | otelcol.Consumer | 其他组件可用于向其发送遥测数据的值。 |
input
接受任何遥测信号(指标、日志或追踪)的 otelcol.Consumer
数据。
组件健康状况
仅当 otelcol.processor.tail_sampling
被赋予无效配置时,才会被报告为不健康。
调试信息
otelcol.processor.tail_sampling
不公开任何组件特定的调试信息。
示例
此示例在将追踪数据从 Alloy 发送到 otelcol.exporter.otlp 以进行进一步处理之前,对其进行批处理。此示例展示了一个不切实际的策略数量,目的是演示如何设置每种类型。
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
具有可以被以下组件使用的导出
注意
连接某些组件可能不合理,或者组件可能需要进一步配置才能使连接正常工作。有关更多详细信息,请参阅链接的文档。