About the Performance tool

Using this data, you can assess possible sources of improved performance (faster response time or higher throughput) through software changes, hardware changes, or rule changes.

As Process Commander operates, it collects statistics about the demands made on processing resources, and the server system's response. The Performance tool summarizes and formats these statistics and presents them as HTML pages.

Performance data shows the processing demand statistics of your work since you connected, and may help you assess the performance impact of various approaches or configuration choices.

The DB Trace facility logs all SQL interactions between your Process Commander session and the PegaRULES database.

Performance statistics can help you distinguish between performance issues that arise in the Process Commander server, the PegaRULES database, or external systems called by the workflow. In all cases, the statistics can help you determine how to improve performance.

To view performance data:

1. Select Run > Performance or type the equivalent keyboard shortcut CTRL + Q.
2. The Performance panel appears, containing statistics that reflect totals since you logged on.
3. You can interact with the summary tool page to record statistics. See Performance tool — Using the Summary display.

Through a personal preference, you can control whether the Performance tool opens in a new window or in the lower half of the Developer workspace.

1. Select Edit > Preferences.
2. Access the Tools group of preferences. Select the Performance check box to cause the tool to open in a new window. Clear the check box to cause the tool to open within the workspace.
3. Click  Save  .

When the Performance tool appears in the lower half of the Developer portal window, you can click and drag the top edge upward to view more of the statistics.

Click the INIT, FULL, or DELTA links to access the Full Details display for that row. This display provides additional statistics from the same snapshot.

See Performance tool — Full Details Display.

The CPU statistic (pxProcessCPU property) records CPU time in seconds for the Java process since startup of the node, covering all requestors combined. This statistic is available on all platforms.

For other Performance tool, CPU statistics, whether CPU data appears depends on the platform.

Although some vendors' Java 5 and later JVM implementations support process-level CPU data and some support thread-level CPU data, obtaining correct CPU data is often too costly. The Performance tool attempts to get CPU timings from management APIs that are included in Java 5 and Java 6. However, while the JVM must implement the API methods, it does not have to actually implement the underlying functionality - so support for cpu timings without the pr3native library depends upon the version of Java, the manufacturer of the JVM and the operating system — such as AIX versus Solaris — on which the code is running.

Beginning with v5.4, if the prconfig.xml file specifies that the native library should not be loaded, the Performance tool still attempts to obtain CPU timings from the JVM and will report them if available.

Linux

For Linux-based systems, all per-requestor CPU statistics are reported as zero.

Windows

CPU usage statistics for each requestor interaction are available only for Process Commander systems hosted on the Microsoft Windows operating system (both X86 and X64).

Requestor-level CPU statistics on Windows servers depend on the Java Native Interface (JNI) implementation in the Microsoft pr3native.dll file, which is loaded by default.

However, on a busy Windows server, the JNI may add some overhead to both processor and memory. If you do not need the CPU statistics, you can disable this DLL. To disable requestor-level CPU statistics on Windows servers, update the prconfig.xml file setting for the useNativeLibrary setting:

<env name="Initialization/usenativelibrary" value="true" />

and redeploy (or restart, as appropriate). See Pega Developer Network article PRKB-25002 Enabling PAL CPU counters using the pr3native library.

Solaris and AIX

On Sun Solaris systems and IBM AIX systems, the vendor-supplied Java Native Interface pr3native.so file supports elapsed time statistics. No other features of Process Commander depend on this file; if this file is not present, an error is noted in the Pega log at startup, and elapsed time statistics are less precise, but other processing is unaffected.

The Performance tool supports interactive sessions directly. Services operate as background requestors; you can capture selected Performance statistics in a log file. See Performance tool — Statistics for services.

You can monitor the interactions between Process Commander's server engine and the PegaRULES database or other relational databases, and the operation of the rule cache. Familiarity with SQL is required to interpret the output. To use this facility:

1. Open the Full details window.
2. Click the DB Trace Options link to set up which database events are monitored. See Setting DB Trace options.
3. Click the Start DB Trace link to turn on the facility and record SQL statements that Process Commander sends to the database software.
4. Click Stop DB Trace to end data collection and access the trace results as a text file or with Microsoft Excel. See Interpreting DB Trace Results.

Unlike the resource statistics feature, the DB Trace feature is normally off. Use the DB Trace feature only for a brief interval. When enabled, DB Trace processing can produce voluminous output and may adversely affect session performance.

The DB Trace tool link is not displayed in a production system — a system with the Production Level on the System form set to 5. In addition, the DB Trace is available only to users who have the PegaRULES:SysAdm4 access role. These access roles provide access to the standard privilege named Code-Pega-.PerformanceTools.

You can start and stop this tool from an activity, by calling the standard activity Code-Pega-Requestor.SetRequestorLevelDBTrace to turn the DB Trace tool on and off.  This activity sets the pxRequestor.pyDBTraceEnabled property; the tool closes the output text file when tracing is turned off.

System-wide database trace

An alternative approach that provides comprehensive tracing of SQL statements sent to the PegaRULES database is the dumpStats parameter in the prconfig.xml file.

To enable this feature:

1. Update the <database> node of the prconfig.xml file to add this element:

<entry key="dumpStats" value="true" />

2. Stop and restart the application server.

This setting generates a system-wide database trace file in the ServiceExport directory that can become very large quickly, and can affect system performance. Use this setting only for brief periods, and when a single-requestor DB trace is not suitable.

When two instances of Process Commander are installed on a single Windows server (for example, one for testing and one for production), only one copy of the pr3native.dll library can be loaded. The second copy is not loaded; Performance tool CPU statistics may not be available on the copy started second.

Timings are based on JVM software implementations that depend on JVM versions and vendor; this may limit the validity of cross-system comparisons. If your system uses Sun Microsystems JVM 1.4.2 or 1.5, the sun.misc.Perf interface is used. In other JVMs, the System.nanoTime or system.CurrentTimeMillis class may be used.