バージョン: 3.x

メタデータの運用と保守

警告

metadata_failure_recovery は絶対に必要な場合を除いて使用を避けてください。使用するとメタデータの切り捨て、消失、スプリットブレインを引き起こす可能性があります。不適切な操作による不可逆的なデータ損傷を防ぐため、慎重に使用してください。

このドキュメントでは、実際の本番環境において Doris メタデータを管理する方法に焦点を当てています。FE ノードの推奨デプロイメント、一般的に使用される運用方法、および一般的なエラー解決方法が含まれています。

まず、Doris メタデータ設計ドキュメントを読んで、Doris メタデータがどのように動作するかを理解してください。

重要なヒント

現在のメタデータ設計は後方互換性がありません。つまり、新しいバージョンで新しいメタデータ構造の変更がある場合（FE コードの FeMetaVersion.java ファイルに新しい VERSION があるかどうかで確認できます）、通常、新しいバージョンにアップグレードした後に旧バージョンにロールバックすることは不可能です。そのため、FE をアップグレードする前に、必ずアップグレードドキュメントの操作に従ってメタデータ互換性をテストしてください。

メタデータカタログ構造

fe.conf で指定された meta_dir のパスが path/to/doris-meta であると仮定します。通常の Doris クラスターでは、メタデータのディレクトリ構造は以下のようになります：

