Dataway メトリクス集約¶

機能¶

Dataway は集約アップロード機能を提供し、外部インターフェースは /v1/aggregate です。

この機能は主に、Dataway 側で集約されたメトリクスデータを受信し、ウィンドウ単位で整理してからセンターに転送するために使用されます。現在、次の2つの動作モードをサポートしています。

standalone：現在の Dataway が直接集約パッケージを受信し、ローカルの集約キャッシュに書き込み、ウィンドウの期限が切れた後に Kodo の /v1/write/metric に送信します。
proxy：現在の Dataway はローカル集約を行わず、/v1/aggregate リクエストをバックエンドの Dataway ノードに転送するのみです。

基本的な処理フローは次のとおりです。

sequenceDiagram
autonumber

participant dk as Datakit/Client
participant dw as Dataway
participant cache as Aggregate Cache
participant kodo as Kodo

dk ->> dw: POST /v1/aggregate
alt standalone
    dw ->> cache: write aggregate batch
    cache ->> dw: expired windows
    dw ->> kodo: POST /v1/write/metric
else proxy
    dw ->> dw: pick backend endpoint
    dw ->> kodo: forward request
end

動作モード¶

standalone¶

standalone モードでは、Dataway はリクエストボディを aggregate.Batchs にデコードし、ローカルの aggregate.Cache に書き込みます。

現在の実装では：

集約キャッシュのウィンドウは 1 分です。
Dataway は 1 秒ごとに期限切れウィンドウをチェックします。
ウィンドウデータはワークスペースの token でグループ化されます。
各 token ごとに /v1/write/metric が個別に送信されます。

このモードは、集約機能を Dataway 側に集中させ、Dataway が最終的なメトリクスをセンターに書き込む責任を負う場合に適しています。

proxy¶

proxy モードでは、Dataway は集約コンテンツ自体を処理せず、リクエストヘッダー Guance-Pick-Key に基づいてリクエストをバックエンドノードに転送します。

target = aggregator_endpoint[pick_key % len(aggregator_endpoint)]

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

aggregator_endpoint を設定する必要があります。
クライアントは有効な Guance-Pick-Key を保持している必要があります。
現在のノードは転送のみを担当し、集約ウィンドウの状態は保持しません。

このモードは、入口層で負荷分散を行い、集約状態をバックエンドノードに固定する場合に適しています。

Warning

Kubernetes デプロイメントにおいて、フロントエンドの Dataway が /v1/aggregate リクエストを特定のバックエンドノードに安定して転送する必要がある場合、aggregator_endpoint には変動しないバックエンドアドレスを指定する必要があります。この場合、バックエンド Dataway を StatefulSet でデプロイする方が適しています。これにより、各 Pod が固定のネットワーク識別子を持ち、フロントエンド Dataway が固定のエンドポイントに従って転送できるようになります。

設定方法¶

集約に関する設定項目は次のとおりです。

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

フィールド説明：

aggregator_mode
指定可能な値：standalone、proxy
空の場合、デフォルトで proxy として処理されます。
aggregator_endpoint
proxy モードにおけるバックエンドノードのリストです。
standalone モードでは設定は必須ではありません。

対応する環境変数は次のとおりです。

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

Warning

aggregator_mode が空の場合、Dataway は proxy として処理します。ただし、このとき同時に aggregator_endpoint が設定されていない場合、集約機能は初期化されず、対応する /v1/aggregate ルートも有効になりません。

設定例¶

スタンドアロン集約：

aggregator_mode: standalone

入口からバックエンド集約ノードへの転送：

aggregator_mode: proxy
aggregator_endpoint:
  - http://dataway-0.dataway:9528
  - http://dataway-1.dataway:9528

Kubernetes では、上記のアドレスは通常、StatefulSet の Pod の安定した DNS 名に対応します。

インターフェース説明¶

集約インターフェース：

POST /v1/aggregate

説明：

認証方法は、Dataway の他の書き込みインターフェースと同様に、標準のトークン検証ロジックを使用します。
standalone モードでは、リクエストボディは aggregate.Batchs の protobuf エンコードである必要があります。
proxy モードでは、クライアントは追加でリクエストヘッダー Guance-Pick-Key を保持する必要があります。

応答動作：

standalone モードでは、データがローカル集約キャッシュに正常に書き込まれた場合に成功を返します。
proxy モードでは、現在のノードはリクエストをターゲットのバックエンドに転送し、応答ステータスコードはターゲットノードの応答に従います。

組み込みメトリクス¶

Dataway は集約リクエストを処理する際に、一連の組み込み統計メトリクスを維持します。現在、集約に直接関連するメトリクスは次のとおりです。

メトリクス名	タイプ	タグ	説明
`dataway_http_api_body_size_bytes_total`	Counter	`api`, `token`	`/v1/aggregate` リクエストボディの累積バイト数
`dataway_http_aggr_point_total`	Counter	`api`, `token`	集約パッケージに書き込まれた累積ポイント数

タグ説明：

api：インターフェースパス。現在の集約シナリオでは、通常 /v1/aggregate です。
token：データが属するワークスペースのトークン。

これらのメトリクスは、集約の入口トラフィック、書き込み規模、および異なるワークスペース間のリクエスト分布を観察するために使用されます。

自動報告メトリクス¶

apis/metrics_special.go は、定期的に上記の組み込みメトリクスをメトリクスポイントに変換し、Dataway 自身を通じて報告を継続します。

現在の動作は次のとおりです。

1 分ごとに現在の累積値を収集します。
自動的にメジャーメント dataway_aggregate に変換されます。
Dataway のデフォルトのワークスペーストークンを使用して /v1/write/metric に報告されます。
報告が成功すると、今回の累積カウントがリセットされます。

フィールドマッピングルール：

Counter メトリクス：
メトリクス名がそのままフィールド名になります。
Summary メトリクス：
<metric>_sum を生成します。
<metric>_count を生成します。
<metric>_quantile_<quantile> を生成します。

タグマッピングルール：

Prometheus メトリクスのタグは、そのままメトリクスポイントのタグに変換されます。

例えば、dataway_http_api_body_size_bytes_total{api="/v1/aggregate",token="tkn_xxx"} は、フィールド名が dataway_http_api_body_size_bytes_total である dataway_aggregate メトリクスポイントに変換されます。

Info

現在の自動変換ロジックは、Counter と Summary をサポートしています。Gauge、Histogram などのタイプは、現在の実装では報告ポイントに変換されません。

ユースケース¶

入口付近でメトリクスを集約してから、統一的にセンターに書き込む必要がある場合。
集約トラフィックと実際の書き込みノードを分離する必要がある場合。
集約リクエスト量、リクエストボディサイズ、およびポイント数を監視する必要がある場合。