Jira のインデックス作成の仕組み

Jira は、ダッシュボード、課題検索、レポート、およびボードに、Lucene と呼ばれる、Apache によって作成されたサードパーティのライブラリを使用します。

1. Lucene の基本的なコンセプトは次のとおりです。
   
   • Document
     • Document とは、検索およびインデックスの単位です。1 つのインデックスには 1 つ以上の Document が含まれます。
     • インデックス作成には IndexWriter への Document の追加が、検索には IndexSearcher 経由の Document の取得が含まれます。 
     • Lucene の Document は、いわゆるドキュメントである必要はありません。たとえば、ユーザーのデータベース テーブルについて Lucene インデックスを作成している場合、各ユーザーがインデックス内で Lucene Document として表されます。
   • Field

     • 1 つの Document には 1 つ以上の Field が含まれます。Field は単純に名前と値のペアです。たとえば、アプリケーションによくある Field に、title があります。title Field の場合、フィールド名が title で、値は対象のコンテンツ アイテムのタイトルです。

     • このため、Lucene でのインデックス作成には、1 つ以上の Field を含む Document の作成と、それらの Document を 1 つの IndexWriter に追加する作業が含まれます。
   • 検索
     • 検索を行うには、インデックスがすでに構築されている必要があります。Lucene で素早い検索レスポンスを得られるのは、テキストを直接検索するのではなくインデックスを検索しているためです。
     • このタイプのインデックスは逆インデックスと呼ばれます。これは、ページ中心のデータ構造 (ページ -> 単語) をキーワード中心のデータ構造 (単語 -> ページ) に反転させるためです。
       
     • これには、クエリの作成 (通常は QueryParser 経由) と、対象のクエリを IndexSearcher に渡し、ヒットの一覧を受け取ることが含まれます。
   • クエリ
     • Lucene は検索を実行するための独自の小規模な言語を保持しています。Lucene Query Syntax の詳細をご確認ください。
     • Lucene クエリ言語により、ユーザーは、検索対象のフィールド、重み付けすべきフィールド (ブースト)、ブール値クエリの実行 (AND、OR、NOT)、およびその他の機能を利用できます。
2. Jira はインデックス作成に Lucene を使用します。より具体的には、次のようになります。
   
   • Jira で課題が作成または変更されると、対象の課題のフィールドと、検索に便利ないくつかの計算済みの追加データを含む Lucene Document が作成されます。Jira が課題をインデックスすると、課題と関連する Lucene Document プラグインに渡されます。プラグインは、追加した任意のフィールドの名前を返す前に、Lucene Document を任意の方法で変更できます。その後、Lucene Document が Lucene インデックスに追加され、インデックス内の対象の課題についての既存の任意の Document が置き換えられます。 
   • 課題のコメント、作業ログ、変更履歴エントリ用に、追加の Lucene Document が作成されます。
   • 課題への変更内容に応じ、課題コメント、作業ログ、変更履歴 Document の一部またはすべてが既存の Document を置き換えるように再生成される場合があります。
3. Lucene インデックスが破損した場合、あるいはインデックス済みのデータを更新する必要があるような構成変更が行われた場合は、Lucene インデックスを再生成する必要があることがあります。再インデックスを必要とする構成変更のもっともシンプルな例として、計算が行われるカスタム フィールドが追加され、検索で使用できるようにその計算の結果をインデックスしたい場合があります。プロジェクトでのカスタム フィールドの表示/非表示でも Jira の再インデックスが必要となります (少なくとも影響を受けるプロジェクトでは必要ですが、Jira では再インデックスが必要なプロジェクトを特定することはせず、単純にすべてを再インデックスすることを促します)。
4. 構成変更によってコメント、作業ログ、および変更履歴の再インデックスが必要になることはないため、バックグラウンドでの再インデックスではこれらのエントリの再インデックスは行われません (更新された課題の正確性を確保するためであったり、再インデックスが行われたりしているときに、一部の課題でこれらが再インデックスされる可能性はあります)。
5. データベースは Jira の基準となる信頼源であり、インデックス処理ではインデックスを構築するために SQL を使用してデータベースを読み取ります。カスタム フィールド (特にプラグインによって提供されるもの) は、ほかの方法でデータを取得し、それをインデックスに含める場合があります。リモート システムからのデータの取得は、インデックス作成のパフォーマンスに致命的な影響を与える可能性がある点にご注意ください。

Lucene での RAM の使用