/path/to/doris-meta/
            |-- bdb/
            |   |-- 00000000.jdb
            |   |-- je.config.csv
            |   |-- je.info.0
            |   |-- je.info.0.lck
            |   |-- je.lck
            |   `-- je.stat.csv
            `-- image/
                |-- ROLE
                |-- VERSION
                `-- image.xxxx

bdb

メタデータジャーナルを保存する分散kVシステムとしてbdbjeを使用しています。このBDBディレクトリはbdbjeの「dataディレクトリ」に相当します。

.jdb拡張子はbdbjeのデータファイルです。これらのデータファイルはメタデータジャーナルの数の増加に伴って増加します。Dorisが定期的にイメージを完了すると、古いログが削除されます。そのため、通常、これらのデータファイルの合計サイズは数MBから数GB（インポート頻度などのDorisの使用方法に依存）まで変動します。データファイルの合計サイズが10GBを超える場合、イメージが失敗したか、イメージの配布に失敗した履歴ジャーナルが削除できないかどうかを確認する必要があります。

je.info.0はbdbjeの実行ログです。このログの時刻はUTC + 0タイムゾーンです。このログから、bdbjeの動作の一部も確認できます。
imageディレクトリ

imageディレクトリは、Dorisが定期的に生成するメタデータミラーを保存するために使用されます。通常、image.xxxxxミラーファイルが表示されます。ここでxxxxxは数字です。この数字は、イメージがxxxx以前のすべてのメタデータジャーナルを含んでいることを示します。また、このファイルの生成時刻（ls -alで表示）は通常、ミラーの生成時刻です。

image.ckptファイルが表示される場合もあります。これは生成中のメタデータミラーです。du -shコマンドでファイルサイズが増加していることが確認でき、ミラーコンテンツがファイルに書き込まれていることを示します。ミラーが書き込まれると、自動的に新しいimage.xxxxxに名前が変更され、古いイメージファイルを置き換えます。

Masterロールを持つFEのみが定期的にイメージファイルを積極的に生成します。各生成後、FEは他の非Masterロールにプッシュされます。他のすべてのFEがこのイメージを受信したことが確認されると、Master FEはbdbje内のメタデータジャーナルを削除します。そのため、イメージ生成が失敗したり、他のFEへのイメージプッシュが失敗したりすると、bdbje内のデータが蓄積されます。

ROLEファイルはFEのタイプ（FOLLOWERまたはOBSERVER）を記録するテキストファイルです。

VERSIONファイルはDorisクラスターのクラスターIDとノード間のアクセス認証に使用されるトークンを記録するテキストファイルです。

ROLEファイルとVERSIONファイルは同時に存在する場合もあれば、同時に存在しない場合もあります（初回起動時など）。

基本操作

単一ノードFEの起動

単一ノードFEは最も基本的なデプロイメントモードです。完全なDorisクラスターには少なくとも1つのFEノードが必要です。FEノードが1つだけの場合、ノードのタイプはFollowerで、ロールはMasterです。

初回起動
1. fe.confで指定されたmeta_dirのパスをpath/to/doris-metaとします。
2. path/to/doris-metaが既に存在し、権限が正しく、ディレクトリが空であることを確認します。
3. bash bin/start_fe.sh --daemonで直接起動します。
4. 起動後、fe.logで以下のログが確認できるはずです：
  - Palo FE starting...
  - image does not exist: /path/to/doris-meta/image/image.0
  - transfer from INIT to UNKNOWN
  - transfer from UNKNOWN to MASTER
  - the very first time to open bdb, dbname is 1
  - start fencing, epoch number is 1
  - finish replay in xxx msec
  - QE service start
  - thrift server started
  上記のログは必ずしもこの順序である必要はありませんが、基本的に類似しています。
5. 単一ノードFEの初回起動で通常問題は発生しません。上記のログが表示されない場合、一般的に文書の手順を注意深く従っていないため、関連するwikiを注意深く読んでください。
再起動
1. 停止したFEノードはbash bin/start_fe.shを使用して再起動できます。
2. 再起動後、fe.logで以下のログが確認できるはずです：
  - Palo FE starting...
  - finished to get cluster id: xxxx, role: FOLLOWER and node name: xxxx
  - 再起動前にイメージが生成されていない場合：
  - image does not exist: /path/to/doris-meta/image/image.0
  - 再起動前にイメージが生成されている場合：
  - start load image from /path/to/doris-meta/image/image.xxx. is ckpt: false
  - finished load image in xxx ms
  - transfer from INIT to UNKNOWN
  - replayed journal id is xxxx, replay to journal id is yyyy
  - transfer from UNKNOWN to MASTER
  - finish replay in xxx msec
  - master finish replay journal, can write now.
  - begin to generate new image: image.xxxx
  - start save image to /path/to/doris-meta/image/image.ckpt. is ckpt: true
  - finished save image /path/to/doris-meta/image/image.ckpt in xxx ms. checksum is xxxx
  - push image.xxx to other nodes. totally xx nodes, push succeeded xx nodes
  - QE service start
  - thrift server started
  上記のログは必ずしもこの順序である必要はありませんが、基本的に類似しています。
よくある問題

単一ノードFEのデプロイメントでは、起動停止で通常問題は発生しません。質問がある場合は、関連するWikiを参照し、操作手順を注意深く確認してください。

FEの追加

FEプロセスの追加については弾性拡張ドキュメントで詳しく説明されており、ここでは繰り返しません。注意点とよくある問題を以下に示します。

注意事項
- 新しいFEを追加する前に、現在のMaster FEが正常に動作していることを確認します（接続が正常、JVMが正常、イメージ生成が正常、bdbjeデータディレクトリが大きすぎないなど）
- 新しいFEを初めて起動する際は、必ずMaster FEを指す--helperパラメータを追加する必要があります。再起動時は--helperを追加する必要はありません。（--helperが指定されている場合、FEは直接helperノードにロールを問い合わせます。指定されていない場合、FEはdoris-meta/image/ディレクトリ内のROLEおよびVERSIONファイルから情報を取得しようとします。
- 新しいFEを初めて起動する際は、FEのmeta_dirが作成され、正しい権限を持ち、空であることを確認する必要があります。
- 新しいFEの起動とALTER SYSTEM ADD FOLLOWER/OBSERVER文の実行でFEをメタデータに追加する順序は不要です。新しいFEを最初に起動し、文を実行しない場合、新しいFEログにcurrent node is not added to the group. Please add it first.が表示されます。文が実行されると、通常のプロセスに入ります。
- 前のFEが正常に追加された後に、次のFEを追加することを確認してください。
- MASTER FEに接続し、ALTER SYSTEM ADD FOLLOWER/OBSERVER文を実行します。
よくある問題
1. this need is DETACHED
  
  追加するFEを初めて起動する際、Master FEのdoris-meta/bdb内のデータが大きい場合、追加するFEログにthis node is DETACHEDという文字が表示される場合があります。この時点で、bdbjeはデータをコピーしており、追加するFEのbdb/ディレクトリが増加していることが確認できます。このプロセスは通常数分かかります（bdbje内のデータ量に依存）。その後、fe.logにbdbje関連のエラースタック情報が表示される場合があります。最終的なログにQE service startとthrift server startが表示されれば、通常起動は成功しています。mysql-client経由でこのFEに接続を試すことができます。これらの文字が表示されない場合、bdbje複製ログタイムアウトの問題の可能性があります。この時点で、FEを直接再起動することで通常問題が解決されます。
2. さまざまな理由による追加の失敗
  - OBSERVERを追加する場合、OBSERVERタイプのFEはメタデータ書き込みの過半数に参加しないため、理論的に随時起動停止できます。そのため、OBSERVER追加失敗の場合、OBSERVERのFEプロセスを直接終了できます。OBSERVERのメタデータディレクトリをクリアした後、プロセスを再度追加します。
  - FOLLOWERを追加する場合、FOLLOWERは参加メタデータによって多く書き込まれるため、FOLLOWERがbdbje選挙チームに参加している可能性があります。FOLLOWERノードが2つだけ（MASTERを含む）の場合、1つのFEを停止すると、大部分の時間書き込みができないため、もう1つのFEが終了する可能性があります。この時点で、まずALTER SYSTEM DROP FOLLOWERコマンドでメタデータから新しく追加されたFOLLOWERノードを削除し、次にFOLLOWERプロセスを終了し、メタデータを空にしてプロセスを再追加する必要があります。

FEの削除

ALTER SYSTEM DROP FOLLOWER/OBSERVERコマンドで対応するタイプのFEを削除できます。以下の点に注意してください：

OBSERVERタイプのFEについては、直接DROPするだけで十分で、リスクはありません。
FOLLOWERタイプのFEについて。まず、奇数のFOLLOWER（3つ以上）から削除を開始することを確認する必要があります。
1. 非MASTERロールのFEを削除する場合、MASTER FEに接続してDROPコマンドを実行してから、プロセスを終了することをお勧めします。
2. MASTER FEを削除したい場合、まず奇数のFOLLOWER FE`があり、正常に動作していることを確認します。次に、まずMASTER FEプロセスを終了します。この時点で、1つのFEがMASTERに選出されます。残りのFEが正常に動作していることを確認した後、新しいMASTER FEに接続してDROPコマンドを実行し、古いMASTER FEを削除します。

