How To
Summary
IBM DOORS Next 6.0.6.1 added an option to change the way that the underlying Jena file store handles reads and writes. This change provides DOORS Next with improved the reliability, consistency, and query throughput of DOORS Next when enabled.
Objective
This document describes how to enable this enhancement to the DOORS Next application. The document also describes what other changes must be made to the DOORS Next settings at the Java virtual machine level. Finally, a list of considerations, including use cases where enabling the Guava Cache in Jena is not advised.
What difference does applying "Guava Cache in Jena" make?
This setting allows the Jena layer to access the index more efficiently by preventing "blocks" from occurring when multiple operations are concurrently accessing the index. Jena relies on a recursive call structure in order to query data in the index, and as the call stacks increase there is a higher likelihood that these "blocks" occur. Once these blocks start to occur, performance degrades, which causes further blocks to form, which causes performance to degrade further.
The symptom of the block manager experiencing performance problems in this way can be confirmed by generating Java cores.
Benefits of using Guava Cache in Jena
The Journal file is designed to increase and decrease on its own. The growth observed in this environment is directly correlated with this blocking behavior - that is, the Journal file increase isn't directly responsible for performance degradation, but the two usually closely associated. Enabling the Guava Cache in Jena property significantly mitigates the performance degradation experienced in this scenario. It is important to note that the Journal continues to shrink and grow, and this fluctuation is not unexpected.
The Journal file is designed to increase and decrease on its own. The growth observed in this environment is directly correlated with this blocking behavior - that is, the Journal file increase isn't directly responsible for performance degradation, but the two usually closely associated. Enabling the Guava Cache in Jena property significantly mitigates the performance degradation experienced in this scenario. It is important to note that the Journal continues to shrink and grow, and this fluctuation is not unexpected.
Environment
DOORS Next Generation 6.0.6.1 (interim fix 17 applied).
This setting is independent of memory mapped I/O, or direct mode.
Platform independent.
Steps
How to set up "Guava Cache in Jena" with DOORS Next 6.0.6.1 (interim fix 17):
1. Browse to https://server/rm/admin -> Application -> Advanced Properties
2. Inspect the value specified for the setting: "Boolean value for using Guava Cache In Jena"
3. Set the value to true
1. Browse to https://server/rm/admin -> Application -> Advanced Properties
2. Inspect the value specified for the setting: "Boolean value for using Guava Cache In Jena"
3. Set the value to true
Note: If you enable Guava Cache in Jena before interim fix 17, see "Boolean value for using Guava Cache In Jena" is not visible in the UI or in teamserver.properties"
Adjust JVM heap size:
When this change is enabled, the Jena BlockManager adjusts the timing of writes to a more optimal point. It is expected that DOORS Next is running in mapped mode. Set the nursery to 25% of the size of the maximum heap. For example, -Xmx 12G, -Xms 12G, -Xmn 3G.
MBeans to monitor (available with interim fix 16):
1. Navigate to the admin page of the DOORS Next application,
2. Under Configuration session on the left pane, click Serviceability
OR navigate to: https://elmjas6061.ibm.com:9443/rm/admin#action=com.ibm.team.repository.admin.serviceability
OR navigate to: https://elmjas6061.ibm.com:9443/rm/admin#action=com.ibm.team.repository.admin.serviceability
3. Under the
Enable High Frequency Jena Metrics Collection property to "true"
4. Note the The default value is: 3600
Delay between invocations.
5. You will see "The configuration changes were saved successfully. To complete the updates, you must restart the server."
Note: Due to a build issue, when the MBeans detailed in the Steps section, were released, there were Harmless Errors Introduced by ELM 6061 interim fix 16. Enable these MBeans only after you apply 6.0.6.1 interim fix 18.
Additional Information
The information contained in this technote is based on how to improve performance for a "typical" DOORS Next 6.0.6.1 repository. The What difference does the Guava Setting (+Jena changes) make? information is key to understanding when not to implement this change.
In order to delay writes to disk, more Java heap, and RAM is used. If the DOORS Next is primarily used for long reads (for example: complex queries from reports) then it is possible that the Java heap would experience an Out Of Memory Exception.
The MBeans allow monitoring of the situation in real time. If there is a 3rd-party monitoring tool available, you can collect historical metrics as well.
If you suspect that your system is heavily query-based, with only occasional write transactions, then use the following ibm-doors-next-generation-performance-mustgather, then contact IBM Support for further advice before you make this change.
We expect DOORS Next users to run with memory mapped I/O on all platforms, except when you run a reindex. See IBM Engineering Lifecycle Query Engine performance is poor for query and indexing on Windows servers for issues related to Jena on Windows. These issues also impact DOORS Next on 6.0.6.1
Related Information
Document Location
Worldwide
[{"Type":"SW","Line of Business":{"code":"LOB59","label":"Sustainability Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSUVLZ","label":"IBM Engineering Requirements Management DOORS Next"},"ARM Category":[{"code":"a8m50000000Cj1gAAC","label":"DOORS Next->Administration"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"6.0.6"}]
Product Synonym
DOORS Next Generation; DNG; DOORS Next; DN
Was this topic helpful?
Document Information
Modified date:
21 May 2021
UID
ibm16454531