F Enabling Memory Guard Features

This section describes configuration settings available to safeguard your system against memory failures caused by report requests that generate excessive data.

It includes the following sections:

Note:

Memory Guard applies to Oracle BI Publisher 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI Publisher 11.1.1.7.10, see "New Features for 11.1.1.7.10."

F.1 What Are Memory Guard Features?

BI Publisher provides a set of features to provide options to protect Oracle BI Publisher server instances from out-of-memory errors by blocking report requests that generate excessive amounts of data. These "memory guard" features consist of a set of properties that you set in a configuration file. The properties enable you to configure conditions and processing points at which data size is inspected to determine whether the system continues to process a report request or terminates processing. When processing terminates due to data size, an error message is returned to the user.Before going live in your system with the settings, you can enable a test mode. In test mode no reports are rejected, but the results are written to the log file giving you the opportunity to see which requests would trigger termination before you enable the settings in production.

F.2 Key Features

There are nine properties that comprise the memory guard features. Some properties work together to fully define the conditions to terminate processing. The key settings are:

Specify a Maximum Data Size Allowed for Online Processing

This feature enables you to specify a maximum data size allowed for online report viewing. When you set a maximum data size, the following occurs when a user opens a report for online viewing:

  1. A user submits a report to view online in the browser.

  2. The data engine generates the data for the report.

  3. Before document generation, the size of the data (in bytes) is inspected.

  4. If the data generated is larger than the maximum setting, the report processing is ended. The user gets the following message:

    The report you are trying to run exceeds the data limit set for this server. Either re-run with parameters that reduce the data or schedule this report. Contact your Administrator if you have questions.

    The user can then either set parameters (if available for the report) to limit the data and resubmit online; or use the BI Publisher scheduler to submit the report.

To enable this feature, set the property ONLINE_REPORT_MAX_DATA_SIZE.

Specify A Minimum Free Memory Threshold for Online Processing

This setting enables you to specify a minimum value for free JVM space. This enables you to control whether to run a report based on two factors: current usage and the size of the report data. This feature requires the setting of several properties that work together. You specify the threshold JVM space, the report maximum report size that will be allowed when the JVM falls below the threshold, and the maximum wait time to pause the report to wait for more JVM free space to become available.

When you set these properties, the following occurs when a user opens a report for online viewing:

  1. A user submits a report to view online in the browser.

  2. The data engine generates the data for the report.

  3. JVM memory is inspected. If the available JVM memory is above the threshold value, the report processes as usual and there is no system intervention.

    If the available JVM memory is below the threshold value, the size of the report data is inspected and compared to the setting online report data size under free memory. If the report data is below this threshold, then the report continues processing.

    If the report data size exceeds the threshold, then the report is paused to wait for free memory to become available. The report will wait for the time specified in the wait period setting. If the free memory does not rise back above the minimum in the wait period specified, the report request is rejected.

Set Maximum Data Size That Can Be Generated by the Data Engine

This setting sets an absolute limit to the data that can be generated from the execution of a data model. This setting applies to both online report requests and to requests submitted through the scheduler. When the size of the file generated by the data engine exceeds the limit, the data engine terminates execution of the data model and throws the exception:

"oracle.xdo.dataengine.diagnostic.XMLSizeLimitException: XML Output (NNNNNNbytes) generated exceeds specified file size limit (NNNNNbytes)..!!!!!!!".

If the report request was submitted through the scheduler, the job will show as failed in the Report Job History page. The exception error noted above displays when you rest your cursor over the status. If the report request was submitted online, the user will get the error "Unable to retrieve the data XML."

Set Automatic Database Fetch Size

This setting calculates and sets database fetch size at run time depending on total number of data set columns and total number of query columns. Setting this property will override the server-level and data model-level database fetch size properties. When set, this property takes effect for all data models and can significantly slow processing time. This setting is recommended for implementations of BI Publisher that frequently process complex queries of hundreds of columns, such as Oracle Fusion Applications implementations. This setting is not recommended for most general implementations of BI Publisher.

F.3 Configuring Memory Guard Options

Implement the memory guard features by adding this set of properties to the xmlp-server-config.xml file located at:

{BI Publisher Repository}/Admin/Configuration/xmlp-server-config.xml

The property settings are described in Table 1.

Table F-1 Memory Guard Properties and Descriptions

Property Description

ONLINE_REPORT_MAX_DATA_SIZE

Default value: 20000000

Set the maximum allowed online report data size in BYTES. An online report request will always be rejected immediately when the report data size returned from the execution of the data model exceeds the value of this property.

If this property is not set in the configuration file or if the value set is negative, this condition is ignored and no request is rejected based on this condition.

ONLINE_REPORT_FREE_MEMORY_THRESHOLD