高度な操作

FEメタデータ復旧モード

メタデータ復旧モードの不適切な使用や誤った操作は、本番環境で不可逆的なデータ損傷を引き起こす可能性があります。そのため、メタデータ復旧モードの操作に関するドキュメントは提供されなくなりました。真のニーズがある場合は、Dorisコミュニティの開発者に支援を求めてください。

FEタイプの変更

既存のFOLLOWER/OBSERVERタイプのFEをOBSERVER/FOLLOWERタイプに変更する必要がある場合は、上記で説明した方法でFEを削除してから、対応するタイプのFEを追加してください。

FE移行

1つのFEを現在のノードから別のノードに移行する必要がある場合、いくつかのシナリオがあります。

非MASTERノードのFOLLOWER、またはOBSERVER移行

新しいFOLLOWER / OBSERVERを直接追加した後、古いFOLLOWER / OBSERVERを削除します。
単一ノードMASTER移行

開発者の場合、メタデータ復旧モードを使用して操作を実行できます。ただし、ユーザーの場合、メタデータ復旧モードの使用はお勧めしません。環境を再構築し、外部テーブルを使用してデータを転送することをお勧めします。
一組のFOLLOWERを1組のノードから別の組の新しいノードに移行

新しいノードにFEをデプロイし、FOLLOWERを追加することで新しいノードを最初に追加します。古いノードはDROPで1つずつ削除できます。DROP-by-DROPのプロセスで、MASTERは自動的に新しいFOLLOWERノードを選択します。

