MicroStrategy ONE

Avoid Server Shutdown when the Memory Contract Manager Limit is Exceeded

Hitting the Memory Request Idle Time limit set by Memory Contract Manager can cause the Intelligence Server to shut down, leaving the MicroStrategy environment unavailable. To avoid these types of shutdowns, administrators can enable the Intelligence Server to unload uncertified cubes from memory to allow the Intelligence Server to try and recover before it crashes. For more information about certifying cubes, see the Workstation Help.

Starting in MicroStrategy ONE (September 2024), you can swap server messages to disk to improve server stability and prevent memory outages.

Starting in MicroStrategy ONE (June 2024), there is more granular control over the cube unload process.

If you are using a MicroStrategy version prior to MicroStrategy ONE (June 2024), see Enable or Disable Cube Unloading Prior to MicroStrategy ONE (June 2024).

Starting in MicroStrategy ONE (September 2024), when system memory is low (for example, available total system memory is less than 20% of the machine or container's physical memory), the Intelligence Server will automatically swap the least recently used (LRU) server messages to disk which releases up to 20% of total working set memory usage. For more information, see Swap Server Messages to Disk.

For more information about server messages and working set, see Governing User Resources

Unload Cubes in Low Memory

When system memory is low, such as when the available total system memory is under pressure (less than 20% of the machine/container's physical memory), the Intelligence Server will automatically start unloading cubes up to 10% of the total physical memory, using the following steps:

  1. Release index of cubes not used in the past 2 days. Administrators can customize the most used cube interval via registry. This is enabled by default and Administrators can disable cube index governing.

  2. If you Enable Cube Governing and the system is still under pressure, the Intelligence server will start unloading cubes based on the Least Recently Used (LRU) algorithm. This setting is disabled by default.

If the system does not recover from low memory and enters Memory Depletion status, the Intelligence Server will follow the same steps above to unload a larger number of cubes. For more information, see Governing Intelligence Server Memory Use with Memory Contract Manager.

The unload process will be skipped if cube memory usage is less than 30% of the total physical memory. Certified cubes will be skipped.

Enable Cube Governing

To enable the behavior in MicroStrategy Web:

  1. On the upper right of any page, click your user name, and then select Preferences from the drop-down list.

  2. From the left, select General.

  3. Enable Cube Governing.

  4. Save the change.

If enough memory is released before reaching the full Memory Request Idle Time limit, Intelligence Server will exit Memory Contract Manager. If not, Intelligence Server will still be shutdown by Memory Contract Manager as usual. Even if the Intelligence Server will avoid shutdown, the unloading process will be performed for all cubes once it is triggered.

Enable or Disable Cube Unloading Prior to MicroStrategy ONE (June 2024)

How to Enable or Disable Cube Unloading

The feature is by default off in MicroStrategy ONE. This feature can be enabled through a environment variable named DisableUnloadingCachingForMCM.

Available settings:

  • DisableUnloadingCachingForMCM is unset, the feature is off by default.
  • DisableUnloadingCachingForMCM= 0, the feature is on.
  • DisableUnloadingCachingForMCM= 1, the feature is off.

To change the value of this setting on:

  • Windows:

    1. Go to Environment Variables > System Variables.
    2. Add a variable named DisableUnloadingCachingForMCM with value of 0.

  • Linux:

    1. Export DisableUnloadingCachingForMCM=0 in the same terminal before starting Intelligence Server.

      If the variable is set correctly, you could see following log in the DSSErrors.log file:

      [Kernel][Info][UID:0][SID:0][OID:0] The environment variable "DisableUnloadingCachingForMCM" is set to 0. Enable unloading cube For MCM.

Feature Behavior

When the Intelligence Server exceeds half of the Memory Request Idle Time setting, the cube unloading will be triggered. Messages such as the following will appear in the DSSErros.log file:

  • [Kernel][Info][UID:0][SID:0][OID:0] Intelligence Server has entered Request Idle Mode for 301 seconds, the event of purging cache is triggered.

All un-certified cubes for each project will then be unloaded one by one to release memory. Messages such as the following will appear in the DSSErros.log file:

  • [Kernel][Info][UID:0][SID:0][OID:0] Start to unload cube for project "ART - GCSBB AML Reporting" to release memory for Intelligence Server, current memory for loaded cubes in this project's cube manager is 1177845.

  • [Kernel][Info][UID:0][SID:0][OID:0] Finish attempting to unload cubes for project "ART - GCSBB AML Reporting", current memory for loaded cubes in this project's cube manager is 0. Some cubes may be loaded again by other users during the processing. Please check cube monitor to find out which cube is not unloaded.

If enough memory is released before reaching the full Memory Request Idle Time limit, Intelligence Server will exit Memory Contract Manager. If not, Intelligence Server will still be shutdown by Memory Contract Manager as usual. Even if the Intelligence Server will avoid shutdown, the unloading process will be performed for all cubes once it is triggered.

Swap Server Messages to Disk

Key considerations when swapping server messages to disk:

  • The latest active server message of each session will not be swapped.

  • Correct configuration of the Working Set file directory is required. For more information, see Edit Server-Level Governing Settings.

  • The swap skips if the following scenarios occur:

    • The current usage of working set memory is less than 20% of the Maximum memory for working set cache governing setting.

    • The Intelligence Server already entered MCM denial status.

      The swap skips to avoid an additional memory request that is required by disk operations. For more information on MCM denial status, see Governing Intelligence Server Memory Use with Memory Contract Manager.

This feature is enabled by default. You can Disable Working Set Memory Governing via the MicroStrategy REST API, if necessary.

Disable Working Set Memory Governing via the MicroStrategy REST API

  1. Open the MicroStrategy REST API Explorer by appending /MicroStrategyLibrary with /api-docs/index.html?visibility=all in your browser.

  2. Create a session and authenticate it. In the Authentication section, use POST /api/auth/admin/login.

  3. Click Try Out and modify the request body by providing your username and password.

  4. Click Execute.

  5. In the response, find X-MSTR-AuthToken.

  6. To get the current setting status:

    1. Under the Configurations section, look up GET /api/v2/configurations/featureFlags.

    2. Click Try Out.

    3. Set the proper X-MSTR-AuthToken from step 5. You can also get this via inspecting the browser network XHR requests.

    4. Click Execute.

    5. Search for WorkingSetGoverning in the response body to find its status details.

  7. Under the Configurations section, look up PUT /api/configurations/featureFlags/{id}.

  8. Click Try Out.

  9. Set the proper X-MSTR-AuthToken from step 5. You can get this by inspecting the browser network XHR requests.

  10. Set id to 2858F54E4B456DFD52AC90BA740DF4C8.

  11. To disable this setting, set the status value to 2.

  12. Click Execute.

  13. Repeat step 6 to verify that the setting is disabled.