How to monitor Storage Stream operations (PEGA0004 alert)

Benefits

Values of the Storage Stream column (pzPVStream) may require a large number of bytes of storage, and extracting or updating a property value from this column requires that the entire value be transmitted from the PegaRULES database to the server. Accordingly, careful design to minimize the number of Storage Stream operations can improve performance significantly.

Process Commander includes two alerts that provide information on Storage Stream operations:

• The PEGA0004 alert appears when the size of a Storage Stream column exceeds either of two specified limits. This alert applies to any type of access, including reads, updates, or searches.
• The PEGA0025 alert appears when any search operation — such as those produced by the Obj-Browse, Obj-List, or Obj-List-View method — requires a value from the Storage Stream

PEGA004 Alert

The system adds a line to the Alert log when the Process Commander server requests a very large volume of data from the Storage Stream columns of the PegaRULES database. The line includes this identifier:

PEGA0004 Number of bytes received from the database has exceeded threshold.

Two threshold values are provided: one for warnings and one that causes a fatal error. By default, the warning threshold is enabled with a value of 50 megabytes; Storage Stream values larger than 50MB cause the warning to appear in the Alert log. (By default, the fatal threshold is disabled.)

• In a development environment, such monitoring allows you to identify and isolate those database operations that retrieve a large volume of data that does not reside in exposed properties. Such operations affect JVM memory demand and may affect overall system performance.
• In a production setting, disable these facilities, or enable them only for short intervals of focused troubleshooting. Monitoring is somewhat costly in terms of system resources even when few measurements exceed the threshold values. Also, the errorMB setting terminates the activity, which can affect application results.

Data returned from columns other than the pzPVStream column does not count towards the threshold limits.

During upload of a ZIP archive, this alert setting is bypassed by design.

Building initial indexes for the Advanced Search facility (accomplished through the System Management application) search naturally requires reading every rule, data instance, or work object. In some cases, a PEGA0004 alert threshold (alerts/database/interactionByteThreshold/errorMB) can cause the indexing process to fail before completing. Before building initial indexes on a new installation, make sure no value is set for the errorMB setting.

Changing defaults

1. Edit the prconfig.xml file to enable the interactionByteThreshold feature and set cutoff values of the warnMB element in megabytes and a higher value for the errorMB element. Set value="0" for the errorMB element or warnMB to indicate no limit. If you omit the warnMB line, the default value for warnMB is 50MB.

<env name="alerts/database/interactionByteThreshold/enabled"      value="true"/>
<env name="alerts/database/interactionByteThreshold/warnMB"
     value="50"/>
<env name="alerts/database/interactionByteThreshold/errorMB"
     value="100"/>

2. Recommended values for warnMB and errorMB are 50 and 100 respectively, though you can use higher or lower thresholds.

3. Undeploy and redeploy the server to make the prconfig.xml file changes effective.

4. Monitor the Alert log for PEGA0004 alerts. Each PEGA004 alert line contains values for three performance statistics, identified by a property name (in the Log-Usage class). These may aid in diagnosing and addressing the issue:

• pxListRowWithoutStreamCount — Number of rows retrieved from the PegaRULES database that contained only properties exposed as columns, and no values from the Storage Stream (blob) column.
• pxListRowWithUnfilteredStreamCount — Number of entire rows retrieved from the PegaRULES database, containing all exposed columns and the Storage Stream (blob) column.
• pxListRowWithFilteredStreamCount — Number of rows retrieved from the PegaRULES database that included some properties from the Storage Stream (blob) column.

6. Monitor the Pega log for stack trace exceptions from the class:

com.pega.pegarules.engine.database.DatabaseImpl

If the amount of data returned from Storage Stream elements (after any needed decompression of the Storage Stream) exceeds the warnMB limit, the entry has an ALERT severity and appears in the Alert log, with a Java stack trace.

If the errorMB limit is exceeded, the entry has an ERROR severity, and the activity containing the database request ends.

Each log entry identifies the Requestor ID, the operator, and the currently executing activity.

Enhancing the application

Where possible, research reported exceptions and modify the application rules to eliminate them. These strategies may be appropriate, depending on the situation:

• Reduce the number of rows returned.
• Reduce the size of the expanded Storage Streams.
• Reduce the size of property values.
• Redesign the class to split values into two or more classes, if analysis shows this is beneficial.

PDN Articles

For additional examples and explanation of these facilities, consult the Pega Developer Network articles:

• PRKB-25335 Understanding the PEGA0004 Alert
• PRKB-25362 Understanding the PEGA0025 Alert
• PRKB-23116 How to detect and remedy the performance impact of Obj-List methods and List View reports

	exposed property, Pega log, PegaRULES database,Storage Stream
	How to detect lengthy PegaRULES database operations Working with the PegaRULES database Understanding alerts

SysAdmin category