FEポートの置換

FEには現在以下のポートがあります

Ed_log_port: bdbjeの通信ポート
http_port: httpポート、イメージのプッシュにも使用
rpc_port: Frontendのthrift serverポート
query_port: Mysql接続ポート
arrow_flight_sql_port: Arrow Flight SQL接続ポート

edit_log_port

このポートを置換する必要がある場合、複数のfeノードがデプロイされている場合は、ノード管理ステップで古いノードを削除し、新しいノードを追加できます。単一ノードの場合、上記の「単一ノードMASTER移行」を参照して単一のMaster feノードを移行できます
http_port

すべてのFE http_portは一致している必要があります。そのため、このポートを変更したい場合、すべてのFEを停止し、変更してから同時に再起動する必要があります。
rpc_port

設定を変更した後、FEを直接再起動します。Master FEはハートビートを通じてBEに新しいポートを通知します。Master FEのこのポートのみが使用されます。ただし、すべてのFEポートを一致させることをお勧めします。
query_port

設定を変更した後、FEを直接再起動します。これはmysqlの接続先にのみ影響します。
arrow_flight_sql_port

設定を変更した後、FEを直接再起動します。これはarrow flight sql server接続先にのみ影響します。

BDBJEのデータ表示（デバッグ時のみ使用）

FEのメタデータログはKey-Valueの形でBDBJEに保存されています。一部の異常な状況では、メタデータエラーによりFEが起動できない場合があります。この場合、DorisはユーザーがBDBJEに保存されているデータをクエリしてトラブルシューティングを促進する方法を提供します。

まず、fe.confに設定を追加する必要があります：enable_bdbje_debug_mode=true、次にbash start_fe.sh --daemonでFEを起動します。

この時、FEはデバッグモードに入り、httpサーバーとMySQLサーバーのみを起動し、BDBJEインスタンスを開きますが、メタデータやその他の後続の起動プロセスは読み込みません。

この時、FEのWebページにアクセスするか、MySQLクライアント経由でDorisに接続した後、show proc "/bdbje";を通じてBDBJEに保存されているデータを表示できます。

mysql> show proc "/bdbje";
+----------+---------------+---------+
| DbNames  | JournalNumber | Comment |
+----------+---------------+---------+
| 110589   | 4273          |         |
| epochDB  | 4             |         |
| metricDB | 430694        |         |
+----------+---------------+---------+

第1レベルディレクトリには、BDBJEのすべてのデータベース名と各データベースのエントリ数が表示されます。

mysql> show proc "/bdbje/110589";
+-----------+
| JournalId |
+-----------+
| 1         |
| 2         |

...
| 114858    |
| 114859    |
| 114860    |
| 114861    |
+-----------+
4273 rows in set (0.06 sec)

第2レベルに入ると、指定されたデータベース下のすべてのエントリキーが一覧表示されます。

mysql> show proc "/bdbje/110589/114861";
+-----------+--------------+---------------------------------------------+
| JournalId | OpType       | Data                                        |
+-----------+--------------+---------------------------------------------+
| 114861    | OP_HEARTBEAT | org.apache.doris.persist.HbPackage@6583d5fb |
+-----------+--------------+---------------------------------------------+
1 row in set (0.05 sec)

第3レベルでは、指定されたキーの値情報を表示できます。

ベストプラクティス

FEのデプロイメント推奨事項は、インストールとデプロイメントのドキュメントに記載されています。ここではいくつかの補足を説明します。

