Indexing Assets in Jira Service Management
Jira Service Management のアセットは、オブジェクト (資産と構成アイテム) のデータベースを管理するのに役立ち、リクエストを通じて簡単に操作できるようにします。ただし、これらのオブジェクトに対するクエリは、詳細な情報モデルが作成されるため、リソースを大量に消費する可能性があります。これらの課題に対処し、パフォーマンスを向上させるには、インデックスを使用できます。インデックスは、データベースのディスクに保存されているデータとは別の、アセット オブジェクト データのインメモリ コピーです。インデックスを使用すると、データへのアクセスがはるかに速くなり、パフォーマンスが向上し、アセット クエリ言語 (AQL) の結果が速くなります。
アセットとメモリの要件
インスタンスが大きくなるにつれて、インメモリ インデックスには時間の経過とともにより多くの Java 仮想マシン (JVM) メモリが必要になる可能性があります。アセットで使用する予定のデータ量を Jira が処理できるように設定されていることをご確認ください。アセットのメモリに関する推奨事項をご確認ください。
アセットのインデックス化の仕組み
アセットでは、インデックス化はインメモリ キャッシュ システムである Google の Guava Cache によって管理されます。このシステムでは、アセット データの種類が異なれば使用するインデックスも異なり、それぞれが特定のデータ カテゴリ向けに最適化されています。このアプローチでは、データが複雑になっても、システムは応答性と効果を維持します。Google の Guava Cache について詳細をご確認ください。
インデックス | 保存対象 |
|---|---|
オブジェクト |
|
オブジェクト タイプ属性 |
|
objectType |
|
objectSchema | 以下のような基本的なオブジェクト スキーマ:
|
オブジェクト チケット | Jira チケットとの関係 |
ファイル | アセットで参照されているファイル |
アイコン | アイコン データ |
カスタム フィールド、参照カスタム フィールド、既定のカスタム フィールド | アセットのカスタム フィールド設定 |
フリー テキスト インデックス | 検索に必要な ID、キー、ラベル、属性用語。フリー テキスト インデックスは、文字列全体を保存するのではなく、文字列をキーワードに減らします。フリー テキスト インデックスについて詳細をご確認ください。 これは Lucene に保存される唯一のインデックスです。 |
インデックス化されたフラグ
インデックス化されたフラグは、資産の特定の属性を検索および取得する目的でインデックスに含めるかどうかを決定する設定です。アセットでは、テキスト領域を除くすべての属性が既定でインデックス化されます。
特定の属性をインデックスから削除するには、その属性のインデックス化されたフラグを無効にします。これはメモリ消費量の削減に役立ちますが、属性をデータベースから直接取得する必要があるため、検索やインポートが遅くなる可能性があります。属性の設定について詳細をご確認ください。
属性のインデックス化を無効にしても、インデックス再作成のパフォーマンスに大きな影響はありません。ただし、インデックス化されていない属性のインポートのパフォーマンスは 2 倍を超える可能性があります。
ディスク ストレージ
Jira とは異なり、アセットのインデックスは Lucene には保存されません（フリー テキスト インデックスを除く）。つまり、アセットのインデックスは通常、ディスク上に残りません。管理者はインデックスを手動でディスクに転送できます。または、アセットの設定で [シャットダウン時にキャッシュを保存] を有効にすることで、シャットダウン時に自動的に転送することもできます。
システムがシャット ダウンする際に、[シャットダウン時にキャッシュを保存] が有効になっている場合、または [アセット インデックスをファイルに永続化] が手動でトリガーされると、次のインデックスが JiraLocalHome/caches/insight_indexes ディレクトリのファイルに書き込まれます。
オブジェクト
オブジェクト スキーマ
オブジェクト タイプ
オブジェクト タイプ属性
オブジェクト チケットの接続
このプロセスでは、インデックスを一時ファイルに書き込み、既存のインデックス ファイルを削除し、一時ファイルを insight_indexes ディレクトリに移動します。
起動時のディスク ストレージ
起動時に、[アセット インデックスをファイルから復元] が有効になっていると、インデックスはディスク上のインデックス ファイルから再作成されます。この設定が有効になっていない場合、インデックスはデータベースから再作成されます。
オブジェクトの数が多い場合は、データベースからインデックスを再作成するよりも、起動時にファイルからインデックスを復元する方が効率的です。ただし、データベースからインデックスを再作成することで、データの不整合の原因となり得るインデックス ファイルの破損というリスクを軽減できる可能性があります。構成の設定について詳細をご確認ください。
フリー テキスト インデックス
フリー テキスト インデックスは Lucene に保存され、テキスト領域、テキスト、URI、メール、選択属性などのアセットのテキスト属性でテキストを検索するために使用されます。
アセットのフリー テキスト インデックスは JiraLocalHome/caches/insight_indexes/freetext/directory に保存され、スキーマごとに 1 つのインデックスが保持されます。アセットでは毎晩深夜に、フリー テキスト インデックスを再作成する定期ジョブが自動的に実行されます。現在、このジョブを無効にするオプションはありません。さらに、手動でインデックス再作成が実行されるたびに、フリー テキストのインデックス再作成がトリガーされます。この設定により、インデックス化は最新の状態に保たれますが、インデックス再作成のスケジュールを管理する際の柔軟性が制限される可能性があります。
クラスタリングとレプリケーション
クラスター環境では、各ノードが独自のインデックスを保持しているため、すべてのノードが現在のデータの状態を認識できるように、変更をノード間でレプリケートする必要があります。このレプリケーション プロセスは、ネットワークの中断、高負荷 (インポート中など)、および一般的なパフォーマンス上の課題に対処する必要があるため、複雑です。レプリケーションは、オブジェクトが変更されるたびに行われます。
Jira Service Management 5.8.0 以降では、アセットの無効化通知には、オブジェクト インデックスのクラスター メッセージの代わりに Atlassian Cache のノード間無効化が使用されます。アセットのパフォーマンス改善について詳細をご確認ください。
レプリケーション フロー
レプリケーションには、作成、更新、削除というオブジェクト操作が含まれます。CacheMessage には次のものが含まれます。
インデックス タイプ
追加、削除、更新などの操作の種類
ID of the entity to update in the index
更新時刻
The default capacity for the work queue size is 10,000. You can configure the capacity by updating the Sender queue size property (com.atlassian.assets.replication.work.queue.size) on the Assets configuration page. More about Assets configuration
The batch replication message contains the IDs of the objects to be added and deleted and the IDs of updated objects along with their update times. For example, if there’s an object creation with the ID 21229075 in the jiradctest3 node, you can see the following message in the logs:
2024-09-19 16:55:59,747+0200 assets-replicator-3 TRACE [i.r.i.i.replication.poller.CacheMessageWorkQueuePoller] Batch message: AssetsBatchReplicationMessage(id=026ef180-78d5-487e-a8fb-35507714336f, sourceNode=jiradctest3, cacheType=OBJECT, addIds=[21229075, 21229057 ], updateIds={}, deleteIds=[], messageTimestamp=1726757759747, retryAttempts=0, lastRetryTimestamp=1726757759747)On the other nodes, the message could be similar to this:
2024-09-19 16:56:00,729+0200 RMI TCP Connection(4298)-10.150.208.4 DEBUG [i.r.i.index.replication.AssetsReplicationTransportManager] onRemove for event: 026ef180-78d5-487e-a8fb-35507714336f
2024-09-19 16:56:00,724+0200 RMI TCP Connection(5457)-10.150.208.4 DEBUG [i.r.i.index.replication.AssetsReplicationTransportManager] Received event from node jiradctest3 from object cache with ID 026ef180-78d5-487e-a8fb-35507714336f
2024-09-19 16:56:00,724+0200 RMI TCP Connection(5457)-10.150.208.4 DEBUG [i.r.i.index.replication.AssetsBatchReplicationMessageReceiver] Received message with ID 026ef180-78d5-487e-a8fb-35507714336f
2024-09-19 16:56:00,725+0200 assets-replication-receiver-0 TRACE [i.r.i.i.replication.poller.AssetsBatchReplicationMessageWorkQueuePoller] Processing replication message with ID 026ef180-78d5-487e-a8fb-35507714336fReplication happens by invalidation. Each node receives a remove message and independently loads updates from the database. More about Assets index validation property defaults
Dead-letter queue
A dead-letter queue (DLQ) is a holding area for messages that can't be processed successfully. By default, items on the retry queue are retried every minute for a total of 10 minutes. If you need, you can configure this in the Assets configuration.
When all retries fail, the failed update messages are moved to the DLQ. If necessary, you can replay (retry) items in the DLQ once you've resolved the root cause of the failure, or you can clear them if the issue can't be fixed or if a reindex has already been completed.
These endpoints let you either replay or clear the DLQ:
GET
rest/insight/1.0/deadletterqueue/replaythat replays the DLQ in a non-cluster mode and sends a broadcast request to replay the DLQ of all nodes in a clustered mode.GET
rest/insight/1.0/deadletterqueue/replay/{nodeId}that sends a unicast request to replay the DLQ of a specific node in a clustered mode. ThenodeIdis the node that should receive the request and replay its DLQ.
Reindexing Assets
You need to be a Jira system administrator to perform a reindex.
Sometimes, your Assets data can fall out of synchronization with the database. This can happen due to direct alterations in the database or if the index replication process fails. To get everything back, you'll need to reindex Assets. Reindexing involves dropping all in-memory data and pulling fresh data from the database. You can perform the following reindex actions:
Clean re-index where all objects will be removed from the index across all nodes, and then will be indexed again. This is recommended if you want to have a fresh state of the index. Once the indexing is in progress, you won't be able to cancel it, search for objects, or filter them. This reindexing will drop all IDs stored in the cache.
Re-index (standard re-index) where all objects will stay in the index during the process, and Assets will index them again. You can search for objects during the process. This reindexing will keep the IDs and only retrieve data for the IDs that are already in the cache.
The standard re-index method can expose faults in cases where IDs have been removed or added. If this happens, we recommend the clean re-index method. More about clean-reindex in Jira settings
Persists Assets index to file where you can manually persist (copy) the index on your disk. This is useful if you have a big Assets environment with a large number of objects and are planning to reinstall your Jira. With the index on your disk, Assets won't have to recreate it from scratch.
During a clean reindex, the local index for each type is cleared out, and a message is sent to all nodes to remove their copies of the index. This message includes the index type to be removed (like object) and the REMOVE_ALL operation. All local index files persisted on disk are deleted. The node that's processing the reindex will start rebuilding its index. You can configure the number of threads used in this process by adjusting the Assets parallelism property on the Assets configuration page. Then, all nodes will remove their local copy of the index and rebuild their indexes using the replication process.
ロックの適用
During a reindex, you can't use Assets on the node that's executing the reindex. In the case of a clean re-index, Assets can't be used across the entire cluster. To manage this, a lock is applied to prevent any modification of Assets data. Once the reindex is completed, Assets will unlock.
スタートアップ
On startup, if you've enabled Restore Assets index from file, the index will be recreated from the index files on disk. If you don’t enable this setting, the index will be re-created from the database. An integrity check of the Assets index files will be conducted against the database, which serves as the source of truth and verifies whether the data is consistent. If the data is inconsistent, an Assets reindex will be initiated.
You can see the reindex details in the logs that will look similar to the following example.
2024-11-11 10:15:27,870 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Control corrupted data done
2024-11-11 10:15:27,872 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] property: 'assets.version' set to: 20.2.0-SNAPSHOT
2024-11-11 10:15:27,873 InsightLauncherThread WARN anonymous [i.r.i.i.m.InsightPersistedIndexManager] Assets Object Cache file not found <localhome>/caches/insight_indexes/objectschema
2024-11-11 10:15:27,876 InsightLauncherThread WARN anonymous [i.r.i.i.m.InsightPersistedIndexManager] Assets Object Cache file not found <localhome>/caches/insight_indexes/objecttype
2024-11-11 10:15:27,877 InsightLauncherThread WARN anonymous [i.r.i.i.m.InsightPersistedIndexManager] Assets Object Cache file not found <localhome>/caches/insight_indexes/objecttypeattribute
2024-11-11 10:15:27,877 InsightLauncherThread WARN anonymous [i.r.i.i.m.InsightPersistedIndexManager] Assets Object Cache file not found <localhome>/caches/insight_indexes/objects
2024-11-11 10:15:27,877 InsightLauncherThread WARN anonymous [i.r.i.i.m.InsightPersistedIndexManager] Assets Object Cache file not found <localhome>/caches/insight_indexes/objectConnection
2024-11-11 10:15:27,881 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Restore Assets cache done
2024-11-11 10:15:27,882 InsightLauncherThread WARN anonymous [c.r.j.p.i.s.c.i.i.IndexIntegrityCheckerImpl] Integrity check failed, number of objects mismatched, database: 1, index: 0
2024-11-11 10:15:27,884 InsightLauncherThread WARN anonymous [c.r.j.p.i.s.c.i.i.IndexIntegrityCheckerImpl] Integrity check failed, number of objects schemas mismatched, database: 1, index: 0
2024-11-11 10:15:27,885 InsightLauncherThread WARN anonymous [c.r.j.p.i.s.c.i.i.IndexIntegrityCheckerImpl] Integrity check failed, number of objects types mismatched, database: 21, index: 0
2024-11-11 10:15:27,885 InsightLauncherThread WARN anonymous [c.r.j.p.i.s.c.i.i.IndexIntegrityCheckerImpl] Integrity check failed, number of objects type attribute mismatched, database: 138, index: 0
2024-11-11 10:15:27,888 InsightLauncherThread WARN anonymous [c.r.j.p.i.s.l.InsightLauncher] Cache integrity check failed: IndexIntegrity{objectJiraIssueIndexOk=true, objectSchemaIndexOk=false, objectTypeAttributeIndexOk=false, objectTypeIndexOk=false, objectIndexOk=false}
2024-11-11 10:15:27,893 InsightLauncherThread INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexServiceImpl] Numbers of objects in database 1
2024-11-11 10:15:27,895 InsightLauncherThread INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexServiceImpl] Starting Assets Reindex with a total work units of 161
2024-11-11 10:15:27,930 InsightLauncherThread INFO Anonymous user [c.r.j.p.i.s.c.m.AsyncTaskHandlerImpl] Starting InsightMultiThreadedEnabled service AsyncTaskHandlerImpl with parallelism set to 10
2024-11-11 10:15:27,934 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Check Assets cache integrity done
2024-11-11 10:15:27,934 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Start scheduling object attributes
2024-11-11 10:15:27,934 insight-InsightThreadGroup-worker-thread-0 WARN Anonymous user [c.r.j.p.i.s.c.i.ReindexServiceImpl] Starting Assets reindex in 10 threads
2024-11-11 10:15:27,934 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.InsightLockServiceImpl] Locking Assets insight_locked
2024-11-11 10:15:27,935 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Scheduling object attributes done.
2024-11-11 10:15:27,936 InsightLauncherThread INFO anonymous [c.r.j.p.i.s.l.InsightLauncher] Scheduling import done.
2024-11-11 10:15:27,936 insight-InsightThreadGroup-worker-thread-0 WARN Anonymous user [c.r.j.p.i.s.c.i.ClusterAwareReindexServiceImpl] Assets is locked for reindex
2024-11-11 10:15:27,943 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.c.i.ObjectTypeReindexStrategy] Getting object type IDs to index
2024-11-11 10:15:27,945 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.c.i.ObjectTypeReindexStrategy] Found 21 object type IDs to index
2024-11-11 10:15:27,946 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.c.i.ObjectTypeReindexStrategy] Started Assets reindex of object types
2024-11-11 10:15:27,974 insight-InsightThreadGroup-worker-thread-3 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:27,974 insight-InsightThreadGroup-worker-thread-3 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:27,974 insight-InsightThreadGroup-worker-thread-1 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,073 insight-InsightThreadGroup-worker-thread-8 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,074 insight-InsightThreadGroup-worker-thread-9 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,074 insight-InsightThreadGroup-worker-thread-5 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,075 insight-InsightThreadGroup-worker-thread-7 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,077 insight-InsightThreadGroup-worker-thread-6 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,078 insight-InsightThreadGroup-worker-thread-4 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,078 insight-InsightThreadGroup-worker-thread-2 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexObjectTypesJob] Object type index complete for thread
2024-11-11 10:15:28,078 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.c.i.ObjectTypeReindexStrategy] Reindex of object types completed in 135ms
2024-11-11 10:15:28,362 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.c.i.ReindexServiceImpl] Finishing progress OK ProgressId: resourceId: reindex, category: assets-reindex
2024-11-11 10:15:28,362 insight-InsightThreadGroup-worker-thread-0 INFO Anonymous user [c.r.j.p.i.s.InsightLockServiceImpl] Unlocking Assets insight_locked
2024-11-11 10:15:28,364 insight-InsightThreadGroup-worker-thread-0 WARN Anonymous user [c.r.j.p.i.s.c.i.ClusterAwareReindexServiceImpl] Assets is unlocked after reindex構成
アセットのグローバル Jira 設定にアクセスするには、次の手順に従います。
Go to Administration, then Manage apps.
In the Assets section, go to Assets configuration.
3. At the bottom of the Assets configuration page, select Edit settings.
4. Go to the General Assets configuration section and change the needed configuration.
構成 | 説明 | Why you might change this |
|---|---|---|
アセット インデックスをファイルから復元 | Decreases startup time by restoring the Assets index from a file. If you uncheck this setting, you’ll experience slower startup times. However, you’ll eliminate the risk of data inconsistency caused by a potentially corrupted index file Default is to restore cache from file. | Disabling this will always cause a reindex on startup. |
キャッシュをシャットダウン時に保存 | Stores the Assets cache on a file on plugin shutdown. | Storing the cache on shutdown can perform poorly when you're dealing with a very large number of objects. In such cases, consider increasing the Tomcat shutdown timeout, which is 60 seconds by default. Check the performance tuning settings |
アセット キャッシュを制限 | Limits the amount of objects stored in Assets cache. | To reduce the required memory footprint. |
キャッシュに許されるオブジェクトの数 | Specifies the maximum of objects that can reside in the Assets object cache. If this amount is exceeded, objects will be evicted by the last used LRU principle. | To change the maximum number of objects in the cache. |
インデックス サイズの制限
You can limit the number of objects in the Assets index to reduce memory consumption. However, this will affect performance for the objects that aren't in the index, as those objects will be queried directly from the database.
トラブルシューティング
If you run into indexing issues, refer to the information below.
不整合な状態のインデックス再作成
In some cases, data can end up in an inconsistent state in the database. When this happens, the data can't be referenced in the index, which can cause issues when you're trying to view it in the Assets application.
Starting with Jira Service Management 10.1, these errors display in the Assets indexing UI and logs. More about troubleshooting Assets index
アトラシアンのプロファイリングとメトリック
Assets collects and exposes some Java Management Extensions (JMX) metrics that you can use to monitor your assets replication stats. More about live monitoring using the JMX interface
ログ
Below you can see an overview of loggers (logging mechanisms) used in Assets to monitor and troubleshoot replication and reindexing processes.
logger | レベル | 説明 |
|---|---|---|
| DEBUG | Logs the DLQ content every 5 minutes by default, but only if the DLQ isn’t empty. You can change the logging frequency by updating Dead-letter queue logging interval (ms). |
| DEBUG | Logs Assets index replication statistics every 5 minutes by default. You can change the logging frequency by updating Dead-letter queue logging interval (ms). |
| DEBUG | Includes all replication logging. More about performance in Assets |
| DEBUG | Logs reindexing. |