Dataway テールサンプリング¶

機能¶

Dataway はテールサンプリング機能を提供します。外部インターフェースは以下の通りです。

• /v1/tail_sampling（raw payload；Datakit 2.10 のヘッダーレス zstd payload と互換性あり）
• /v1/tail_sampling_v2（従来の raw 互換パス）
• /v2/tail_sampling（zstd payload）
• /v1/tail_sampling_config

テールサンプリングは、まず Dataway 側でグループ化されたデータを受信し、サンプリングルールに基づいて保持または破棄を決定し、最終的に保持されたデータをセンターに書き込みます。

現在サポートしているデータは次の3種類です。

• 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 が送信する、圧縮ネゴシエーションヘッダーなし、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 はパス、ヘッダー、packet 圧縮フィールドを明示的に検証します。

• 旧バージョンの Dataway は /v2/tail_sampling を認識できず、404 を返します。
• 新バージョンの Dataway は、サポートされていない圧縮方法、ヘッダー欠落、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 ボディサイズに基づいてパケットを分割し、分割可能な各 raw packet が Dataway の MaxRawBodySize を超えないようにします。これにより、圧縮率の高い packet が古いノードで 413 拒否されるのを防ぎます。
• Datakit 2.10 は zstd packet を /v1/tail_sampling に直接送信し、ネゴシエーションヘッダーは付けません。新しい 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 ごとに一時保存されます
• 設定の配信が成功すると、利用可能なデータは自動的に 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 自身がテールサンプリングトラフィックを処理する際の実行状態を反映し、サンプリングルール自体のビジネス統計ではありません。

2 つのセンター指標セットの役割分担：

• tail_sampling：サンプリングルールのビジネス統計（token ごとに1つ）、例：trace_kept_count / trace_dropped_count
• dataway_aggregate：Dataway 処理プロセスの実行状態（dataway デフォルト token で集約）、例：各フェーズのカウント、送信/滞留、ワーカー状態