Dataway テールサンプリング¶

機能¶

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

/v1/tail_sampling
/v1/tail_sampling_v2
/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 /v1/tail_sampling
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 分です。
送信フェーズでは、ワーカープールを使用して非同期で書き出します。

proxy¶

proxy モードでは、現在の Dataway はローカルにテールサンプリングの状態を保持しません。

/v1/tail_sampling および /v1/tail_sampling_v2 はバックエンドノードに転送されます。
/v1/tail_sampling_config はすべてのバックエンドノードにブロードキャストされます。

したがって、proxy モードでは：

aggregator_endpoint を設定する必要があります。
クライアントは有効な Guance-Pick-Key を携帯する必要があります。
バックエンドノードが実際のサンプリングと状態管理を担当します。

Warning

Kubernetes デプロイメントにおいて、フロントエンドの Dataway がテールサンプリングリクエストを特定のバックエンドノードに安定して転送する必要がある場合、aggregator_endpoint には安定した不変のバックエンドアドレスを指定する必要があります。この場合、バックエンドの Dataway は StatefulSet を使用してデプロイし、Pod アドレスと DNS 名を安定させ、フロントエンドの Dataway が固定的に転送できるようにすることをお勧めします。

ローカル設定¶

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
          }
        ]
      }
    ]
  }
}

Info

logging と rum は group_dimensions 設定を使用してグループ化のディメンションを指定します。data_ttl が空の場合、デフォルトはどちらも 1m です。

Warning

現在の実装では、設定内容の検証が行われます。trace では group_key=trace_id のみ許可されます。derived_metrics は現在サポートされていないため、設定するとエラーが返されます。

データレポートインターフェース¶

テールサンプリングデータのインターフェースは以下のとおりです。

POST /v1/tail_sampling
POST /v1/tail_sampling_v2

説明：

現在、両方のインターフェースは同じ処理ロジックを使用します。
standalone モードでは、リクエストボディは protobuf エンコードされた aggregate.DataPacket である必要があります。
proxy モードでは、リクエストはバックエンドノードに転送されます。

412 と pending cache¶

standalone モードにおいて、Dataway が起動したばかりで、対応する token + data_type のサンプリング設定がまだ配信されていない場合：

Dataway はまずこのデータをローカルの pending cache に格納します。
その後、412 Precondition Failed を返します。

現在の動作：

pending cache はメモリキャッシュです。
token + data_type ごとに一時保存されます。
設定が正常に配信されると、利用可能なデータは自動的に TailSamplingProcessor にドレインされます。
現在のデフォルトの最大キャッシュ数は 100000 パケットです。

規定された動作：

クライアントは 412 を受信した後、このデータは Dataway によって受け入れられたものと見なします。
クライアントは引き続き /v1/tail_sampling_config を送信するだけで問題ありません。
クライアントはこのデータを再送信する必要はありません。

異常系：

pending cache が満杯の場合、Dataway は 503 を返します。
この場合、リクエストは受け入れられたものと見なせません。

テールサンプリング組み込みメトリクス¶

テールサンプリング設定は builtin_metrics をサポートしています。これらのメトリクスは、テールサンプリングプロセッサによってサンプリング中に生成され、定期的な更新時にセンターに書き込まれます。

現在の組み込みメトリクスは以下のとおりです。

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 自動レポートメトリクス¶

サンプラー自身の builtin_metrics に加えて、apis/metrics_special.go は、テールサンプリング API の処理状況を説明するために、Dataway の自己観測メトリクスセットを自動的に管理します。

現在、テールサンプリングに関連するメトリクスは以下のとおりです。

メトリクス名	タイプ	タグ	説明
`dataway_http_api_body_size_bytes_total`	Counter	`api`, `token`	テールサンプリングインターフェースのリクエストボディの累積バイト数
`dataway_http_tail_sampling_trace_total`	Counter	`token`	受信した tracing グループ数
`dataway_http_tail_sampling_span_total`	Counter	`token`	受信した tracing span の総数
`dataway_http_tail_sampling_packet_send_total`	Counter	`token`, `data_type`, `result`	送信結果の統計。`result` には `success`、`failure`、`drop` が含まれます

これらのメトリクスは：

1 分ごとに収集されます。
dataway_aggregate メトリクスポイントに変換されます。
Dataway のデフォルトトークンを使用して /v1/write/metric にレポートされます。
レポート後、現在の累積値はリセットされます。

このメトリクスセットは、サンプリングルール自体のビジネス統計ではなく、テールサンプリングトラフィックを処理する Dataway 自身の実行状態を反映します。