Graceful Exit
v3.3 以降、StarRocks は Graceful Exit をサポートしています。
概要
Graceful Exit は、StarRocks FE、BE、CN ノードの非破壊的なアップグレードと再起動をサポートするために設計されたメカニズムです。その主な目的は、ノードの再起動、ローリングアップグレード、またはクラスターのスケーリングなどのメンテナンス操作中に、実行中のクエリやデータ取り込みタスクへの影響を最小限に抑えることです。
Graceful Exit は以下を保証します：
- ノードは、終了が始まると新しいタスクの受け入れを停止します。
- 既存のクエリとロードジョブは、制御された時間枠内で完了することが許可されます。
- システムコンポーネント（FE/BE/CN）は、クラスターが正しくトラフィックを再ルーティングするように状態変更を調整します。
Graceful Exit のメカニズムは、FE と BE/CN ノードで異なります。以下に説明します。
FE Graceful Exit メカニズム
トリガーシグナル
FE Graceful Exit は以下で開始されます：
stop_fe.sh -g
これは SIGUSR1 シグナルを送信し、デフォルトの終了（-g オプションなし）は SIGTERM シグナルを送信します。
ロードバランサーの認識
シグナルを受信すると：
- FE は
/api/healthエンドポイントでHTTP 500 を即座に返します。 - ロードバランサーは約15秒以内に劣化状態を検出し、この FE への新しい接続のルーティングを停止します。
接続ドレインとSHUTDOWNロジック
Follower FE
- 読み取り専用クエリを処理します。
- FE ノードにアクティブなセッションがない場合、接続は即座に閉じられます。
- SQL が実行中の場合、FE ノードは実行が終了するのを待ってからセッションを閉じます。
Leader FE
-
読み取りリクエストの処理は、Follower と同じです。
-
書き込みリクエストの処理には以下が必要です：
- BDBJE のクローズ。
- 新しいリーダー選出の完了を許可。
- 後続の書き込みを新しく選出されたリーダーにリダイレクト。
タイムアウト制御
クエリが長時間実行される場合、FE は60秒（--timeout オプションで設定可能）後に強制終了します。
BE/CN Graceful Exit メカニズム
トリガーシグナル
BE Graceful Exit は以下で開始されます：
stop_be.sh -g
CN Graceful Exit は以下で開始されます：
stop_cn.sh -g
これは SIGTERM シグナルを送信し、デフォルトの終了（-g オプションなし）は SIGKILL シグナルを送信します。
状態遷移
シグナルを受信すると：
- BE/CN ノードは自分自身をEXITINGとマークします。
- 新しいクエリフラグメントを拒否し、
INTERNAL_ERRORを返します。 - 既存のフラグメントの処理を続行します。
フライト中のクエリの待機ループ
BE/CN が既存のフラグメントの終了を待つ動作は、BE/CN の設定 loop_count_wait_fragments_finish によって制御されます（デフォルト：2）。実際の待機時間は loop_count_wait_fragments_finish × 10 秒（デフォルトでは 20 秒）です。タイムアウト後もフラグメントが残っている場合、BE/CN は通常のSHUTDOWNを続行します（スレッド、ネットワーク、その他のプロセスを閉じる）。
改善された FE 認識
v3.4 以降、FE はハートビートの失敗に基づいて BE/CN を DEAD とマークしなくなりました。BE/CN の「EXITING」状態を正しく認識し、フラグメントが完了するための大幅に長いグレースフルエグジットウィンドウを許可します。
設定
FE 設定
stop_fe.sh -g --timeout
- 説明：FE が強制終了されるまでの最大待機時間。
- デフォルト：60（秒）
- 適用方法：スクリプトコマンドで指定します。例：
--timeout 120。
最小 LB 検出時間
- 説明：LB は劣化した健康状態を検出するのに少なくとも 15 秒を必要とします。
- デフォルト：15（秒）
- 適用方法：固定値
BE/CN 設定
loop_count_wait_fragments_finish
- 説明：BE/CN が既存のフラグメントを待機する期間。値に 10 秒を掛けます。
- デフォルト：2
- 適用方法：BE/CN 設定ファイルで変更するか、動的に更新します。
graceful_exit_wait_for_frontend_heartbeat
- 説明：BE/CN がハートビートを介して FE がSHUTDOWNを確認するのを待つかどうか。v3.4.5 以降。
- デフォルト：false
- 適用方法：BE/CN 設定ファイルで変更するか、動的に更新します。
stop_be.sh -g --timeout, stop_cn.sh -g --timeout
- 説明：BE/CN が強制終了されるまでの最大待機時間。BE/CN の待機期間に達する前に終了しないように、
loop_count_wait_fragments_finish* 10 より大きい値に設定します。 - デフォルト：false
- 適用方法：スクリプトコマンドで指定します。例：
--timeout 30。
グローバルスイッチ
Graceful Exit は v3.4 以降、デフォルトで有効です。一時的に無効にするには、BE/CN 設定 loop_count_wait_fragments_finish を 0 に設定します。
Graceful Exit 中の期待される動作
クエリワークロード
| クエリタイプ | 期待される動作 |
|---|---|
| 短い（20 秒未満） | BE/CN は十分に待機し、クエリは正常に完了します。 |
| 中程度（20 ～ 60 秒） | BE/CN の待機ウィンドウ内で完了したクエリは成功として返されます。それ以外の場合、クエリはキャンセルされ、手動で再試行が必要です。 |
| 長い（60 秒以上） | クエリは FE/BE/CN によってタイムアウトで終了される可能性が高く、手動で再試行が必要です。 |
データ取り込みタスク
- Flink または Kafka コネクタを介したロードタスクは、ユーザーに見える中断なしに自動的に再試行されます。
- Stream Load（非フレームワーク）、Broker Load、および Routine Load タスクは、接続が切断されると失敗する可能性があります。手動での再試行が必要です。
- バックグラウンドタスクは、FE の再試行メカニズムによって自動的に再スケジュールされ、実行さ れます。
アップグレードと再起動操作
Graceful Exit は以下を保証します：
- クラスター全体のダウンタイムなし;
- ノードを一度に一つずつ排出することで安全なローリングアップグレード。
制限とバージョンの違い
バージョンの動作の違い
| バージョン | 動作 |
|---|---|
| v3.3 | BE Graceful Exit に欠陥あり：FE は BE/CN を DEAD と誤ってマークし、クエリがキャンセルされる可能性があります。効果的な待機は制限されています（デフォルトで 15 秒）。 |
| v3.4+ | 拡張された待機期間を完全にサポートし、FE は BE/CN の「EXITING」状態を正しく識別します。プロダクションに推奨されます。 |
操作上の制限
- 極端な場合（たとえば、BE/CN がハングする場合）、Graceful Exit が失敗する可能性があります。プロセスを終了するには
kill -9が必要であり、部分的なデータの永続性のリスクがあります（スナップショットで回復可能）。
使用方法
前提条件
StarRocks バージョン：
- v3.3+：基本的な Graceful Exit サポート。
- v3.4+：強化されたステータス管理、長い待機ウィンドウ（数分まで）。
設定：
loop_count_wait_fragments_finishを正の整数に設定してください。graceful_exit_wait_for_frontend_heartbeatをtrueに設定し、FE が BE の「EXITING」状態を検出できるようにします。
FE Graceful Exit の実行
./bin/stop_fe.sh -g --timeout 60
パラメータ：
--timeout: FE ノードが強制終了されるまでの最大待機時間。
動作：
- システムは最初に
SIGUSR1シグナルを送信します。 - タイムアウト後、
SIGKILLにフォールバックします。
FE 状態の検証
以下の API を使用して FE の健康状態を確認できます：
http://<fe_host>:8030/api/health
LB は連続して非 200 応答を受信した後にノードを削除します。
BE/CN Graceful Exit の実行
-
v3.3 の場合：
- BE:
./be/bin/stop_be.sh -g- CN:
./be/bin/stop_cn.sh -g -
v3.4+ の場合：
- BE:
./bin/stop_be.sh -g --timeout 600- CN:
./bin/stop_cn.sh -g --timeout 600
BE/CN はフラグメントが残っていない場合、即座に終了します。
BE/CN 状態の検証
FE 上で実行：
SHOW BACKENDS;
StatusCode:
SHUTDOWN: BE/CN Graceful Exit が進行中。DISCONNECTED: BE/CN ノードが完全に終了しました。
ローリングアップグレードワークフロー
手順
- ノード
Aで Graceful Exit を実行します。 - ノード
Aが FE 側でDISCONNECTEDと表示されていることを確認します。 - ノード
Aをアップグレードして再起動します。 - 残りのノードについて上記を繰り返します。
Graceful Exit の監視
FE ログ fe.log、BE ログ be.log、または CN ログ cn.log を確認し、EXITINGにタスクがあったかどうかを確認します。
トラブルシューティング
BE/CN がタイムアウトで終了する
タスクが Graceful Exit 期間内に完了しない場合、BE/CN は強制終了（SIGKILL）をトリガーします。これが過度に長いタスクの期間や不適切な設定（たとえば、--timeout 値が小さすぎる）によるものかどうかを確認してください。
ノードの状態が SHUTDOWN でない
ノードの状態が SHUTDOWN でない場合、loop_count_wait_fragments_finish が正の整数に設定されているか、BE/CN が終了前にハートビートを報告したかどうかを確認してください（そうでない場合、graceful_exit_wait_for_frontend_heartbeat を true に設定します）。
