メタデータの運用と保守

警告

絶対に必要でない限り、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

1. bdb

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

   .jdbサフィックスはbdbjeのデータファイルです。これらのデータファイルはメタデータジャーナル数の増加に伴って増加します。Dorisが定期的にイメージを完了すると、古いログは削除されます。通常、これらのデータファイルの合計サイズは数MBから数GB（Dorisの使用方法、例えばインポート頻度によって異なる）まで変動します。データファイルの合計サイズが10GBより大きい場合、イメージが失敗したかイメージの配信に失敗した履歴ジャーナルが削除できないか疑う必要があるかもしれません。

   je.info.0はbdbjeの実行ログです。このログの時刻はUTC + 0タイムゾーンです。このログからbdbjeがどのように動作するかも確認できます。

2. 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. 初回起動

   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を注意深くお読みください。

2. 再起動

   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

      上記のログは必ずしもこの順序通りではありませんが、基本的には似ています。

3. 一般的な問題

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

FEの追加

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

1. 注意点

   • 新しいFEを追加する前に、現在のMaster FEが正常に動作していることを確認してください（接続は正常、JVMは正常、イメージ生成は正常、bdbjeデータディレクトリが大きすぎないなど）
   • 新しいFEを初回起動する時は、--helperパラメータを追加してMaster FEを指すようにする必要があります。再起動時に--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文を実行します。

2. 一般的な問題

   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プロセスを直接killできます。OBSERVERのメタデータディレクトリをクリアした後、プロセスを再度追加します。

      • FOLLOWERが追加される場合、FOLLOWERはメタデータの書き込みの多数に参加します。したがって、FOLLOWERがbdbje選挙チームに参加している可能性があります。2つのFOLLOWERノードのみ（MASTERを含む）がある場合、1つのFEを停止すると、大部分の時間書き込みができないため、もう1つのFEが終了する可能性があります。この時点で、まずALTER SYSTEM DROP FOLLOWERコマンドでメタデータから新しく追加されたFOLLOWERノードを削除し、次にFOLLOWERプロセスをkillし、メタデータを空にしてプロセスを再追加する必要があります。

FEの削除

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

• OBSERVERタイプのFEの場合、直接DROPで十分で、リスクはありません。

• FOLLOWERタイプのFE。まず、奇数個のFOLLOWER（3個以上）から削除を開始することを確認する必要があります。

  1. 非MASTERロールのFEを削除する場合、MASTER FEに接続し、DROPコマンドを実行してからプロセスをkillすることを推奨します。
  2. MASTER FEを削除する場合、まず奇数個のFOLLOWER FE`が存在し正常に動作していることを確認します。次に最初にMASTER FEプロセスをkillします。この時点で、FEがMASTERに選出されます。残りのFEが正常に動作していることを確認した後、新しいMASTER FEに接続してDROPコマンドを実行し、古いMASTER FEを削除します。

高度な操作

FEメタデータ復旧モード

メタデータ復旧モードの不適切な使用や間違った操作は、本番環境で不可逆的なデータ損傷を引き起こす可能性があります。そのため、メタデータ復旧モードを操作するためのドキュメントは提供されなくなりました。本当に必要な場合は、Dorisコミュニティの開発者にサポートをお問い合わせください。

FEタイプ変更

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

FE移行

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

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

   新しいFOLLOWER/OBSERVERを直接追加した後、古いFOLLOWER/OBSERVERを削除します。

2. 単一ノードMASTER移行

   開発者の場合、メタデータ復旧モードを使用して操作を実行できます。ただし、ユーザーの場合、メタデータ復旧モードの使用は推奨されません。環境を再構築し、外部テーブルを使用してデータを転送することを提案します。

3. 一組のFOLLOWERを一組のノードから別の一組の新しいノードに移行

   新しいノードにFEをデプロイし、FOLLOWERを追加することで新しいノードを最初に追加します。古いノードはDROPで1つずつドロップできます。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接続ポート

1. edit_log_port

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

2. http_port

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

3. rpc_port

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

4. query_port

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

5. arrow_flight_sql_port

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

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

FEのメタデータログはBDBJEにKey-Value形式で保存されます。一部の異常な状況では、メタデータエラーにより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つだけMASTERとしてデプロイし、その他のFEをOBSERVERとすることを強く推奨します。これにより、多くの複雑な運用保守問題を軽減できます。 MASTERシングルポイントでのメタデータ書き込み障害についてはあまり心配する必要はありません。まず、適切に設定されていれば、javaプロセスとしてのFEがハングアップすることは非常に困難です。次に、MASTERディスクが破損した場合（確率は非常に低い）でも、OBSERVERのメタデータを使用してmetadata recovery modeを通じて手動で復旧できます。

• FEプロセスのJVMは十分なメモリを確保する必要があります。FEのJVMメモリは最低10GB、32GBから64GBにすることを強く推奨します。そして、JVMメモリ使用量を監視するためのモニタリングをデプロイしてください。FEでOOMが発生すると、メタデータ書き込みが失敗し、復旧できない障害が発生する可能性があります！

• FEノードは、過剰なメタデータによるディスク容量不足を防ぐため、十分なディスク容量を確保する必要があります。同時に、FEログも十数ギガバイトのディスク容量を消費します。

その他の一般的な問題

1. 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を同時に再起動するだけで解決します。起動後も問題が解決されない場合は、未知の問題があるかどうかを確認する必要があります。

2. 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クラスターホストの時刻同期を確保することを推奨します。

3. 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がMASTERになり、その後のイメージ生成は新しい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が発生している場合は生成が失敗しており、具体的なエラーメッセージを確認する必要があります。

4. 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です。この数値を適切に減らしてイメージをより頻繁に作成し、古いジャーナルの削除を高速化できます。

5. FOLLOWER FEが次々とハングアップする

   Dorisのメタデータは多数書き込み戦略を採用しているため、メタデータジャーナルは成功とみなされる前に、少なくとも一定数のFOLLOWER FE（例：3つのFOLLOWERの場合、2つに正常に書き込む必要がある）に書き込まれる必要があります。書き込みが失敗した場合、FEプロセスは自発的に終了します。したがって、3つのFOLLOWER：A、B、Cがあると仮定します。Cが最初にハングアップし、次にBがハングアップすると、Aもハングアップします。そのため、ベストプラクティスセクションで説明したように、メタデータの運用保守における豊富な経験がない場合は、複数のFOLLOWERをデプロイすることは推奨されません。

6. fe.logでget exception when try to close previously opened bdb database. ignore itが表示される

   後にignore itという言葉がある場合、通常は対処する必要はありません。興味がある場合は、BDBEnvironment.javaでこのエラーを検索し、注釈を確認してください。

7. show frontends;から見ると、FEのJoinがtrueと表示されているが、実際にはFEが異常である

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

8. 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を正常に開始することのみを目的としており、失われたメタデータは復旧できません。