FEメタデータの動作ロジックをよく理解していない場合、またはFEメタデータの運用保守における十分な経験がない場合、実際にはFOLLOWERタイプのFEを1つのみMATERとしてデプロイし、他のFEはOBSERVERとすることを強く推奨します。これにより多くの複雑な運用保守問題を軽減できます。 MATERの単一障害点によるメタデータ書き込み障害をそれほど心配する必要はありません。まず、適切に設定されていれば、javaプロセスとしてのFEがハングアップすることは非常に困難です。次に、MATERのディスクが損傷した場合（確率は非常に低い）、metadata recovery modeを通じてOBSERVER上のメタデータを使用して手動で復旧することも可能です。
FEプロセスのJVMは十分なメモリを確保する必要があります。FEのJVMメモリは最低10GB、32GBから64GBにすることを強く推奨します。また、JVMメモリ使用量を監視するモニタリングをデプロイしてください。FEでOOMが発生すると、メタデータ書き込みが失敗し、回復不可能な障害が発生する可能性があります！
FEノードは、過剰なメタデータによるディスク容量不足を防ぐため、十分なディスク容量を確保する必要があります。同時に、FEログも十数ギガバイトのディスク容量を消費します。

その他のよくある問題

fe.logにmeta out of date. current time: xxx, synchronized time: xxx, has log: xxx, fe type: xxxが出力される

これは通常、FEがMasterを選出できないことが原因です。例えば、3つのFOLLOWERが設定されているが、1つのFOLLOWERのみが起動されている場合、このFOLLOWERでこの問題が発生します。通常は、すべてのFOLLOWERを同時に再起動するだけで解決します。起動後も問題が解決しない場合は、未知の問題があるかどうかを確認する必要があります。
Clock delta: xxxx ms. between Feeder: xxxx and this Replica exceeds max permissible delta: xxxx ms.

Bdbjeでは、ノード間の時刻誤差が一定の閾値を超えてはならないことが要求されます。超過した場合、ノードは異常終了します。デフォルトの閾値は5000msで、FEパラメータmax_bdbje_clock_delta_msによって制御され、適切に修正できます。ただし、NTPなどの時刻同期方法を使用してDorisクラスタホストの時刻同期を確保することを推奨します。
image/ディレクトリ内のミラーファイルが長期間更新されない

Master FEはデフォルトで50,000のメタデータジャーナルごとにミラーファイルを生成します。頻繁に使用されるクラスタでは、通常半日から数日ごとに新しいイメージファイルが生成されます。イメージファイルが長期間（例：1週間以上）更新されていない場合は、以下の理由を順番に確認できます：
1. Master FEのfe.logでmemory is not enough to do checkpoint. Committed memory XXXX Bytes, used memory XXXX Bytes. を検索してください。見つかった場合は、現在のFEのJVMメモリがイメージ生成に不十分であることを示しています（通常、イメージ生成にはFEメモリの半分を予約する必要があります）。JVMメモリを追加してFEを再起動した後に観察する必要があります。Master FEを再起動するたびに、新しいイメージが直接生成されます。この再起動方法は、新しいイメージを能動的に生成するためにも使用できます。複数のFOLLOWERデプロイメントがある場合、現在のMaster FEを再起動すると、別のFOLLOWER FEがMATERになり、その後のイメージ生成は新しいMasterの責任となることに注意してください。そのため、すべてのFOLLOWER FEのJVMメモリ設定を変更する必要がある場合があります。
2. Master FEのfe.logでbegin to generate new image: image.xxxxを検索してください。見つかった場合は、イメージが生成されています。このスレッドの後続ログを確認し、checkpoint finished save image.xxxxが表示されれば、イメージの書き込みが成功しています。Exception when generating new image fileが発生した場合は、生成が失敗しており、具体的なエラーメッセージを確認する必要があります。
bdb/ディレクトリのサイズが非常に大きく、数GB以上に達する

BDBディレクトリは、新しいイメージを生成できないエラーを解消した後も、しばらくの間大きいままです。Master FEのイメージプッシュが失敗したことが原因の可能性があります。Master FEのfe.logでpush image.XXXX to other nodes. totally XX nodes, push succeeded YY nodesを検索できます。YYがXXより小さい場合、一部のFEへのプッシュが成功していません。fe.logで具体的なエラーException when pushing image file.url = xxxを確認できます。

