oak-run.jar でのインデックス作成の使用例

Oak-run は、コマンドラインで以下のようなインデックスに関する使用例をサポートします。AEM の JMX コンソールを使用する必要はありません。

oak-run.jar インデックスコマンドを使用して Oak インデックスを管理する全般的なメリットとして、以下のものがあります。

  1. Oak-run index コマンドは、AEM 6.4 用の新しいインデックス作成ツールセットを提供します。
  2. Oak-run を使用すると、インデックス再作成の時間を短縮でき、大規模なリポジトリでのインデックス再作成時間を削減できます。
  3. Oak-run を使用すると、インデックス再作成中の AEM でのリソース消費を低減できるので、システム全体のパフォーマンスが向上します。
  4. Oak-run は out-of-band のインデックス再作成機能を備えています。実稼動環境を利用したままインデックスを再作成する必要があり、インデックス再作成中のメンテナンスやダウンタイムが許容されない場合に使用できます。

以下の節では、コマンドの例を示します。oak-run インデックスコマンドは、すべての NodeStore および BlobStore 設定をサポートしています。以下では、FileDataStore および SegmentNodeStore を使用した設定の例を紹介します。

使用例 1 - インデックスの整合性チェック

これは、インデックスの破損に関連する使用例です。以前は、破損しているインデックスを特定できない場合もありました。このため、次の特長を持つツールが用意されています。

  1. すべてのインデックスでインデックスの整合性チェックを実行し、有効なインデックスと無効なインデックスに関するレポートを提供します。
  2. このツールは、AEM にアクセスできない場合でも使用可能です。
  3. このツールは簡単に使用できます。

破損しているインデックスのチェックは、--index-consistency-check 操作を使用して実行できます。

java -jar oak-run*.jar index --fds-path=/path/to/datastore  /path/to/segmentstore/ --index-consistency-check

これにより、indexing-result/index-consistency-check-report.txt にレポートが生成されます。サンプルレポートについては、以下を参照してください。

Valid indexes :
        - /content/oak:index/enablementResourceName
        - /oak:index/cqProjectLucene
        - /oak:index/cqTagLucene
        - /oak:index/lucene
        - /oak:index/ntBaseLucene
        - /oak:index/socialLucene
    Invalid indexes :
        - /oak:index/atDamIndex
        - /oak:index/atIndex
        - /oak:index/cqPageLucene
        - /oak:index/damAssetLucene
        - /oak:index/groups
        - /oak:index/slingeventJob
        - /oak:index/users
        - /oak:index/workflowDataLucene
    Ignored indexes as these are not of type lucene:
        - /oak:index/acPrincipalName
        - /oak:index/active

メリット

このツールを使用することにより、サポートおよびシステム管理者は、破損しているインデックスをすばやく特定し、これらのインデックスを再作成できるようになりました。

使用例 2 - インデックス統計

以前は、クエリパフォーマンスに関して診断する場合、お客様のセットアップの既存のインデックス定義やインデックス関連統計が必要になることがありました。これらの情報は、これまで複数のリソースに散在していました。より簡単にトラブルシューティングできるように、次の特長を持つツールが用意されています。

  1. システムに存在するすべてのインデックス定義を 1 つの JSON ファイルにダンプします。

  2. 既存のインデックスの重要な統計をダンプします。

  3. オフライン分析のためにインデックスコンテンツをダンプします。

  4. AEM にアクセスできない場合でも使用可能です。

前述の操作は、次の操作用の index コマンドを使用して実行できるようになりました。

  • --index-info - インデックスに関連するさまざまな統計を収集してダンプします。

  • --index-definitions - インデックス定義を収集してダンプします。

  • --index-dump - インデックスコンテンツをダンプします。

コマンドが実際にどのように機能するかについての例は、次を参照してください。

java -jar oak-run*.jar index --fds-path=/path/to/datastore  /path/to/segmentstore/ --index-info --index-definitions --index-dump

これらのレポートは、indexing-result/index-info.txt および indexing-result/index-definitions.json に生成されます。

また、同じ詳細が Web コンソール経由でも提供され、設定のダンプ zip にも含まれます。この詳細には、次の場所からアクセスできます。

