EdgeFlow 方式のテールサンプリング¶
EdgeFlow は DataKit と Dataway の間にデプロイされ、trace_id ごとにトレースの Span を集約し、EdgeFlow ローカル DSL ルールに基づいて保持または破棄を決定します。DataKit の Aggregator はグルーピング、パッケージ化、送信を担当し、実際のサンプリング条件、サンプリングレート、待機時間は EdgeFlow に適用済みのルールに従います。
本記事では tracing テールサンプリングを設定します。例ではエラートレースを優先的に保持し、ハートビートと 404 のトレースを破棄し、その他のトレースを 10% サンプリングします。SDK または収集側で既に破棄された Span は復元できません。
前提条件とインストールリソース¶
バージョン要件:DataKit 2.11 以上、EdgeFlow 1.0.1。ホストインストールパッケージは Linux AMD64 向けです。本記事では EdgeFlow ローカルの rules validate、rules test、rules apply コマンドでサンプリングルールを管理します。
| インストールリソース | ダウンロード先 |
|---|---|
| EdgeFlow ホストインストールパッケージ(Linux AMD64) | インストールパッケージをダウンロード |
| EdgeFlow コンテナイメージ | pubrepo.guance.com/guance/edgeflow:1.0.1 |
元の Dataway アドレス、ワークスペース token、独立した管理 token、書き込み可能な状態ディレクトリを準備します。DataKit が EdgeFlow のデータポートにアクセスでき、EdgeFlow が元の Dataway にアクセスできることを確認します。例では内部ネットワークの HTTP アドレスを使用します。ホストインストールの例では Linux/systemd を使用します。Docker インストールには利用可能な Docker Engine と永続データボリュームが必要です。事前に DataKit の設定と既存のルールをバックアップしてください。
操作順序:接続方式の選択 → EdgeFlow のインストール → ローカル DSL ルールの適用 → DataKit の設定 → サンプリング結果の検証。ホストインストールと Docker インストールはどちらか一方を選択します。
接続方式の選択¶
| 比較項目 | フルプロキシモード | サンプリング専用モード |
|---|---|---|
[dataway].urls |
EdgeFlow を指す | 元の Dataway を保持 |
[aggregator].endpoints |
空。通常の出口を再利用 | 独立した EdgeFlow ノードを指す |
| tracing | EdgeFlow でサンプリング後に Dataway へ送信 | Aggregator から EdgeFlow へ送信し、サンプリング後に Dataway へ送信 |
| 通常のログ、メトリクスなど | EdgeFlow 経由で転送 | 元の Dataway へ直接送信 |
| デプロイ | 1 つの接続経路で単一インスタンスを使用 | 複数の独立インスタンスを使用でき、trace ごとに分散 |
| 障害の影響 | その通常出口のすべてのデータに影響 | 主にトレースのサンプリングに影響し、その他のデータは元の出口を維持 |
本記事では tracing tail ルールのみを追加します。既存の集約、ルーティングルール、専用 Sink の処理範囲は個別に確認する必要があります。
フルプロキシ:DataKit → 単一インスタンス EdgeFlow → 元の Dataway
サンプリング専用モード:DataKit ── 通常のログ、メトリクス ─────────→ 元の Dataway
└── Aggregator → EdgeFlow A/B ──→ 元の Dataway
フルプロキシモードでは単一インスタンスを使用します。 通常のリクエストには複数の trace が含まれる場合があり、ランダムなロードバランシングでリクエストを複数の EdgeFlow インスタンスに分散することはできません。
サンプリング専用モードの複数ノードでは、すべての DataKit が数と順序の一致した endpoint リストを使用し、各アドレスが 1 つの固定インスタンスのみに対応する必要があります。各 EdgeFlow インスタンスは独立した状態ディレクトリまたはデータボリュームを使用し、同じローカル DSL ルールを適用します。trace ごとの分散をランダムなロードバランシングで代替することはできず、複数のノードで状態ディレクトリを共有することもできません。
endpoint の数や順序を変更すると trace の帰属が変わるため、切り替えと処理中データのドレインを統一的に計画する必要があります。ノード間でルールが自動同期されたり、既存のトレース状態が引き継がれたりすることはありません。
ホストインストール¶
以下のプレースホルダー値は実際の値に置き換える必要があります。<DATAWAY_HOST> は元の Dataway ホスト、<EDGEFLOW_HOST> は EdgeFlow ホスト、<WORKSPACE_TOKEN> はワークスペース token、<ADMIN_TOKEN> は管理認証情報です。例のワークスペース名は demo、データポートは 9529、管理ポートはローカルホストからのみアクセス可能な 9530 です。
バイナリとディレクトリのインストール¶
Linux AMD64 インストールパッケージをダウンロードして展開し、実際のバージョンを確認します:
curl -fL 'https://static.guance.com/edgeflow/edgeflow-linux-amd64.tar.gz' -o edgeflow-linux-amd64.tar.gz
mkdir -p edgeflow-package
tar -xzf edgeflow-linux-amd64.tar.gz -C edgeflow-package
cd edgeflow-package
./edgeflow --version
ダウンロードアドレスにはバージョン番号が含まれていないため、インストール前にバイナリのバージョンが本記事で使用する 1.0.1 と一致することを確認してください。その後、次を実行します:
sudo useradd --system --user-group --home-dir /var/lib/edgeflow --shell /usr/sbin/nologin edgeflow
sudo install -m 0755 ./edgeflow /usr/local/bin/edgeflow
sudo install -d -m 0755 /etc/edgeflow /etc/edgeflow/rules
sudo install -d -o edgeflow -g edgeflow -m 0750 /var/lib/edgeflow
ユーザーが既に存在する場合は useradd をスキップします。アップグレード時は元の設定と状態ディレクトリを保持します。
実行設定と認証情報¶
sudoedit /etc/edgeflow/edgeflow.toml を使用して実行設定を作成します:
listen = "0.0.0.0:9529"
admin_listen = "127.0.0.1:9530"
upstream_url = "http://<DATAWAY_HOST>:9528"
admin_token_env = "EDGEFLOW_ADMIN_TOKEN"
[state]
mode = "memory_spill"
path = "/var/lib/edgeflow/edgeflow.state"
max_bytes = 10737418240
[workspaces.demo]
token_env = "EDGEFLOW_DEMO_TOKEN"
upstream_url は元の Dataway のプロトコルとポートを保持し、書き込み API のパスや ?token=... を付加せず、EdgeFlow 自身を指すこともできません。ワークスペース token は環境変数で個別に提供し、元の Dataway が受け入れる有効な token である必要があります。管理 token には自身で生成したランダム文字列を使用し、ワークスペース token とは別に設定してローカルルールの管理に使用します。
demo は EdgeFlow 内のワークスペース識別子であり、コマンド内の --workspace demo と一致する必要があります。ワークスペースを追加する場合は、そのワークスペースに [workspaces.<名称>]、独立した token_env、対応する環境変数を追加します。各 token は 1 つのワークスペースにのみ設定できます。各ワークスペースのルールは個別に適用する必要があります。同じワークスペースはすべてのノードで同じ識別子と token を使用します。
sudoedit /etc/edgeflow/edgeflow.env を使用して認証情報を保存します。値に特殊文字が含まれる場合は、systemd の環境ファイルのルールに従って正しく引用してください:
サービスの起動¶
/etc/systemd/system/edgeflow.service を作成します:
[Unit]
Description=EdgeFlow tail sampling
Wants=network-online.target
After=network-online.target
[Service]
User=edgeflow
Group=edgeflow
StateDirectory=edgeflow
WorkingDirectory=/var/lib/edgeflow
EnvironmentFile=/etc/edgeflow/edgeflow.env
ExecStart=/usr/local/bin/edgeflow --config /etc/edgeflow/edgeflow.toml run
Restart=on-failure
TimeoutStopSec=180
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now edgeflow
sudo systemctl status edgeflow --no-pager
sudo journalctl -u edgeflow -n 100 --no-pager
curl -fsS http://127.0.0.1:9529/healthz
サービスが正常であることを確認したら、ローカルルールの準備と適用に進みます。ヘルスチェックの成功はサンプリングが設定済みであることを意味しません。
Docker インストール¶
Docker ホスト上に独立したディレクトリを準備します:
edgeflow.toml と edgeflow.env を作成し、内容は実行設定と認証情報を参照し、state.path を /app/data/edgeflow.state に変更します。upstream_url はコンテナネットワークからアクセスできる必要があります。管理アドレスは 127.0.0.1:9530 のままにします。ルールファイルはカレントディレクトリの rules/ に保存します。Docker の環境ファイルは KEY=value 形式で記述し、値の外側に shell の引用符を付けません。
chmod 0644 edgeflow.toml
chmod 0600 edgeflow.env
chmod 0755 rules
docker volume create edgeflow-state
docker pull pubrepo.guance.com/guance/edgeflow:1.0.1
docker run -d --name edgeflow --restart unless-stopped --stop-timeout 180 \
--env-file ./edgeflow.env \
-p 9529:9529 \
-v "$PWD/edgeflow.toml:/app/edgeflow.toml:ro" \
-v "$PWD/rules:/app/local-rules:ro" \
-v edgeflow-state:/app/data \
pubrepo.guance.com/guance/edgeflow:1.0.1 run
docker logs --tail 100 edgeflow
curl -fsS http://127.0.0.1:9529/healthz
イメージは非 root ユーザーで実行されます。新規の名前付きボリュームはイメージ内のデータディレクトリで初期化されます。既存のボリュームを再利用する場合は、コンテナユーザーに読み書き権限があることを確認してください。公開するのはデータポート 9529 のみとし、ローカルルール CLI はコンテナ内で実行します。
ホストインストールと Docker インストールはどちらか一方を選択し、2 つのプロセスで同じポートや状態ディレクトリを競合させないでください。複数ノードのサンプリング専用モードでデプロイする場合、各ノードは独立したコンテナ、データボリューム、固定の到達可能アドレスを使用し、それぞれ同じ DSL ファイルを適用します。ローカルルールの準備と適用に進みます。
ローカルルールの準備と適用¶
edgeflow.toml は実行設定であり、以下の tracing.dsl が実際のサンプリングルールです。DSL ファイルを編集した後は必ず rules apply を実行する必要があります。ファイルを保存するだけでは実行中のルールは更新されません。
1 回の rules apply は指定したワークスペースの DSL ルール全体を置き換えるものであり、1 つのルールを追加するものではありません。 以下の例は、業務ルールをまだ設定していないワークスペースを対象としています。既存の集約、ルーティング、サンプリングルールがある場合は、まず現在の完全な DSL をバックアップし、保持する必要のあるルールを同じファイルにマージしてから、検証と適用を行ってください。本記事の例で直接上書きすることはできません。
ルール例¶
ホストでは /etc/edgeflow/rules/tracing.dsl に保存し、Docker インストールではインストールディレクトリ配下の rules/tracing.dsl に保存します:
version 1;
schema tracing {
field.trace_id: string;
field.resource: string;
field.duration: number;
tag.status: string;
tag.http_status_code: string;
}
tail "trace_sampling" on tracing {
group by field.trace_id;
idle 10s max_wait 1m decision_ttl 5m;
keep when any(tag.status == "error");
drop when any(field.resource in ["/health", "/healthz", "/ready", "/readyz", "/heartbeat"]);
drop when any(tag.http_status_code == "404");
sample 0.1 otherwise seed "edgeflow-tracing-v1";
}
ルールは順番に判定され、最初に一致したアクションが集約済みトレース全体の保持/破棄を決定します。そのため、エラートレースがハートビートや 404 に一致した場合でも優先的に保持されます。ハートビートや 404 を無条件で削除する必要がある場合は、対応する drop をエラー保持ルールの前に置きます。
any(...) は任意の Span が一致すればよいことを示し、「エントリ Span の一致」とは異なります。例では DataKit で一般的なフィールド位置を使用しています。本番適用前に実際のデータで tag. / field.、型、値を確認してください。resource は GET /health やルートテンプレートである可能性があるため、リストを調整する必要があります。HTTP ステータスコードが数値フィールドの場合は、schema と条件の両方を変更する必要があります。
任意の遅いトレース保持ルールは、エラー保持の後、破棄ルールの前に置きます:
ここでは duration を number として宣言し、DataKit 標準 tracing のマイクロ秒値で比較します。1000000 は 1 秒です。これはいずれかの Span が 1 秒を超えることを表し、トレース全体の先頭から末尾までの期間が 1 秒を超えることを表すものではありません。Pipeline が単位を書き換えている場合は、同じように調整する必要があります。
ホストでの検証と適用¶
まずオフラインで検証とプレビューを行います。デフォルトの組み込みサンプルは簡単な確認にのみ使用し、業務ルールは別途、実際のマスキング済みサンプルで検証してください:
sudo chmod 0644 /etc/edgeflow/rules/tracing.dsl
edgeflow rules validate /etc/edgeflow/rules/tracing.dsl
edgeflow rules test /etc/edgeflow/rules/tracing.dsl --workspace demo --format json
以下のコマンドは一時的な systemd ユニット経由で既存の認証情報ファイルを読み込み、EdgeFlow ホスト上でローカルにルールを適用するもので、token をコマンドラインに書き込むことを避けます。初回適用では --if-match 0 を使用します:
sudo systemd-run --quiet --wait --pipe --collect \
--property=EnvironmentFile=/etc/edgeflow/edgeflow.env \
/usr/local/bin/edgeflow --config /etc/edgeflow/edgeflow.toml \
rules apply /etc/edgeflow/rules/tracing.dsl --workspace demo --if-match 0 --format json
出力が ok: true であることを確認し、revision と hash を記録します。既存ルールの更新では引き続き 0 を使用しないでください。更新とロールバックを参照してください。
コンテナ内での検証と適用¶
DSL ファイルを Docker インストールディレクトリ配下の rules/tracing.dsl に保存します。このディレクトリはコンテナに読み取り専用でマウントされています。ホスト上のファイルを編集した後、コンテナ内で検証と適用を行います:
chmod 0644 rules/tracing.dsl
docker exec edgeflow edgeflow rules validate /app/local-rules/tracing.dsl
docker exec edgeflow edgeflow rules test /app/local-rules/tracing.dsl --workspace demo --format json
docker exec edgeflow edgeflow --config /app/edgeflow.toml \
rules apply /app/local-rules/tracing.dsl --workspace demo --if-match 0 --format json
コンテナには --env-file 経由で必要な認証情報が注入されています。初回適用後、更新時は現在の revision を使用するか、--if-match を省略します。複数ノードでは上記の手順をそれぞれ実行し、各インスタンスが同じファイルを適用して同じ hash を返すことを確認します。各インスタンスの revision は独立しており、数値が同じである必要はありません。
まず EdgeFlow ルールを適用し、その後で DataKit のデータ出口を切り替えます。DSL の元ファイルと履歴バージョンを保存し、コンテナのデータボリュームだけを唯一のバックアップにしないでください。
DataKit Aggregator の設定¶
詳細なパラメータについては DataKit Aggregator を参照してください。ここではデータ取り込みのみを設定し、EdgeFlow の実際の業務サンプリングポリシーは DataKit で管理しません。
接続設定の選択¶
ホストのデフォルト主設定は /usr/local/datakit/conf.d/datakit.conf です。既存の設定セクション内でフィールドを変更し、設定セクションを重複して追加したり、ファイル全体を上書きしたりしないでください。
サンプリング専用モードでは元の [dataway].urls を保持します:
[dataway]
urls = ["http://<DATAWAY_HOST>:9528?token=<WORKSPACE_TOKEN>"]
[aggregator]
endpoints = [
"http://edgeflow-a:9529?token=<WORKSPACE_TOKEN>",
"http://edgeflow-b:9529?token=<WORKSPACE_TOKEN>"
]
timeout = "30s"
max_raw_body_size = 1048576
use_local_config = true
local_config_dir = "/usr/local/datakit/conf.d/aggr"
local_metric_config_file = "aggr.toml"
local_tail_sampling_config_file = "tail-sampling.toml"
単一ノードでは endpoint を 1 つだけ保持します。ホスト名は実際に到達可能なアドレスに置き換えてください。Kubernetes 内の DataKit でも、Pod ネットワークからアクセスできる EdgeFlow のホストアドレスまたは DNS を使用する必要があります。endpoint には token 付きのサービスルートアドレスを使用し、API パスを付加しません。同じ DataKit の endpoint リストでは、各アドレスが同じワークスペース token を使用し、元の [dataway].urls のワークスペースと一致している必要があります。このリストで異なるワークスペースを混在させないでください。
フルプロキシモードでは同じ Aggregator パラメータを使用しますが、以下の 2 項目を変更します:
[dataway]
urls = ["http://<EDGEFLOW_HOST>:9529?token=<WORKSPACE_TOKEN>"]
[aggregator]
endpoints = []
この設定断片は差分のみを示しています。前の完全な例にある他の Aggregator フィールドは引き続き保持する必要があります。endpoint リストを空にすると通常の Dataway 出口が再利用され、このモードでは EdgeFlow アドレスを 1 つだけ設定します。
取り込み用ルールファイルの作成¶
ホスト上では /usr/local/datakit/conf.d/aggr/ を作成します。Kubernetes 環境では操作マシン上で以下の 2 ファイルを準備します。
aggr.toml は空の集約ルールセットを保持します:
既存の集約業務がある場合は元のファイルを直接上書きしないでください。集約タスクも Aggregator endpoint を使用するためです。
tail-sampling.toml は tracing のグループ送信を有効にします:
version = 1
[trace]
data_ttl = "1m"
group_key = "trace_id"
[[trace.sampling_pipeline]]
name = "send-traces-to-edgeflow"
type = "condition"
condition = '{ 1 = 1 }'
action = "keep"
ここでの keep は EdgeFlow がすべてのトレースを保持することを意味しません。実際の保持/破棄は適用済みの tracing.dsl によって決まります。この TOML の version、data_ttl は、EdgeFlow のルール revision や待機時間とは同じパラメータ体系ではありません。今回は tracing のみを扱う範囲を維持するため、[logging] や [rum] を追加しないでください。
Kubernetes での DataKit の設定¶
以下では、DataKit が datakit 名前空間にあり、DaemonSet 名が datakit であることを前提とします。まず既存の設定をバックアップしてください。デプロイツールや GitOps で管理している場合は、元の設定ソースを変更してリリースする必要があります。このセクションでは既存の DataKit のみを設定し、EdgeFlow はインストールしません。
ConfigMap を作成します:
kubectl -n datakit get daemonset datakit -o yaml > datakit-daemonset-backup.yaml
kubectl -n datakit create configmap edgeflow-tail-ingestion \
--from-file=aggr.toml=./aggr.toml \
--from-file=tail-sampling.toml=./tail-sampling.toml \
--dry-run=client -o yaml | kubectl apply -f -
接続アドレスの Secret を作成します。以下は 2 ノードのサンプリング専用モードの例です。datakit-edgeflow-endpoints.yaml として保存した後、kubectl apply -f datakit-edgeflow-endpoints.yaml を実行します:
apiVersion: v1
kind: Secret
metadata:
name: datakit-edgeflow-endpoints
namespace: datakit
type: Opaque
stringData:
endpoints: "http://<EDGEFLOW_A_HOST>:9529?token=<WORKSPACE_TOKEN>,http://<EDGEFLOW_B_HOST>:9529?token=<WORKSPACE_TOKEN>"
以下の断片を DataKit コンテナの既存の env、volumeMounts にマージし、元の ENV_DATAWAY を保持します。同じ名前の変数は 1 項目だけ残してください:
env:
- name: ENV_AGGREGATOR_ENDPOINTS
valueFrom:
secretKeyRef:
name: datakit-edgeflow-endpoints
key: endpoints
- name: ENV_AGGREGATOR_TIMEOUT
value: "30s"
- name: ENV_AGGREGATOR_MAX_RAW_BODY_SIZE
value: "1048576"
- name: ENV_AGGREGATOR_USE_LOCAL_CONFIG
value: "true"
- name: ENV_AGGREGATOR_LOCAL_CONFIG_DIR
value: "/usr/local/datakit/conf.d/aggr"
- name: ENV_AGGREGATOR_LOCAL_METRIC_CONFIG_FILE
value: "aggr.toml"
- name: ENV_AGGREGATOR_LOCAL_TAIL_SAMPLING_CONFIG_FILE
value: "tail-sampling.toml"
volumeMounts:
- name: edgeflow-tail-ingestion
mountPath: /usr/local/datakit/conf.d/aggr/aggr.toml
subPath: aggr.toml
readOnly: true
- name: edgeflow-tail-ingestion
mountPath: /usr/local/datakit/conf.d/aggr/tail-sampling.toml
subPath: tail-sampling.toml
readOnly: true
spec.template.spec.volumes にマージします:
フルプロキシモードでは、Secret 内のアドレスを単一の http://<EDGEFLOW_HOST>:9529?token=<WORKSPACE_TOKEN> に変更し、最初の環境変数名を ENV_DATAWAY に変更します。重複する ENV_DATAWAY と元の ENV_AGGREGATOR_ENDPOINTS を削除し、同時に主設定で aggregator.endpoints = [] であることを確認します。空の環境変数ではファイル内に既存の endpoint リストはクリアされません。
DataKit 設定の有効化¶
ホストでは次を実行します:
Kubernetes 環境では設定ソースを更新した後、次を実行します:
kubectl -n datakit rollout restart daemonset/datakit
kubectl -n datakit rollout status daemonset/datakit
DataKit のローカル取り込み設定を変更した後は DataKit を再起動します。subPath マウントも、新しいファイルを読み込むには Pod を再作成する必要があります。EdgeFlow のサンプリングポリシーのみを変更する場合は、EdgeFlow の各ノードで DSL を適用するだけでよく、そのために DataKit の設定を変更する必要はありません。
ルールパラメータとサンプリング基準¶
| パラメータ | 例 | 意味 |
|---|---|---|
version |
1 |
DSL 構文バージョンであり、変更のたびに増加するルールバージョンではありません |
group by |
field.trace_id |
完全なトレース単位でグループ化します。service を追加すると、サービスをまたぐトレースがグループ分割されます |
idle |
10s |
このグループが最後にデータを受信してからの無通信時間。0 より大きい必要があります |
max_wait |
1m |
このグループのデータを初めて受信してから集約する最大時間。idle より大きい必要があります |
decision_ttl |
5m |
決定の保持時間。0 より大きい必要があります。この期間中に遅れて到着した同じグループのデータは既存の決定を再利用します |
sample |
0.1 |
通常トレースのサンプリング比率。範囲は [0,1] です |
seed |
edgeflow-tracing-v1 |
安定した確率サンプリングのシード。同じポリシーで一貫している必要があります |
revision |
適用後に返される | 現在のインスタンスのルールリビジョン番号。更新時の同時実行チェックに使用します |
上記の時間は EdgeFlow がデータを受信した時刻に基づいて計算されます。idle または max_wait のいずれかの条件を満たせば集約を終了するため、すべてのトレースが 1 分間待機するわけではありません。Span の報告間隔とトレースの長さに応じて調整し、早期に終了しすぎないようにしてください。
decision_ttl は集約時間を延長しません。既に破棄決定がある場合、保持期間内に遅れて到着したエラー Span も破棄決定を引き継ぎます。保持期間の終了後、同じ trace の後続データは再グループ化され、異なる決定が下される可能性があります。
エラー保持が優先され、10% は前のルールに一致しなかった trace にのみ適用されます。10,000 件のトレースのうち、エラールールで 500 件を保持し、後続の破棄ルールで 1,500 件を削除し、残りの 8,000 件から約 800 件をサンプリングすると、合計の保持率は約 13% になります。異なる trace_id ごとに集計する必要があり、Span 数やバイト数で代用することはできません。
すべてのトレースを一律 10% でサンプリングする必要がある場合は、tail 内の 3 つの条件アクションを削除し、sample ... otherwise のみを残します。エラートレースもサンプリング対象になります。同カテゴリの 2 つ目の tail ルールを重ねないでください。
サンプリング結果の検証¶
まず一意で検索可能な trace ID を使用して確定的なルールを検証し、その後、多数の異なる trace で比率を検証します。
| シナリオ | 主な例での期待結果 |
|---|---|
| エラー Span を含む | 集約済みトレース全体を保持 |
| エラーなし、ハートビートパスに一致 | 破棄 |
| エラーなし、404 を含む | 破棄 |
| エラーと 404 の両方に一致 | エラールールが優先され、保持 |
| 多数の通常トレース | trace ごとに集計し、約 10% を保持 |
| 同じ trace が異なる DataKit から到来 | サンプリング専用モードの複数ノードでは同じインスタンスに集約 |
| 通常のログ、メトリクス | 選択したモードに応じて EdgeFlow 経由で転送、または元の Dataway へ直接送信 |
集約時間と実際の配信遅延を超えて待機した後、プラットフォームの結果を確認します。HTTP の成功やヘルスチェックはルールの受け入れ確認の代わりにはなりません。本番適用前に、遅延 Span、下流の中断と復旧も検証し、失敗時のフォールバックが保持比率を変えるかどうかを確認してください。
更新、ロールバック、運用¶
ローカルルールの更新とロールバック¶
- そのワークスペースの現在の完全な DSL ファイル、適用済みの
revision、hashを保存します。 - ローカルファイルを変更し、
validateとtestを実行します。 - 同じ
rules applyコマンドを使用し、初回の--if-match 0をそのインスタンスの現在の revision に置き換えます。このパラメータを省略し、CLI に現在のバージョンを読み取らせて同時更新をチェックさせることもできます。 - 正常に返されたことを確認し、各ノードで同じファイルを適用して
hashを確認した後、業務結果を検証します。
同じ内容を繰り返し適用しても revision は増加しません。バージョン競合時はまず既存のルールを確認し、他の人の変更を直接上書きしないでください。ロールバックでは保存した旧 DSL を再適用します。構文バージョンは引き続き version 1; のままです。
既存のグループは引き続き元のルールで処理を完了する可能性があるため、更新後は処理中データを観察する必要があります。DSL ファイルを変更するだけ、または DataKit を再起動するだけでは EdgeFlow ルールは更新されません。
実行設定または認証情報の変更¶
実行設定、認証情報、サンプリングルールでは反映方法が異なります:
| 変更内容 | 反映操作 |
|---|---|
| EdgeFlow DSL | 対応するワークスペースの各ノードで rules apply を実行します。DataKit の再起動は不要です |
ホスト上の edgeflow.toml または edgeflow.env |
保存後に sudo systemctl restart edgeflow を実行します。サービスユニットを変更した場合は、先に sudo systemctl daemon-reload を実行します |
Docker の edgeflow.toml または edgeflow.env |
元のインストールディレクトリで旧コンテナを停止して削除し、Docker インストールの docker run コマンドで再作成します。元のデータボリュームは保持して再利用します |
| DataKit の主設定またはローカル取り込みファイル | DataKit 設定の有効化に従ってサービスを再起動するか Pod を再作成します |
Docker の再作成では、先に docker stop edgeflow、docker rm edgeflow を実行できますが、edgeflow-state データボリュームは削除しないでください。docker restart のみでは変更後の --env-file は読み込まれません。再作成により、置き換えたマウント設定ファイルが確実に再読み込みされます。再起動後はサービスの状態とサンプリング結果を確認します。ワークスペースを追加する場合は、起動成功後に個別にルールを適用してから、そのワークスペースのデータを取り込みます。
元のデータ経路への復旧¶
フルプロキシモードでは元の [dataway].urls に戻します。サンプリング専用モードではカスタム Aggregator endpoints をクリアします。どちらのモードでも、今回有効にした tracing 取り込み設定を元に戻し、元の設定を復元して DataKit を再起動した後、通常の tracing 書き込みが復旧したことを確認する必要があります。use_local_config = false を設定するだけにしないでください。これは設定ソースを切り替えるものです。
EdgeFlow を停止する前に、ドレインのための時間を確保し、状態ディレクトリを保持してください。旧ノードが受信済みデータを引き続き送信する可能性があるため、重複と遅延を考慮する必要があります。
ストレージと障害の観察¶
memory_spill はメモリを優先して使用し、必要に応じてデータをディスクに一時保存します。正常停止時には状態を保存します。異常終了時には、受信済みでも未送信のデータが失われる可能性があり、永続データボリュームを使用してもこのリスクは排除できません。本記事のホストと Docker の例はいずれもこのモードを使用しています。異常終了後も受信済みデータを失わないことが業務上必要な場合は、永続化デプロイ方式を別途確認する必要があります。
state.max_bytes は論理状態の容量枠であり、実際のディスク使用量のハード上限ではありません。容量にはバックログ、トレース状態、スナップショット、インデックス、余裕を含める必要があります。例えば、元のボディが 2 MiB/s で 30 分間バックログした場合、約 3.52 GiB が必要になります。
以下の制限は edgeflow.toml の [limits] で調整でき、未設定の場合はデフォルト値が使用されます。表内の容量はバイト数であり、プロセス全体のメモリ上限として扱うことはできません:
| パラメータ | デフォルト値 | 制限到達時の影響 |
|---|---|---|
max_compressed_body |
16777216(16 MiB) |
上限を超えたリクエストは拒否されます |
max_decompressed_body |
67108864(64 MiB) |
解凍後に上限を超えたリクエストは拒否されます |
max_active_groups |
200000 |
グループ数の上限に達した場合、新しいグループのデータは直接保持して転送されます |
max_group_bytes |
8388608(8 MiB) |
単一トレースの累計データが上限を超えた場合、既存データと今回のデータを保持します。後続データは決定保持期間中に引き続き保持されます |
DataKit の max_raw_body_size = 1048576 は 1 回の送信パッケージのサイズを制御するもので、トレース全体の累計サイズを制限することはできません。10% のサンプリング率だけで容量を見積もらないでください。決定待ちのデータも依然として容量を占有し、上記の直接保持動作が発生すると保持比率も高くなります。
プロセスログ、ディスク、メモリ、/readyz、/metrics を通じて状態を観察します。edgeflow_engine_fail_open_total の reason="active_groups"、reason="group_bytes" は、容量不足による直接保持を観察するために使用できます。DataKit の aggr_tail_sampling_fallback_package_total、aggr_tail_sampling_fallback_point_total は、送信失敗後のフォールバック規模を観察するのに役立ちます。
サンプリング専用モードで通常出口にフォールバックすると、未サンプリングのデータが直接送信され、実際の保持量が増加する可能性があります。一部のリクエストが既に成功している場合は重複も発生し得ます。フルプロキシモードでは通常出口が引き続き EdgeFlow であるため、フォールバックによってそのノードの障害を回避することはできません。
よくある質問¶
| 現象 | 確認ポイント |
|---|---|
| ルール変更後も変化がない | ローカルの rules apply を実行したか、workspace が正しいか、各ノードが同じファイルを適用しているか、まだ旧グループを観察しているかを確認します |
| 適用に失敗する | DSL 構文、CLI プロセスが管理 token を読み込んでいるか、EdgeFlow が実行中か、--if-match が現在の revision かを確認します |
| ハートビートまたは 404 が依然として保持される | 先にエラーまたは遅いトレースの保持に一致していないか、フィールド位置、型、リソース名が例と一致しているかを確認します |
| サンプリング率が 10% でない | エラー優先保持、サンプル数、trace と Span の集計基準、失敗時のフォールバック、容量超過後の直接保持を確認します |
| トレースが不完全 | SDK のヘッドサンプリング、収集フィルタ、trace ID の伝播、ノード割り当て、遅延 Span を確認します |
| データ側の認証に失敗する | endpoint 内の token と EdgeFlow ワークスペース token が一致しているかを確認します |
| 413 または継続的な 5xx | パッケージサイズ制限、ネットワーク、ディスク容量、メモリ、下流の状態を確認します |
関連ドキュメント:データ集約とテールサンプリングの概要、DataKit Aggregator、Dataway テールサンプリング。