同時に、FE設定ファイルに設定を追加できます：edit_log_roll_num = xxxx。このパラメータはメタデータジャーナルの数を設定し、一度イメージを作成します。デフォルトは50000です。この数値を適切に減らしてイメージをより頻繁に作成し、古いジャーナルの削除を高速化できます。
FOLLOWER FEが次々とハングアップする

Dorisのメタデータは多数決書き込み戦略を採用しているため、メタデータジャーナルは成功と見なされるまでに、少なくとも一定数のFOLLOWER FE（例：3つのFOLLOWERの場合、2つが正常に書き込まれる必要がある）に書き込まれる必要があります。書き込みが失敗した場合、FEプロセスは自発的に終了します。そのため、A、B、CのFOLLOWERが3つあるとします。Cが最初にハングアップし、次にBがハングアップすると、Aもハングアップします。そのため、Best Practicesセクションで説明したように、メタデータの運用保守に豊富な経験がない場合は、複数のFOLLOWERをデプロイすることは推奨されません。
fe.logにget exception when try to close previously opened bdb database. ignore itが出現する

後ろにignore itという語がある場合は、通常対処する必要はありません。興味がある場合は、BDBEnvironment.javaでこのエラーを検索し、注釈を確認してください。
show frontends;で見ると、FEのJoinがtrueとして表示されているが、実際にはFEが異常である

show frontends;でJoin情報を確認してください。この列がtrueの場合は、FEがクラスタに参加したことのみを意味します。クラスタ内に正常に存在していることを意味するものではありません。falseの場合は、FEがクラスタに参加したことがないことを意味します。
FEのmaster_sync_policy、replica_sync_policy、txn_rollback_limitの設定

master_sync_policyは、Leader FEがメタデータログを書き込む際にfsync()を呼び出すかどうかを指定するために使用され、replica_sync_policyは、FE HAデプロイメント同期メタデータ時に他のFollower FEがfsync()を呼び出すかどうかを指定するために使用されます。Dorisの初期バージョンでは、これらの2つのパラメータはデフォルトでWRITE_NO_SYNC、つまりfsync()を呼び出しませんでした。Dorisの最新バージョンでは、デフォルトがSYNCに変更され、つまりfsync()を呼び出します。fsync()の呼び出しは、メタデータディスク書き込みの効率を大幅に低下させます。一部の環境では、IOPSが数百まで低下し、レイテンシが2-3ms増加する可能性があります（ただし、Dorisメタデータ操作には十分です）。そのため、以下の設定を推奨します：
1. 単一Follower FEデプロイメントの場合、master_sync_policyをSYNCに設定し、FEシステムのダウンタイムによるメタデータの損失を防ぎます。
2. 複数Follower FEデプロイメントの場合、master_sync_policyとreplica_sync_policyをWRITE_NO_SYNCに設定できます。複数システムの同時停止の確率は非常に低いと考えられるためです。
単一Follower FEデプロイメントでmaster_sync_policyがWRITE_NO_SYNCに設定されている場合、FEシステム停止が発生し、メタデータの損失が生じる可能性があります。この時点で、他のObserver FEが再起動を試行すると、エラーが報告される可能性があります：
```
Node xxx must rollback xx total commits(numPassedDurableCommits of which were durable) to the earliest point indicated by transaction xxxx in order to rejoin the replication group, but the transaction rollback limit of xxx prohibits this.
```

これは、永続化されたいくつかのトランザクションをロールバックする必要があるが、エントリ数が上限を超えていることを意味します。ここでのデフォルトの上限は100で、txn_rollback_limitを設定することで変更できます。この操作はFEを正常に起動しようとする場合にのみ使用されますが、失われたメタデータは回復できません。

重要なヒント​

メタデータカタログ構造​

基本操作​

単一ノードFEの起動​

FEの追加​

FEの削除​

高度な操作​

FEメタデータ復旧モード​

FEタイプの変更​

FE移行​

FEポートの置換​

BDBJEのデータ表示（デバッグ時のみ使用）​

ベストプラクティス​

その他のよくある問題​