Dataway 尾采样¶

功能介绍¶

Dataway 提供尾采样能力，对外接口包括：

• /v1/tail_sampling（raw payload；兼容 Datakit 2.10 的无 header zstd payload）
• /v1/tail_sampling_v2（历史 raw 兼容路径）
• /v2/tail_sampling（zstd payload）
• /v1/tail_sampling_config

尾采样用于先在 Dataway 侧接收按分组打包后的数据，再根据采样规则决定保留还是丢弃，最终把保留的数据写入中心。

当前支持三类数据：

• tracing
• logging
• rum

基本处理流程如下：

sequenceDiagram
autonumber

participant dk as Datakit/Client
participant dw as Dataway
participant ts as TailSamplingProcessor
participant kodo as Kodo

dk ->> dw: POST /v2/tail_sampling（zstd）或 /v1/tail_sampling（raw）
alt config ready
    dw ->> ts: ingest packet
    ts ->> dw: kept packets
    dw ->> kodo: write tracing/logging/rum
else config not ready
    dw ->> dw: pending cache
    dw -->> dk: 412 Precondition Failed
    dk ->> dw: POST /v1/tail_sampling_config
    dw ->> ts: update config and drain pending
end

工作模式¶

尾采样和聚合共用同一组模式配置：

• standalone
• proxy

standalone¶

standalone 模式下，当前 Dataway 直接处理尾采样数据：

• 接收 protobuf 编码的 aggregate.DataPacket
• 根据 token + data_type 查找尾采样配置
• 配置已就绪时，直接写入 TailSamplingProcessor
• 周期性取出到期分组并发送到对应数据类型写入接口

当前实现中：

• 采样窗口推进周期为 1 秒
• 派生指标刷新周期为 1 分钟
• 发送阶段使用 worker pool 异步写出

proxy¶

proxy 模式下，当前 Dataway 不保留本地尾采样状态：

• /v1/tail_sampling、/v1/tail_sampling_v2 和 /v2/tail_sampling 会转发到后端节点
• /v1/tail_sampling_config 会广播到所有后端节点

因此在 proxy 模式下：

• 必须配置 aggregator_endpoint
• 客户端需要携带合法的 Guance-Pick-Key
• 后端节点负责真正的采样和状态维护

本地配置¶

Dataway 本地没有单独的尾采样 YAML 配置项，尾采样使用和聚合相同的模式配置：

aggregator_mode: standalone
aggregator_endpoint:
  - http://dataway-0:9528
  - http://dataway-1:9528

环境变量：

DW_AGGREGATOR_MODE=standalone
DW_AGGREGATOR_ENDPOINTS=http://dataway-0:9528,http://dataway-1:9528

说明：

• standalone：当前节点自己持有尾采样状态
• proxy：当前节点只做转发或广播

在 Kubernetes 中，如果前置 Dataway 作为入口层、后置 Dataway 负责实际尾采样，后置节点更适合使用 StatefulSet 部署，并将 StatefulSet Pod 的稳定地址写入 aggregator_endpoint。

采样配置下发¶

尾采样规则通过接口下发，而不是写在 dataway.yaml 中：

POST /v1/tail_sampling_config

请求体为 JSON，顶层结构如下：

{
  "version": 1,
  "trace": {},
  "logging": {},
  "rum": {}
}

其中：

• trace 对应 tracing 尾采样配置
• logging 对应 logging 尾采样配置
• rum 对应 rum 尾采样配置

tracing 配置示例¶

{
  "version": 1,
  "trace": {
    "version": 1,
    "data_ttl": "5m",
    "group_key": "trace_id",
    "pipelines": [
      {
        "name": "keep-all",
        "type": "probabilistic",
        "rate": 1
      }
    ],
    "builtin_metrics": [
      {
        "name": "trace_total_count",
        "enabled": true
      }
    ]
  }
}

说明：

• trace.group_key 当前只能是 trace_id
• trace.data_ttl 为空时默认 5m
• pipelines 支持 condition 和 probabilistic
• condition 使用 action=keep/drop
• probabilistic 使用 rate=0~1

logging 配置示例¶

{
  "version": 1,
  "logging": {
    "version": 1,
    "data_ttl": "1m",
    "group_dimensions": [
      {
        "group_key": "service",
        "pipelines": [
          {
            "name": "keep-all",
            "type": "probabilistic",
            "rate": 1
          }
        ]
      }
    ]
  }
}

rum 配置示例¶

{
  "version": 1,
  "rum": {
    "version": 1,
    "data_ttl": "1m",
    "group_dimensions": [
      {
        "group_key": "session_id",
        "pipelines": [
          {
            "name": "keep-all",
            "type": "probabilistic",
            "rate": 1
          }
        ]
      }
    ]
  }
}

数据上报接口¶

尾采样数据接口：

POST /v1/tail_sampling
POST /v1/tail_sampling_v2
POST /v2/tail_sampling

说明：

• /v1/tail_sampling 接收未压缩的 PBPoints payload；此外仅兼容 Datakit 2.10 发送的无压缩协商 header、PayloadCompression=1 的 zstd packet
• /v1/tail_sampling_v2 是历史 raw 兼容路径，与 /v1/tail_sampling 走同一套处理逻辑；它不是 zstd 协议路径
• /v2/tail_sampling 只接收 zstd payload；请求必须同时满足：
• header Guance-Tail-Sampling-Payload-Compression: zstd
• aggregate.DataPacket.PayloadCompression=1
• standalone 模式下，请求体需要是 protobuf 编码的 aggregate.DataPacket
• proxy 模式下，请求会被转发到后端节点