https://serverhost:serverport/system/console/status-oak-index-defn

メリット

このツールを使用すると、インデックス作成またはクエリの問題に関連するすべての必要な詳細をすばやく収集できるので、この情報の抽出にかかる時間を短縮できます。

使用例 3 - インデックス再作成

シナリオによっては、インデックス再作成の実行が必要な場合があります。現在、インデックス再作成を行うには、CRXDE またはインデックスマネージャのユーザーインターフェイスを使用して、インデックス定義ノードで reindex フラグを true に設定します。このフラグが設定されると、インデックス再作成が非同期的におこなわれます。

次に、インデックス再作成に関するいくつかの注意点を示します。

  • インデックス再作成を DocumentNodeStore 設定で行うと、すべてのコンテンツがローカルにある SegmentNodeStore 設定で行う場合より、大幅に時間がかかります。

  • 現在の設計では、インデックス再作成中に非同期インデクサーがブロックされます。他のすべての非同期インデックスが古くなり、インデックス作成中に更新が取得されません。このため、システムが使用中の場合は、最新の結果が表示されないことがあります。

  • インデックス再作成には、リポジトリ全体のトラバーサルが伴います。これは、AEM 設定に大きな負荷がかかる可能性があり、エンドユーザーエクスペリエンスに影響する可能性があります。

  • DocumentNodeStore インストールでは、インデックス再作成にかなりの時間がかかる可能性があります。操作中に Mongo データベースへの接続に失敗すると、インデックス作成を最初からやり直す必要があります。

  • テキストを抽出するので、インデックス再作成に時間がかかる場合があります。これは、主に PDF ファイルが多く含まれる設定に当てはまります。テキスト抽出にかかる時間は、インデックス作成時間に影響する可能性があります。

これらの目的を満たすために、oak-run インデックスツールでは、必要に応じて使用できるインデックス再作成の様々なモードをサポートしています。oak-run インデックスコマンドには、次のメリットがあります。

  • out-of-band のインデックス再作成 - oak-run のインデックス再作成は、実行中の AEM 設定とは別に実行できるので、使用中の AEM インスタンスへの影響が最小限に抑えられます。

  • out-of-lane のインデックス再作成 - このインデックス再作成は、インデックス作成操作に影響を与えずに行なわれます。つまり、非同期インデクサーは他のインデックス作成を続行できます。

  • インストールでの簡略化されたインデックス再作成 - DocumentNodeStoreDocumentNodeStore インストールでは、インデックス再作成が単一のコマンドで実行できます。これにより、インデックス再作成が確実に最適な方法で実行されます。

  • インデックス定義の更新および新しいインデックス定義の導入のサポート

インデックス再作成 - DocumentNodeStore

DocumentNodeStore インストールでは、単一の oak-run コマンドを使用してインデックス再作成を行うことができます。

java -jar oak-run*.jar index --reindex --index-paths=/oak:index/lucene --read-write --fds-path=/path/to/datastore mongodb://server:port/aem

これには次のメリットがあります。

  • 実行中の AEM インスタンスへの影響が少ない。ほとんどの読み取りはセカンダリサーバーから実行できます。実行中の AEM のキャッシュは、インデックス再作成に必要とされるトラバーサルをすべて考慮しても、悪影響は受けません。
  • ユーザーは、--index-definitions-file オプションを使用して新しいインデックスまたは更新されたインデックスの JSON を提供することもできます。

インデックス再作成 - SegmentNodeStore

SegmentNodeStore インストールでは、次のいずれかの方法でインデックス再作成を行うことができます。

オンラインのインデックス再作成 - SegmentNodeStore

既定の方法に従い、reindex フラグを設定してインデックス再作成を行います。

オンラインのインデックス再作成 - SegmentNodeStore - AEM インスタンス実行中

SegmentNodeStore インストールでは、セグメントファイルに読み取り／書き込みモードでアクセスできるのは 1 つのプロセスのみです。このため、oak-run のインデックス作成の一部の操作では、手動による追加の手順が必要です。

