Back ForwardHow to analyze system-wide usage with the Log-Usage class

Show all 

Instances of the Log-Usage class, which (in the initial PegaRULES database schema) are stored in the pr_perf_stats table, support system-performance and usage reporting. C-2655

The instances in this class provide a cumulative history of past system usage across all nodes and all requestor types. Analyses of this data can provide valuable insights about the patterns and sources of processing demand, and can be helpful in performance tuning.

NoteDon't confuse Log-Usage data, which covers system and requestor performance of all types. with Log-RuleUsage data, which cover only rules assembly rules — rules of those rule types that the system converts to Java code.

NoteDon't confuse Log-Usage reporting — which provides comprehensive coverage of system activity — with the reports provided by the License Compliance facility, which focus on specific metrics and uses a separate data-collection mechanism.

Keys of instances the Log-Usage class

The key (pzInsKey column) of the pr_perf_stats table — the key of each Log-Usage instance — is concatenated from the values of four properties:

The first character of the requestor ID identifies a requestor type:

Record types

Identifying a snapshot

The pxSnapshotType column identifies an important value needed to interpret the other values in a record. This column has one of six values: REMOVED ACTIVATE 8/7/09 MIRAT

Identifying an agent or daemon

For agents and daemons, the pyProcLabel property PROJ-537 identifies the agent, the index of the row on the Rule-Agent-Queue form, and the activity. The subscript is zero-based; for example, the value:

Pega-ProCom:2:Assign-Corr.SendCorr

in a log identifies processing by the Assign-Corr.SendCorr activity listed the second row of Agent Queue form for the Pega-RULES agent.

For daemons such as the master agent, the pyProcLabel column is blank.

When the system adds to this class

A daemon known as the Usage Daemon commits instances of the Log-Usage class to the database table.

The Usage Daemon saves an instance of the Log-Usage class when a requestor terminates, passivates, activates, and at regular hourly intervals. To minimize the performance effect of new instances, the daemon's write operations are deferred and then committed as a group.

By default, INTERVAL operations record a snapshot at 59 minutes after each hour. For example, if an Operator signs on at 11:15 AM and signs off at 11:56 AM, no INTERVAL instances for that requestor are logged.

By default, this daemon wakes every 300 seconds, so the contents of the table may be stale or incomplete by as much as five minutes.

In a multinode cluster, the Usage Daemons on each node operate independently, so the presence of records in the database table with a recent pxSnapShotTime from one node does not imply that no more records with a similar or earlier pxSnapShotTime value will arrive.

Because agents are requestors, this daemon adds instances to the Log-Usage class for agents even when the system has no interactive users. This behavior is expected.

Some service requestors end a few seconds or less after they start; typically no INTERVAL instances appear for such requestors. If a service uses pooled requestors, INTERVAL instances may appear for those requestors in the pool once each hour. VAGUE OR CONFUSING

Reporting

To facilitate reporting, all properties of the Log-Usage class are exposed as columns of the pr_perf_stats table; this table does not contain a Storage Stream column.

Except for the properties in the following table, the names and meanings of statistical properties in the Log-Usage class is identical to the names and meanings of those in the Code-Pega-PAL class, which supports the Performance tool. For a listing and brief descriptions of those properties, see Performance tool — Full details display. B-24166

For technical reasons, Log-Usage properties listed in the following table have a shorter name from the corresponding Code-Pega-PAL properties. B-24234

Code-Pega-PAL Property

Log-Usage Property

pxDeclarativeRulesInvokedBackgroundCount pxDeclRulesInvokedBckGrdCnt
pxDeclarativeRulesInvokedElapsed pxDeclRulesInvokedElapsed
pxDeclarativeRulesLookupElapsed pxDeclRulesLookupElapsed
pxListRowWithFilteredStreamCount pxListRowWithFilteredStrmCnt
pxListRowWithUnfilteredStreamCount pxListRowWithUnfilteredStrmCnt
pxListWithUnfilteredStreamCount pxListWithUnfilteredStrmCnt
pxSavedClipboardAfterInteractionCount pxSavedCbAfterIntCount
pxSavedClipboardAfterInteractionCPU pxSavedCbAfterIntCPU
pxSavedClipboardAfterInteractionElapsed pxSavedCbAfterIntElapsed
pxSavedContextAfterInteractionCount pxSavedCxtAfterIntCount
pxSavedContextAfterInteractionCPU pxSavedCxtAfterIntCPU
pxSavedContextAfterInteractionElapsed pxSavedCxtAfterIntElapsed

To improve access, the PegaRULES database indexes are defined for the pr_perf_stats table. You can access this table using the pxUserIdentifier, pxSnapshotTime, pxRequestorType, pxSnapShotType, or pxSystemNodeID property values STILL TRUE?

Summary View report

Run the standard summary view report Log-Usage.BrowseUsageStatistics.ALL to review the types of data in this table. (Summary view reports are limited to 10,000 records; only the first 10,000 rows in the table that meet your selection criteria appear.) You can copy this summary view report and customize your copy.

Reporting with the System Management Application

Use the System Management application to report on aggregate system usage based on Log-Usage data, as follows:

  1. Select> System > Tools > System Management App. You may be prompted for authentication credentials.
  2. The System Management application starts. Select any node; your choice does not affect the report contents.
  3. Select Logging and Tracing > Garbage Collector and Log Usage.
  4. Click a radio button to select Log Usage Statistics. Enter a Start Time as five fields, for example Jan, 23, 2006, 16 00 for 16:00 on Jan 23, 2006. SIC VERY ODD FORMAT
  5. Optionally, enter a Stop Time and Node Name to restrict the report.
  6. Click the top  VIEW   button.

Trimming the pr_perf_stats table

In a production setting, the pr_perf_stats table can grow to contain millions of rows. By default, the system automatically purges records older than 30 days. If you do not need older rows for performance analysis, debugging, or other reporting, you can purge them by date (known as trimming) without affecting other system capabilities. B-24277

Once each day, the Pega-RULES agent starts a stored procedure that purges older rows of this table, passing the value of the pxProcess property as the number of days to retain. To set a retention period longer or shorter than the 30 days, add or revise the following element to your prconfig.xml file and restart the system:

<env name="usage/retentionperiod " value="nnn" />

where nnn is the number of days to retain.

Notes

Optionally, you can disable this facility through the Dynamic System Settings data instance Pega-RULES.
usage/usagetrackingenabled
.

OldIn releases before V5.2, instances of the Log-Usage class were stored in the pr4_log_usage table. The pr4_log_usage database table is not used in Version 5.2 or later. A separate table, pr4_log_rule_usage, supports the Log-RuleUsage class.

Definitions daemon, license compliance facility, prconfig.xml file, Usage Daemon
Related topics Using the Performance tool
Working with the PegaRULES database - Log and miscellaneous tables
Standard rules Atlas — Standard classes derived from the Log- base class
UpSysAdmin category