1. Jira は一度に 1 つの課題を処理し、Lucene Document の構築中に使用するメモリ量は最小限に留めます。
2. Lucene はインデックスをディスクにファイル セグメントとして保存し、これは 1-2 GB のサイズになる可能性があります。Document の追加や削除に応じ、これらのセグメントのマージや再構造が行われます。これは通常、大量のメモリを使用します。
3. 検索中にも大量のメモリが使用される場合があります (特に大規模な検索セットの並べ替えを行うとき)。ただし、Jira 5.x と Jira 6.x の時間枠では、これらの領域のメモリ要件が多くの検索シナリオについて大幅に削減されました。
4. 素早い検索のため、Lucene は特定のデータ構造を RAM に完全に読み込みます。
   • Field キャッシュはフィールドでの並べ替えを行うときに水面下で使用されますが、フィールド タイプに応じ、RAM を Document 単位である程度消費します (消費量が圧倒的に多いのは String です)。これは対象のフィールドでの並べ替えを初めて行ったときに読み込まれます。
     
   • Norm は、インデックス時に計算された先験的な Lucene Document ブーストをエンコードし、長さの標準化とアプリケーションが行う任意のブーストを含み、検索に使用されるフィールド X の Lucene Document あたり 1 バイトを消費します。たとえば、ご利用のアプリケーションが 3 つのフィールドを検索する場合 (例: 本文、タイトル、概要)、Lucene Document あたり 3 バイトの RAM が必要となります。これらは対象のフィールドが初めて検索されるときにオンデマンドで読み込まれます。
     
   • 削除が行われる場合、Lucene Document あたり 1 ビットが消費されます。これは IndexReader の構築中に作成されています。

インデックスの大きさの判断基準

JIRA_HOME ディレクトリに移動して次のコマンドを実行します (Linux)。 

du -h caches/

これによって次のようなものが返されます。

8.0K caches/indexesV2/plugins
244K caches/indexesV2/changes
124K caches/indexesV2/comments
416K caches/indexesV2/issues
8.0K caches/indexesV2/worklogs
56K caches/indexesV2/entities/searchrequest
56K caches/indexesV2/entities/portalpage
116K caches/indexesV2/entities
920K caches/indexesV2
4.0K caches/tmp_attachments
928K caches

この場合、インデックスは 928k です。 

リソースをもっとも多く消費しているプロセスの特定方法

1. 一般に、インデックスを作成するための Lucene Document の構築が最大のリソースを必要とし、課題のインデックスやデータベースからのデータの読み取りがこの多くを占めます。これは、インストールされているプラグインや、それらがインデックス データを保管する方法の影響を強く受けます。
2. インデックス作成のプロセスは、3 つのリソース領域で多くのリソースを要求します。
   
   • CPU とメモリ
   • データベース
   • Lucene ファイルを保持しているファイル システム
3. 上の領域のどれもがボトルネックになる可能性があります。例として、長い ping 応答、データベースからの低速なレスポンス、低速なファイル システム (NAS の使用) などが挙げられます。インデックス作成のパフォーマンスが懸念事項である場合、これらすべてを確認する必要があります。
4. バックグラウンドの再インデックスでは 1 つのスレッドのみを使用しており、理論的には、Jira の残りの部分に大きな影響を与えることなくバックグラウンドで並行して実行されます。しかし、大きな影響を与える可能性があることもあります。大規模なシステムに高い負荷がかかっていて、課題検索が多く行われている場合は、大きな影響が及ぶ場合があります。このような場合、再インデックスは深夜などのアクティビティが少ない期間に行うことをご検討ください。

再インデックス中に見込まれる競合、ロック、ブロック

1. バックグラウンドの再インデックスについては、ありません。Jira はシステム内のすべての課題を読み取り、各課題のインデックス エントリを再構築していきます。バックグラウンドの再インデックスは、ユーザーが課題を更新することで再インデックスさせるのと同じように実行されます。 
2. 表で行う再インデックスについては、該当します。表で行われる再インデックスでは、古いインデックスを完全に削除してゼロから再構築します。
3. クラスタ環境の場合、バックグラウンドの再インデックスでは、インデックス作成を行ったノードから完全なインデックスをコピーし、それを入れ替えるときに、セカンダリのノードで小規模な停止が発生します。

再インデックスをキャンセルしても引き続き Jira を使えますか?

1. Jira のロックとインデックスの再構築 - 再インデックスを止めることはできません。このプロセス中に Jira を再起動しても Jira を使用することはできず、インデックスが破損し、再インデックスを実行する必要があります。 

2. バックグラウンドでの再インデックス - 再インデックスをキャンセルすると、処理中のすべての課題が適切な状態になり、未処理の課題は再インデックスの開始前と同じ状態になります。再インデックスが実際には不要であった場合、再インデックスを開始してキャンセルしても問題はありません。構成変更によって再インデックスが必要になった場合、再インデックスは引き続き必要であり、近日中に時間を確保して完了させる必要があります。