Default value: 100000000

Threshold value of free JVM memory in BYTES to trigger possible rejection of report requests. When JVM free memory returned from run time is below the value of this property, the server will check the report data size to decide if a request should be accepted or rejected. This property works together with the three properties:

  • ONLINE_REPORT_MAX_DATA_SIZE_UNDER_FREE_MEMORY_THRESHOLD

  • MINIMUM_SECOND_RUN_GARBAGE_COLLECTION

  • WAIT_SECOND_FOR_FREE_MEMORY

If this property value is not set or the value set is negative, this condition will be ignored. This property is for online report requests only.

ONLINE_REPORT_MAX_DATA_SIZE_UNDER_FREE_MEMORY_THRESHOLD

Default value: 10000000 (bytes)

Maximum report data size in BYTES allowed when free JVM memory is under the specified threshold value set in ONLINE_REPORT_FREE_MEMORY_THRESHOLD. A request will be rejected when its report data size exceeds the value of this property.

This property takes effect only if ONLINE_REPORT_FREE_MEMORY_THRESHOLD is set to be a positive value. This property is for online report requests only.

MINIMUM_SECOND_RUN_GARBAGE_COLLECTION

Default value: 300 (seconds)

Minimum time span in seconds between any two subsequent garbage collection runs. Set this value to avoid overrunning JVM garbage collection. The server enforces the minimum of 120 seconds, which means the value will be reset to 120 seconds if it falls below the minimum.

WAIT_SECOND_FOR_FREE_MEMORY

Default value: 30 (seconds)

The maximum time in seconds that a run-report request will wait for free JVM memory to come back above the threshold value. This property value takes effect only when a positive value of ONLINE_REPORT_FREE_MEMORY_THRESHOLD is specified. If the free memory comes back in the time less than the value of WAIT_SECOND_FOR_FREE_MEMORY, the request will proceed immediately to generate the document. If free memory is still below the threshold value after WAIT_SECOND_FOR_FREE_MEMORY seconds, the request will be rejected. The larger this property value, the longer the browser will wait for a request to run.

MEMORY_GOVERNOR_MODE

Default value: test

Valid values are: "production" and "test"

This setting enables you to run memory guard features in test mode. In test mode, all memory checks and logging are performed but no requests are terminated or rejected. You can view the results in the BI Publisher log file to see which requests would have been terminated or rejected. This feature can help you determine which requests are causing memory issues before you enable the other features in your system. The log level must be set to WARNING or higher.

XML_DATA_SIZE_LIMIT

Default value: 2GB

Maximum XML data size in BYTES that can be generated from the execution of a data model. This setting applies to both online report requests and to requests submitted through the scheduler. When the size of the file generated by the data engine exceeds the value set for this property, the data engine terminates execution of the data model and throws an exception. This property value takes effect only if XML_DATA_SIZE_LIMIT is set to be a positive integer value.

When the value of this property is set with no units, the system assumes bytes, for example, "1000000" (bytes). You can also specify megabytes or gigabytes using "MB" and "GB", for example,"1MB" or "2GB".

DB_FETCH_SIZE_AUTO

Default value: false

Process calculates and sets database fetch size at run time depending on total number of data set columns and total number of query columns. This property value takes effect only if DB_FETCH_SIZE_AUTO is set to true. Setting this property will override the server-level and data mode- level database fetch size properties.

ENABLE_DATAMODEL_DIAGNOSTIC

Default value: false

Setting property ENABLE_DATAMODEL_DIAGNOSTIC value to true will write data set details, memory, and SQL execution time information to the log file. Oracle recommends setting this property to true only for debugging purposes. When set to true, processing time is increased.


F.4 Sample Configuration File Entries

The following shows sample entries for the memory guard properties in the xmlp-server-config.xml file

({BI Publisher Repository}/Admin/Configuration/xmlp-server-config.xml):

<property name="ONLINE_REPORT_MAX_DATA_SIZE" value="2000000" /> 
<property name="ONLINE_REPORT_FREE_MEMORY_THRESHOLD" value="100000000" />
<property name="ONLINE_REPORT_MAX_DATA_SIZE_UNDER_FREE_MEMORY_THRESHOLD" value="1000000" /> 
<property name="MINIMUM_SECOND_RUN_GARBAGE_COLLECTION" value="300" /> 
<property name="WAIT_SECOND_FOR_FREE_MEMORY" value="30" /> 
<property name="MEMORY_GOVERNOR_MODE" value="test" /> 
<property name="XML_DATA_SIZE_LIMIT" value="2GB"/> 
<property name="DB_FETCH_SIZE_AUTO" value="true"/> 
<property name="ENABLE_DATAMODEL_DIAGNOSTIC" value="true"/>