これには、次のものが含まれます。

  1. ステップテキスト

  2. AEM で使用される同じリポジトリに oak-run を読み取り専用モードで接続し、インデックスを作成します。これを実行する方法の例：

    java -jar oak-run-1.7.6.jar index --fds-path=/Users/dhasler/dev/cq/quickstart/target/crx-quickstart/repository/datastore/ --checkpoint 26b7da38-a699-45b2-82fb-73aa2f9af0e2 --reindex --index-paths=/oak:index/lucene /Users/dhasler/dev/cq/quickstart/target/crx-quickstart/repository/segmentstore/

  3. 最後に、前述のコマンドを実行した後で、IndexerMBean#importIndex 操作を使用して、oak-run がインデックスファイルを保存したパスから、作成したインデックスファイルを読み込みます。

このシナリオでは、AEM サーバーを停止したり、新しいインスタンスをプロビジョニングしたりする必要はありません。ただし、インデックス作成にはリポジトリ全体のトラバーサルが伴うので、インストールへの I/O 負荷が増加し、実行時のパフォーマンスに悪影響があります。

オンラインのインデックス再作成 - SegmentNodeStore - AEM インスタンスのシャットダウン

SegmentNodeStore インストールでは、単一の oak-run コマンドを使用してインデックス再作成を行うことができます。ただし、AEM インスタンスをシャットダウンする必要があります。

次のコマンドを使用して、インデックス再作成を開始できます。

java -jar oak-run*.jar index --reindex --index-paths=/oak:index/lucene --read-write --fds-path=/path/to/datastore  /path/to/segmentstore/

この方法と前述の方法の違いは、チェックポイントの作成とインデックスの読み込みが自動的におこなわれることです。欠点は、処理中に AEM を終了する必要があることです。

Out of Band のインデックス再作成 - SegmentNodeStore

この使用例では、クローン作成された設定でインデックスを再作成して、実行中の AEM インスタンスへの影響を最小限に抑えることができます。

  1. JMX 操作でチェックポイントを作成します。これを行うには、JMX コンソールに移動して、CheckpointManager を検索します。次に、createCheckpoint(long p1) 操作をクリックして、秒単位の有効期限に大きい値（2592000 など）を使用します。

  2. 新しいマシンに crx-quickstart フォルダーをコピーします。

  3. oak-run の index コマンドを使用してインデックスを再作成します。

  4. 生成されたインデックスファイルを AEM サーバーにコピーします。

  5. JMX を使用してインデックスファイルをインポートします。

このユースケースでは、別のインスタンスのデータストアにアクセスできることを前提としていますが、FileDataStore が EBS などのクラウドベースのストレージソリューションに配置されている場合は、このデータストアにアクセスできないことがあります。この場合、FileDataStore のクローンも作成されるシナリオは除外されます。インデックス定義でフルテキストのインデックス作成が実行されない場合は、DataStore へのアクセスは必要ありません。

使用例 4 - インデックス定義の更新

現在、インデックス定義の変更は、ACS Ensure Index パッケージ経由で送信できます。これにより、コンテンツパッケージ経由でインデックス定義の送信が可能になります。コンテンツパッケージは後で、reindex フラグを true に設定してインデックスを再作成する必要があります。

これは、インデックス再作成に時間がかからない小規模なインストールに適しています。ただし、非常に大きいリポジトリでは、インデックス再作成にかなりの時間がかかります。このような場合は、oak-run インデックスツールを使用できます。

oak-run では、インデックス定義を JSON 形式で提供したり、out-of-band モードでインデックスを作成したりすることができます。out-of-band モードの場合、ライブインスタンスでは変更がおこなわれません。

この使用例を検討する必要があるプロセスは次のとおりです。

  1. 開発者がローカルインスタンスでインデックス定義を更新し、インデックス定義の JSON ファイルを --index-definitions オプションを使用して生成します。

  2. 更新された JSON がシステム管理者に提供されます。

  3. システム管理者は Out of Band 方式に従って、別のインストールでインデックスを準備します。

  4. これが完了すると、生成されたインデックスファイルが、実行中の AEM インストールに読み込まれます。

このページ