客户端应使用以下协议组合：

常见响应状态码：

压缩协议与滚动升级¶

Datakit 2.11 及以上默认通过 /v2/tail_sampling 发送 zstd payload。Dataway 会显式校验路径、header 和 packet 压缩字段：

• 旧版 Dataway 不认识 /v2/tail_sampling，会返回 404
• 新版 Dataway 收到不支持的压缩方法、缺失 header、raw v2 packet，或不属于 Datakit 2.10 兼容组合的 v1 zstd packet 时，返回 415 Unsupported Media Type
• Datakit 收到 404 或 415 后，会把当前 packet 还原为 raw，改用 /v1/tail_sampling 重试，并将该 endpoint 的 legacy 能力缓存 10 分钟
• 降级发送前，Datakit 按解压后的 protobuf body 大小拆包，确保每个可拆分 raw packet 不超过 Dataway 的 MaxRawBodySize，避免高压缩比 packet 在旧节点上被 413 拒绝
• Datakit 2.10 会把 zstd packet 直接发送到 /v1/tail_sampling 且不带协商 header；新版 Dataway 为该已发布版本保留精确兼容
• 早于 2.10 的 Datakit 继续发送 raw v1 数据；新版 Dataway 会补算 span 谓词并在进入时间轮前按收益决定是否压缩

具备上述双向兼容后，升级到 Datakit 2.11+ 与新版 Dataway 时可以混合滚动。Datakit 2.10 与不支持该兼容的旧版 Dataway 仍不兼容，应先升级其中一端到带兼容逻辑的版本。

kept 包发送与退出恢复¶

Dataway 对已经决定保留的 packet 使用有界 worker pool 和磁盘溢出队列发送：

• 发送失败最多退避重试 3 次；重试耗尽才计入 failure/drop
• 内存队列满时先进入异步 overflow 通道，再写入磁盘队列；Dataway 重启后会主动打开已有队列并继续发送
• 进程退出时，overflow、内存队列和退避中的 packet 优先写入健康磁盘
• 磁盘不可用时，退出阶段的网络兜底重试共享 5 秒预算；预算耗尽的 packet 会明确计入失败指标并输出汇总日志

412 与 pending cache¶

在 standalone 模式下，如果 Dataway 刚启动、对应 token + data_type 的采样配置还没下发：

• Dataway 会先把这批数据放入本地 pending cache
• 然后返回 412 Precondition Failed

当前行为：

• pending cache 是内存缓存
• 按 token + data_type 暂存
• 配置下发成功后，会自动把可用数据 drain 到 TailSamplingProcessor
• 当前默认最多缓存 100000 个 packet

约定行为：

• 客户端收到 412 后，视为这批数据已经被 Dataway 接住
• 客户端只需要继续发送 /v1/tail_sampling_config
• 客户端不需要重复发送这批数据

异常情况：

• 如果 pending cache 已满，Dataway 会返回 503
• 这种情况下不能再把请求视为已接收

尾采样指标集（tail_sampling）¶

尾采样配置支持 builtin_metrics。这些指标由尾采样处理器在采样过程中生成，并在周期性刷新时写入中心。写入中心后，指标集（measurement）名为 tail_sampling，例如在观测云中查询 field trace_dropped_count、tag stage/decision/data_type。

当前内置指标如下。

tracing¶

• trace_total_count
• trace_kept_count
• trace_dropped_count
• trace_error_count
• span_total_count
• trace_duration

其中：

• trace_duration 为时长分布指标
• 其它为计数指标

logging¶

• logging_total_count
• logging_error_count
• logging_kept_count
• logging_dropped_count

rum¶

• rum_total_count
• rum_kept_count
• rum_dropped_count

说明：

• builtin_metrics 为空时，当前默认会把该数据类型支持的内置指标全部开启
• 这些指标来自尾采样处理过程本身，不是 Dataway 自身运行指标

Dataway 自动上报指标（指标集 dataway_aggregate）¶

除采样器自己的 builtin_metrics（写入 tail_sampling 指标集）外，apis/metrics_special.go 还会自动维护一组 Dataway 自观测指标，用来描述尾采样 API 的处理情况。这组指标汇总后进入中心的 dataway_aggregate 指标集，字段前缀为 dataway_http_tail_sampling_*。

当前与尾采样相关的指标包括：

这些指标会：

• 每 1 分钟采集一次
• 被转换为 dataway_aggregate 指标点
• 使用 Dataway 默认 token 上报到 /v1/write/metric
• 上报后重置当前累积值
• 指标中的 token 标签固定为 redacted，不保留原始 token 的任何片段

这组指标反映的是 Dataway 自身处理尾采样流量的运行状态，而不是采样规则本身的业务统计。

两个中心指标集的分工：

• tail_sampling：采样规则的业务统计（各 token 一份），如 trace_kept_count / trace_dropped_count
• dataway_aggregate：Dataway 处理过程的运行状态（dataway 默认 token 聚合），如各阶段计数、发送/积压、worker 状态