System Management Application Reference Guide

System Management Application Reference Guide
PegaRULES Process Commander v 5.1

© Copyright 2006
Pegasystems Inc., Cambridge, MA
All rights reserved.
This document describes products and services of Pegasystems Inc. It may

contain trade secrets and proprietary information. The document and product are
protected by copyright and distributed under licenses restricting their use,
copying distribution, or transmittal in any form without prior written
authorization of Pegasystems Inc.
This document is current as of the date of publication only. Changes in the

document may be made from time to time at the discretion of Pegasystems. This
document remains the property of Pegasystems and must be returned to it upon
request. This document does not imply any commitment to offer or deliver the
products or services described.
This document may include references to Pegasystems product features that have
not been licensed by your company. If you have questions about whether a
particular capability is included in your installation, please consult your
Pegasystems service consultant.
For Pegasystems trademarks and registered trademarks, all rights reserved. Other
brand or product names are trademarks of their respective holders.
Although Pegasystems Inc. strives for accuracy in its publications, any

publication may contain inaccuracies or typographical errors. This document
could contain technical inaccuracies or typographical errors. Changes are
periodically added to the information herein. Pegasystems Inc. may make
improvements and/or changes in the information described herein at any time.
This document is the property of:

Pegasystems Inc.
101 Main Street
Cambridge, MA 02142-1590
Phone: (617) 374-9600

Fax: (617) 374-9620
www.pega.com
PegaRULES Process Commander

Document: System Management Application Reference Guide
Software Version 5.1
Updated: August 15, 2006
Contents
Introduction..........................................................................................................1
Installation............................................................................................................2
Overview..............................................................................................................2
Installing The SMA..............................................................................................4
System Configuration ...................................................................................4
Adding System Nodes ........................................................................................5
Creating a New Node ...................................................................................6
Tomcat ..........................................................................................................9
WebSphere................................................................................................ 11
WebLogic ................................................................................................... 13
SMA Security .....................................................................................................16

web.xml Security .............................................................................................. 16
mBean Security – the prmBeans.properties file ............................................. 17
Configuring the prmBeans.properties File ................................................ 18
Example prmBeans.properties File........................................................... 21
Tracking access in the PEGA log file........................................................ 23
SMA User Interface ...........................................................................................25

Agent Management ......................................................................................... 28
Configuration Management ............................................................................. 32
Listener Management ...................................................................................... 33
Requestor Management.................................................................................. 36
System Management....................................................................................... 42
PegaRULES Node Information................................................................. 43
System wide requestor status ................................................................... 43
PegaRULES Build Information.................................................................. 44
Java VM Information.................................................................................. 44
Administration................................................................................................... 45
Index Management.................................................................................... 46
Pulse Status............................................................................................... 47
Requestor Pools ........................................................................................ 49
Rule Utility Library Extractor ...................................................................... 51
System Usage History............................................................................... 52
Logging and Tracing ........................................................................................ 54
Garbage Collector and Log Usage ........................................................... 55
Log Files..................................................................................................... 65
Logging Level Settings .............................................................................. 66
Remote Logging ........................................................................................ 68
Remote Tracing ......................................................................................... 69
Advanced ......................................................................................................... 73
Introduction
For large, distributed, enterprise-level applications built in version 5.1 of PegaRULES
Process Commander, a flexible and powerful tool to monitor system operations is needed.
Process Commander includes the System Management Application, which uses Java
Management Extensions (JMX) to track the system functions. JMX is an industry-
standard, J2EE-compliant administrative interface to applications running in the JVM, and
is used to administer, monitor and otherwise manage resources that are deployed in the
application server. The JMX mBeans underlying the interface can either examine or
modify the state of applications.
The System Management Application (SMA) allows system administrators to track all the
Process Commander nodes and examine key indicators for the system across the
enterprise. This document describes the functionality of the SMA. It is assumed that
people reading this document are familiar with administration of Java systems, as well as
with the functionality and features of PegaRULES Process Commander (agents, listeners,
database, etc.).
For further information on the topics discussed in this document, please reference the
Pega Developer Network (pdn.pega.com).
CONFIDENTIAL 1
Installation
Overview
Since the main function of the SMA is to monitor the Process Commander nodes, it is not
necessarily useful to load these processes onto a node running PegaRULES. If that
PegaRULES node has a problem or goes down, it is important that the SMA not go down
with it. Therefore, the SMA should be loaded onto a separate server, or at least a
separate JVM, as it requires a separate application server container. (NOTE: For small
development or test systems, it may be useful to have the SMA installed on the same
server, to monitor the application development; however, once that system goes into
production, the SMA should be installed on a separate system.)
When installing the SMA, the developer must create an entry for each node in the
PegaRULES system which needs monitoring. It is not possible to have the system
compare information from different nodes if they do not have entries.
Important: Although the SMA will access all nodes in a particular application server, it will
not track information across different application servers. So if one instance of Process
Commander is installed in a WebSphere application server, and another instance is
installed in a WebLogic application server, the SMA will not be able to display both of
these instances in one screen. In this case, it is necessary to have the SMA installed
once for each application server. If the customer setup involves five servers running
WebSphere and five running WebLogic, two installations of the SMA will be required, one
to monitor each different application server.
2 CONFIDENTIAL
Installation
Multiple Node Configuration:
APPLICATION SERVER I
Process
Commander
Node
JMX mBean
APPLICATION SERVER for server
SMA (Server URL)
System
Management
Application
APPLICATION SERVER II
Process
Commander
Node
JMX mBean
server
(Server URL)
CONFIDENTIAL 3
Installation
Installing The SMA

The prsysmgmt.war file is included as a component of PegaRULES Process
Commander Version 5.1.
The SMA WAR file should be deployed at the same time as Process Commander.
Please reference the Process Commander 5.1 Install Guide for details on deploying the
WAR file.
System Configuration
When configuring SMA for a Process Commander system, the developer must consider
on how many nodes the Process Commander application will be running.
The recommended system configuration for installing SMA is:
For a system with one node, install both the Process Commander application and the
SMA in the same JVM, and check the Connect through local JVM box.
For a system with multiple nodes, the SMA must be installed in a separate JVM
(usually on another node) from the Process Commander application, and none of the
nodes will connect locally. All nodes will use RMI, but since the SMA is on a separate
JVM, the forced garbage collection will not affect the Process Commander application
performance.
The JMX system (on which the System Management application is built) uses Remote
Method Invocation (RMI) to communicate with each node being monitored in a Tomcat or
WebLogic system. (The WebSphere application server actually uses SOAP
communications, so this issue is not present in WebSphere installations.) Due to a known
bug in Java, explicit garbage collection is forced once per minute in any system
using RMI. If a PegaRULES node and the SMA are sharing a JVM, then the Process
Commander system will also go through a garbage collection every minute, which greatly
impacts performance for the PegaRULES system on that node.
If a PegaRULES node and the SMA are sharing a JVM, however, it is possible to connect
them locally, and avoid using RMI. Thus, a checkbox is available on the node setup
screen: Connect through local JVM. Checking this field enables the local connection
for these applications, which provides several advantages:
• local connections are faster

• the issue with forced garbage collections (and the attendant performance issues) are
1
avoided
Note that connecting locally works only in the JVM on the one node which contains both
the SMA and PegaRULES. If this is a system with several nodes, one of which
(containing both applications in one JVM) connects locally while the others are all
connecting through RMI, there will still be a problem on that first node with forced garbage
collection and performance, due to the other nodes.
1
Garbage collection still occurs with a local connection. The GC functionality determines
with reasonable accuracy when a full garbage collection is required by the system (which
should not be often).
4 CONFIDENTIAL
Installation
Adding System Nodes

To add a new Node, click on the “+” icon at the top of the screen. The Node Configuration
Details screen appears.
As stated above, it is necessary to have a separate installation of SMA for each

application server type in the system.
After installation, node entries must be added for each node using that application server
type. The node entry screen differs based on the different application servers, as
described in the following sections.
After the node has been added to the list, it is possible to edit the node information (using
the pad & pencil icon) or delete the node (using the trash can icon). Clicking on the “edit”
icon will display the current node configuration information:
CONFIDENTIAL 5
Installation
Creating a New Node

In order to create a new node, connect to the SMA installation and click the “+” to add a
new node.
The system automatically reads the Server Connection Type and fills in that field.
Depending upon the Server Connection Type, some different fields (detailed in the
following sections) will appear.
The last four fields will appear on the page for all connection types.
6 CONFIDENTIAL
Installation
If the Connect through local JVM box is checked, the system enters “NA” into fields that
are not required for a local connection, such as the Server URL. (If the connection is
local, the system doesn’t need to know where the JMX server is; it is on the server.)
CONFIDENTIAL 7
Installation
For all connection types, the last four fields should be completed as follows:
Field Name Description Example
PRPC Primary URL Optional (used for the Requestor http://prodserver:

Trace functionality). The URL which 8008/
starts Process Commander on this prweb/PRServlet
node. The developer must change
the default (example:
localhost:8080) to the appropriate
server name and port for the Process
Commander server. In addition, if
the contextroot for the Process
Commander install is not prweb, the
appropriate contextroot should also
be entered.
If this information is not present, then

the Requestor Trace feature will not
be available.
PRPC Diagnostic URL Optional (used for downloading http://prodserver:

2 8008/
reports ). The URL which starts the
Diagnostic Data servlet on the prweb/Diagnostic
Process Commander server. As with Data
the Primary URL, the developer must
change the default (example:
localhost:8080) to the appropriate
server name and port for the Process
Commander server. In addition, if
the contextroot for the Process
Commander install is not prweb, the
appropriate contextroot should also
be entered.
Authentication Whether authentication is required in

Required order to access the data on this
node. Checking this box enables
authentication.
Connect through local Whether the connection for this node

JVM is local or requires RMI. Checking
this box tells the system that the
connection is local, and that RMI is
not required.
2
If the incorrect servlet (such as PRServlet) is referenced in the Diagnostic URL field, then when a
user tries to download a .CSV file, unpredictable behavior will result (such as displaying the Process
Commander logon screen).
8 CONFIDENTIAL
Installation
Tomcat
Connect to the SMA installed for the Tomcat application server, and click the “+” to add a
new node.
In addition to the fields described in the Creating a New Node section, for a Tomcat setup,
the developer must also complete the following fields:
Node Name Required. A text name that DevArea

uniquely identifies this node in
SMA. (Each node in the system
must have a unique name.) This
name appears in the Node list,
and may be any meaningful
name the developer desires.
Some developers may wish to

have this name match the node
name of the server being
monitored. This is fine, unless
the node is running two separate
Process Commander instances,
in which case unique names for
each instance on the node must
be used.
CONFIDENTIAL 9
Installation
Server URL Required. The URL which DevArea:9091

points to the JMX server for the
node being monitored (see
Multiple Node Configuration
diagram in previous section).
This is automatically filled in with
all the JMX information needed;
the developer must change the
default (localhost:9004) to the
appropriate JMX server name
and port for the node.
NOTE: For local connections,

this field is not required.
After all the fields on the page are completed, click Submit, and the node will now be
displayed on the left side of the screen.
10 CONFIDENTIAL
Installation
WebSphere
To add a new node for WebSphere, click on the “+” icon at the top of the screen. The
Node Configuration Details screen will display. As with the Tomcat configuration, if the
Connect through local JVM box is checked, the system enters “NA” into fields that are
not required for a local connection, such as the Server URL. (If the connection is local,
the system doesn’t need to know where the server is; it is on the server.)
NOTE: Unlike Tomcat or WebLogic installations, the WebSphere setup uses a SOAP
connection to connect the SMA to Process Commander nodes, so there are no issues
with RMI. However, the local connection is still more efficient if both the SMA and the
Process Commander application are in the same JVM, as that would use a direct
connection.
CONFIDENTIAL 11
Installation
In addition to the fields described in the Creating a New Node section, for a WebSphere
setup, the developer must also complete the following fields:


be used.
Host/Server Name Required. The name of the host DevArea

server or the IP address for the
node being monitored.
Port Required. The SOAP connector 9081

port which is defined in the
WebSphere Administrative
Console. (This also displays in
the WebSphere log with the
following message: “The SOAP
connector is available at port
8880.”)
After all the above fields are completed, click Submit, and the node appears on the left
side of the screen.
12 CONFIDENTIAL
Installation
WebLogic
To add a new Node for WebLogic, click on the “+” icon at the top of the screen. The Node
Configuration Details form appears.
NOTE: There are different node configurations for different versions of WebLogic.
WebLogic 8x
In addition to the fields described in the Creating a New Node section, for a WebLogic
CONFIDENTIAL 13
Installation


be used.
Server URL Required. The hostname and t3://myserver:7001

port for the JMX server for the
node being monitored (see
Multiple Node Configuration
diagram in previous section).
This is automatically filled in with
all the JMX information needed;
the developer must change the
default (localhost:7001) to the
appropriate JMX server name
and port for the node.
NOTE: There will be other text

in this field (such as the “t3:”
string), which is required by
WebLogic. When configuring a
WebLogic node, simply
substitute the appropriate
hostname and port into this
string.
Server Name Required. The WebLogic DevArea

application server name for this
node (set up when this node is
defined in WebLogic).
14 CONFIDENTIAL
Installation
WebLogic 9x
In addition to the fields described in the Creating a New Node section, for a WebLogic
Node Name Required. A text name that uniquely identifies DevArea

this node in SMA. (Each node in the system
must have a unique name.) This name
appears in the Node list, and may be any
meaningful name the developer desires.
Some developers may wish to have this name

match the node name of the server being
monitored. This is fine, unless the node is
running two separate Process Commander
instances, in which case unique names for
each instance on the node must be used.
Server URL Required. The hostname and port for the JMX service:jmx:t3:/
server for the node being monitored (see /myserver:
Multiple Node Configuration diagram in 7001/jndi/webl
previous section). This is automatically filled in ogic.manager
with all the JMX information needed; the
developer must change the default
(localhost:7001) to the appropriate JMX
server name and port for the node.
NOTE: There will be other text in this field

(such as the “t3:” string), which is required by
WebLogic. When configuring a WebLogic
node, simply substitute the appropriate
hostname and port into this string.
CONFIDENTIAL 15
SMA Security
SMA Security
Sensitive data can be obtained through SMA, including the contents of the clipboard for a
given requestor. Due to the sensitivity of the data, it is necessary to provide an access
control mechanism for the System Management mBeans.
Unfortunately, the JMX security mechanisms differ from Web server to Web server.
Functionality exists in Tomcat to easily set up role-based access to the mBeans in the
SMA, but both Websphere and WebLogic have not finalized their security mechanisms for
individual mBeans. Therefore, Pegasystems has added additional security functions to
the SMA until the security functionality in all application servers is available to secure our
customers’ data.
web.xml Security
Users accessing the SMA must be assigned the role PegaDiagnosticUser in the Process
Commander web.xml file (found in the WEB-INF directory). If the user does not have this
role, they will be challenged for authentication when they attempt to access the SMA.
The PegaDiagnosticUser role is associated with the SMA through a security-constraint

element in the web.xml file:

<security-constraint>
<web-resource-collection>
<web-resource-name>Diagnostic Data</web-resource-name>
<description>Serves diagnostic files generated by the JMX client
</description>
<url-pattern>/DiagnosticData</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>PegaDiagnosticUser</role-name>
</auth-constraint>
</security-constraint>
If the developer does not want to restrict access to the SMA, remove this resource
restriction through one of the two methods listed below:
• Edit the PegaRULES web.xml file (in the WEB-INF directory of the prweb
deployment in your application server) and delete this security-constraint element.
NOTE: Changing this setting in the web.xml file may require redeployment of the
PegaRULES web application.
16 CONFIDENTIAL
SMA Security
• Certain application servers (such as IBM WebSphere) allow roles to be mapped

to all users, including unauthenticated users. If your application server supports
this, and this is the desired configuration, map the PegaDiagnosticUser role to all
users. Consult your application server’s documentation to see if this is an option
for your environment.
mBean Security – the prmBeans.properties file

The security solution implemented in Process Commander v5.1 uses a Java properties file
to deny access to one or more mBeans, mBean operations, or mBean attributes. This
property file, named prmBeans.properties, is a top-level configuration file similar to
prconfig.xml or prlogging.xml, and is found in a similar location in the deployment (e.g.,
WEB-INF/classes).
The prmBeans.properties file describes a negative security policy, meaning that it only
contains information on those actions that are explicitly denied. All other operations are
assumed to be allowed.
NOTE: Although the security solution uses a “.properties” file, this is not a J2SE security
policy, but simply a way to provide additional security for the mBeans.
Important: This security functionality is not meant to prevent developers from using the
application server security, but to supplement it. If the application provides powerful and
easy-to-use security features, that should certainly be used. Pegasystems provides
additional security functionality to ensure that there is a universal method of securing
mBean access across all web servers.
Upon startup, the settings in prmBeans.properties are read into memory. Each time that
an mBean attribute or operation is accessed by the SMA, the security settings in memory
for that mBean are checked; access is either allowed or denied to all users. (This feature
does not provide role-based security; once access is denied for an mBean, it is denied to
everyone.) If access is denied, an error message is sent back to the caller.
Access to the mBean operation/attribute

RequestorManagement.RequestorDetails[java.lang.String] has
been denied. If you believe that you should have access to
this operation or attribute, please check your mBean
security settings or contact your system Administrator.
NOTE: The prmBeans.properties settings are only read upon startup of the application. If
a security setting needs to be changed in this file, the change must be made to the file,
and then the application must be undeployed and redeployed (just like a change to the
prconfig.xml file) in order for that change to be referenced.
CONFIDENTIAL 17
SMA Security
Developers who are directly accessing the mBeans through their own custom code will
see the following error:
<?xml version="1.0" encoding="UTF-8"?>

<FatalError>
<PRmBeanError>Access to the mBean operation/attribute
RequestorManagement.Clipboard[java.lang.String] has been
denied. If you believe that you should have access to this
operation or attribute, please check your mBean security
settings or contact your system Administrator.</PRmBeanError>
</FatalError>
Configuring the prmBeans.properties File

The mBean security access may be denied at four levels:
• No access
• mBean level
• mBean Attribute level
• mBean Operation level
Denying access in prmBeans.properties will have different consequences, depending

upon the level of access denied:
1. If all mBeans are denied, then no mBeans get registered with the JMX server.
2 If an mBean is denied at the name level, then that mBean is not registered with the JMX
server. (All non-specified mBeans will still be registered with the JMX server.)
18 CONFIDENTIAL
SMA Security
3. If an mBean is only partially restricted, or even if it all operations/attributes are

specifically denied (but the mBean itself is not denied by name), then it is registered with
the JMX server, but access to the restricted values will be denied. This means that
although a remote user can see that restricted properties exist, they cannot access their
value, either programmatically, or through the SMA user interface.
No Access
If access to all mBeans is denied, then no mBeans get registered with the JMX server,
and all other settings in the file are ignored.
Syntax:
deny = true
Example entry in prmBeans.properties file:
deny = true
mBean Level Access
If access to a particular mBean is denied, then that mBean will not be registered in the
JMX server. This option will not be displayed as a feature in the SMA (list of links on the
left side of the screen), and all other settings for this mBean are ignored.
Syntax:
deny.mBeanName = true
deny.RemoteTracing = true
For a list of all the available mBeans in the SMA, please reference the Working With JMX
mBeans section later in this document.
mBean Attribute Level Access
If access to an mBean attribute is denied, then an error message is returned by the JMX
server if someone tries to access that feature.
Each mBean in the system contains the following attributes:
• Name
• Major Version
• Minor Version
• Category
CONFIDENTIAL 19
SMA Security
Syntax:
deny.mBeanName.AttributeName = true
deny.RequestorManagement.Name = true
mBean Operation Level Access
If access to an mBean operation is denied, then an error message is returned by the JMX
server if someone tries to access that feature. All other settings for that operation are
ignored.
Note that if the mBean has multiple operations with the same name, but different
signatures, then this entry in the prmBeans.properties will deny access to all of them.
Syntax:
deny.mBeanName.OperationName = true
deny.RequestorManagement.Clipboard = true
For a list of all the available operations for each mBean in the SMA, see the Working With
JMX mBeans section later in this document.
mBean Operation Signature Level Access
If access to an mBean with the given operation of the given signature is denied, then an
error is returned by the JMX server if someone tries to access that feature. All other
settings for the given operation are ignored.
NOTE: There should be no spaces between the types in the method signature list, only
commas. If spaces are present, the security rule will not match.
Syntax:
deny.mBeanName.OperationName[OperationSignature,…] = true
deny.HeapProfiling.Analyze[java.lang.String,java.lang.String] =
true
20 CONFIDENTIAL
SMA Security
Example prmBeans.properties File
The following is the default prmBeans.properties file shipped with the SMA:
#Default mBean security configuration.

deny.DatabaseManagement.DatabaseConnectionDetails = true
deny.RequestorManagement.RequestorDetails = true
deny.RequestorManagement.Clipboard = true
By default, access is denied to the following features in SMA:
Link Access Denied Security Risk
Advanced – Database Choose one of the Active Databases

Database Connection and click on the Database Details
Management Details button button. The system will display the
Managed Connections to that database
(i.e., the requestors which are running).
Choosing one of those requestors and
clicking on the Database Connection
Details button will display all the
commands recently executed by that
requestor, including specific database
information.
Requestor Details button Choosing a requestor and clicking this

Management (see Details section button will display a trace entry with
under Requestor details of the requests sent by this
Management for requestor, including specific database
more information) information.
Requestor Clipboard button Choosing a requestor and clicking this

Management (see Clipboard button will display the clipboard for that
section under requestor, with all the data available for
Requestor that clipboard.
Mangement for
details)
If this file is left in the default state, then during startup, the following messages are written
to the PEGA log:
Located App Server independent MBean security configuration:

file:/D:/programs/tomcat5.5/webapps/prweb0501/WEB-
INF/classes/prmbeans.properties
13:58:45,807 [ wabcdexp] (
priv.management.MBeanSecurity) INFO - The following MBean
security configuration has been applied:
deny.RequestorManagement.Clipboard=true
deny.RequestorManagement.RequestorDetails=true
deny.DatabaseManagement.DatabaseConnectionDetails=true
CONFIDENTIAL 21
SMA Security
10:53:27,639 [ wabcdexp]
(riv.management.mBeanManagement) INFO - mBean Management (Web)
initialized for DefaultDomain
If the system could not locate the prmBeans.properties file (it is missing or named
incorrectly), then no security is applied to the SMA, and all operations are allowed by
default. The following messages will be written to the PEGA log:
Unable to locate App Server independent mBean security

configuration after trying:
<properties>
abcde-prmBeans.properties
wabcdexp-prmBeans.properties
prmBeans.properties
11:36:08,264 [ wabcdexp] (
priv.management.mBeanSecurity) WARN - mBean security
configuration has not been defined. All mBean operations will be
allowed.
11:36:08,702 [ wabcdexp]
If the default prmBeans.properties file has been changed, and an entire mBean has been
disabled, messages such as the following will appear at startup:
Located App Server independent mBean security configuration:

file:/D:/programs/tomcat5.5/webapps/prweb0501/WEB-
INF/classes/prmbeans.properties
11:37:48,046 [ wabcdexp] (
priv.management.mBeanSecurity) INFO - The following mBean
deny.RequestorManagement=true
11:37:48,327 [ wabcdexp]
(riv.management.mBeanManagement) INFO - The mBean
com.pega.pegarules.management.RequestorManagement has not been
registered due to the mBean security configuration.
11:37:48,405 [ wabcdexp]
If the default prmBeans.properties file has been changed, and all mBeans have been
disabled, messages similar to the following will appear at startup:
11:38:44,358 [ wabcdexp] (
priv.management.mBeanSecurity) INFO - The following mBean
deny.RequestorManagement=true
22 CONFIDENTIAL
SMA Security
deny=true
11:38:44,593 [ wabcdexp]
com.pega.pegarules.priv.management.web.ServletManagement has not
been registered due to the mBean security configuration.
11:38:44,593 [ wabcdexp]
com.pega.pegarules.management.HeapProfiling has not been
11:38:44,593 [ wabcdexp]
com.pega.pegarules.management.DatabaseTableInfo has not been
11:38:44,593 [ wabcdexp]
com.pega.pegarules.management.LogFileAccess has not been
11:38:44,593 [ wabcdexp]
com.pega.pegarules.management.ListenerManagement has not been
11:38:44,593 [ wabcdexp]
com.pega.pegarules.priv.management.web.WebTierRuntimeEnvironment
has not been registered due to the mBean security configuration.
11:38:44,593 [ wabcdexp]
com.pega.pegarules.management.ClassLoaderManagement has not been
Tracking access in the PEGA log file

The messages described in the preceding section are written by default to the PEGA log
file. To have additional information on access to the SMA mBeans written to this log file,
set the logging level for the class
com.pega.pegarules.priv.management.mBeanSecurity to INFO (see the
Administrative & Security Guide for details on enabling logging levels). In this case, a
message is written to the PEGA log every time someone tries to use the SMA.
Example PEGA log entries:
11:28:32,561 [tion(70)-10.60.51.54] (
priv.management.mBeanSecurity) INFO - GRANTED access to mBean
Operation. Relevant rule:
deny.RequestorManagement.RequestorList[]
11:28:37,624 [tion(70)-10.60.51.54] (
priv.management.mBeanSecurity) INFO - DENIED access to mBean
RequestorManagement. Relevant rule:
deny.RequestorManagement.Clipboard
The “relevant rule” refers to entries in the prmBeans.properties file. When access is
granted, the log file contains a message stating that the listed configuration setting was not
found in the properties file. When access is denied, the log message references the
configuration setting which denied access to the requested feature.
CONFIDENTIAL 23
SMA Security
Developers may not want to have this level of detail continually recorded in the PEGA log.
It may be most useful for the system administrator to enable this INFO logging while they
are configuring and testing the security of the SMA; once the security is approved, the
logging may be disabled.
24 CONFIDENTIAL
SMA User Interface
SMA User Interface

Process Commander provides a ready-made user interface to the mBeans in the System
Management Application.
When the System Management application is first opened, the left side of the screen lists
all nodes which have been entered into the application. After one node has been chosen,
that node name will appear on the left side of the screen in the highlighted box under the
node list, with all the System Management choices beneath. (The System Management
page displays automatically when the node is chosen.)
To change the node, click on another node name; the highlighted node name and all the
node data changes to reflect the new node.
CONFIDENTIAL 25
SMA User Interface
Click on the “home” icon in the upper left corner to display system information about all
nodes. (This gives the system administrator a “snapshot” of the entire system.)
Column Description
Heading
Node Name The name of a node in the system.
System Name The name of the server on which the Process Commander node
is running (there may be several instances of Process
Commander on one server).
Total Memory The current size of the JVM. This can show whether memory for
one (or more) nodes of the system is overallocated.
# Requestors The number of requestors currently in memory for this node. This
can indicate load-balancing issues across the system – if one
node has a much higher number of requestors than other nodes,
and is doing more of the work, users on that node may experience
performance slowdowns.
# Agents The number of agents defined for this node.
# Listeners The number of listeners defined on this node.
Version The PegaRULES Process Commander version being run on the

node.
26 CONFIDENTIAL
SMA User Interface
Click on the “refresh” icon at the top left of the main (large) part of the screen to refresh the
page display with the most recent information for the chosen link.
CONFIDENTIAL 27
SMA User Interface
Agent Management
The Agent Management option contains information about all agents that are running on
the specified node. Note that when an agent is active, it may also be viewed as a
requestor (beginning with “B”) in the Requestor Management screen.
Click the Agent Management link to display this page.
28 CONFIDENTIAL
SMA User Interface
The General Information section displays the current values for the agent configuration
settings in the prconfig.xml file.
Setting Example prconfig.xml entry

Value
Minimum allowed wakeup time for all 30000 minimumwakeup

agents
Wakeup interval for requestor- 60000 requestortimeoutwakeup

timeout (master agent)
Wakeup interval for new agent 600000 newqueuewakeup

processing (master agent)
Initial startup delay for master agents 60000 masterdelay
Java thread pool size 5 threadpoolsize
(For full details on these and other prconfig.xml settings, see the prconfig.xml File Setting
Reference Guide.)
The main part of the page displays a report on all agents which are running or have run in
the system.
Column Heading Example Values Description
Enabled? “True” or “False” Shows whether the agent is

running (“true”) or not (“false”).
There are three ways to disable an
agent:
• by clicking the Stop Queue
button (see below)
• by encountering an exception
(see last column)
• by disabling the Data-Agent-
Queue instance
RuleSet RuleSet Name The name of the agent’s RuleSet
# 1 The index number of the Agent

Activity entry as listed in the Rule-
Agent-Queue (starts with the
number 0).
Description Short Description The description of the agent

(includes Agent Activity
Class and Name)
CONFIDENTIAL 29
SMA User Interface
Column Heading Example Values Description
Scheduling “every 18000 ms” Depending upon the type of agent,

this setting displays one of the
“daily, weekdays only” following:
• the current wakeup interval
for the agent, in milliseconds
(periodic type)
• the description of what
settings were chosen for the
next time the Agent Activity
will run (recurring type)
Last run start date from node system: The start time of the last run for this
May 2, 2006 3:14:04 Agent Activity.
PM EDT
Last run finish date from node system: The last time this Agent Activity
May 2, 2006 3:14:04 finished processing.
PM EDT
Next run time date from node system: The next time this Agent Activity is
May 2, 2006 3:14:04 scheduled to run.
PM EDT
# of memory integer Counter displaying how many

errors times the Agent Activity was
restarted due to a Java
OutOfMemoryError exception.
Exception Any exception information that was

information generated when the Agent Activity
is disabled due to an error.
A series of buttons is displayed across the top of the screen, in three groupings.
Single activity in queue
Button Description
Start Starts an agent activity.
Stop Stops an agent activity that is currently running; sets the

Enabled column to false, and prints an exception in the
Exception Info column
Restart Stops an agent activity and then restarts it.
isAlive Shows whether the specified agent activity is enabled.
Query Displays information on the chosen agent activity.
30 CONFIDENTIAL
SMA User Interface
Button Description
Delay Delays the next start of this activity for the Tracer startup. If a
developer wants to trace the execution of an Agent Activity, it
can go by too fast to enable the Tracer. This button will cause
the Agent Activity status to be set to waiting; once the Tracer is
enabled, the Start button may be pressed for that Activity, to
start its execution.
For example, when a particular agent is chosen and the isAlive button is clicked, the
following data is displayed:
All activities in queue
Button Description
Start Starts all agent activities in a particular queue or RuleSet.
Stop Stops all agent activities (in a particular queue or RuleSet) that
are currently running; for each activity in the RuleSet, sets the
Enabled column to false, and prints an exception in the
Exception Info column
Restart Stops and then restarts all agent activities in a particular queue
or RuleSet.
isAlive Shows whether all agent activities in a particular queue or

RuleSet are enabled.
Query Displays information on all agent activities in a particular queue

or RuleSet.
For example, when any of the Pega-IntSvcs agents are chosen, and the Query button is
clicked, the following data is displayed:
CONFIDENTIAL 31
SMA User Interface
Other - Query RuleSets
Click this button to list all the RuleSets for each agent activity. Scanning this list is a quick
way to see whether there is a problem with agents from a particular RuleSet - if there are
no agents from one RuleSet, there may have been an issue with that Rule.
Configuration Management
The Configuration Management option displays the current settings in the prconfig.xml
file for the current node chosen.
(For full details on these file settings, please reference the prconfig.xml File Settings
Reference Guide.)
IMPORTANT: Unless the system is set up to encrypt the database password, that
password will be visible in this display. If the system is not using a data source, be
sure to encrypt your password for safety!
32 CONFIDENTIAL
SMA User Interface
Listener Management
The Listener Management option displays information about all listeners that are running
on the specified node.
The Available Listeners box displays a dropdown list of all the listeners that are defined
in Process Commander.
The main part of the screen displays a report on all listeners that are running or have run
in the system.
Column Description
Heading
Listener ID A unique character string which is assigned by the Listener

management. The Listener ID doesn’t exist until the listener is
started.
Status The state of the listener:

• running
• sleeping (waiting to run)
• disabled
Listener Class The name of the Process Commander class that defines this
listener (example: Data-Admin-Connect-EmailListener).
Listener Java The name of the Process Commander Java class that
Class implements the listener. All class names begin with
com.pega.pegarules.services; the classes include:
• EmailListener
• file.FileListener
• JMSListener
• MQListener
CONFIDENTIAL 33
SMA User Interface
Column Description
Heading
Listener Name The name of the rule instance (example: “CustomerJMS”). For
Email and MQ listeners, this name is a concatenation of the two
key fields for the rule instance: the Server Name and the
Listener Name (“DevServerCustomerEmail”).
Time Started The date/timestamp showing when this listener was started.
Last Access The last time the listener came out of “sleep” mode and tried to
process a request.
Request Count The number of requests this listener has processed.
Last Request The last time there was a request made to the listener (i.e.,
there was something to be processed).
Error Count The number of errors which have occurred in requests for this
listener
Last Error The timestamp of the last error
A series of buttons is displayed across the top of the screen, in sections:
Available
The Start button starts the selected listener. Unlike the buttons in the next section, which
refer to the listeners displayed in the Running Listeners section, to use the Start Button, it
is necessary to select a listener from the Available Listeners drop-down list. Then, clicking
on Start will start that listener, which will then appear in the Running Listeners section.
NOTE: It may be necessary to refresh the screen (using the Refresh icon) for the Listener
to appear in the list.
Running
These buttons will display information for a chosen listener in the Running Listeners
section.
Button Description
isAlive Shows whether the specified listener is enabled.
Query Displays information about the chosen listener.
Listener Rule Data provided about this listener from the Data-Admin-
Data Connect- instance.
Restart Stops and then restarts the specified listener.
Stop Stops a listener which is currently running and removes the

listing from the Running Listeners display.
34 CONFIDENTIAL
SMA User Interface
By Type Running
These buttons affect all listeners of the type chosen in the Running Listeners section.
Listener types include:
• Email
• File
• JMS
• MQ
Button Description
RestartType Stops and then restarts all listeners of the specified type.
StopType Stops all listeners of the specified type.
All Running
These buttons affect all listeners in the Running Listeners section. NOTE: It is not
necessary to choose one specific listener before clicking these buttons.
Button Description
RestartAll Restarts all listeners on this node.
StopAll Stops all listeners on this node.
CONFIDENTIAL 35
SMA User Interface
Requestor Management
The Requestor Management option displays information about any of the requestors
(users) running on the system.
The Requestor Status report contains the following information for each requestor:
Column Description
Heading
Name The “name” (hash name) of the requestor.

• If the name begins with “H”, this requestor is being used
by a user (HTTP interaction)
• If the name begins with “A”, this requestor is being used
by a listener or service rule
• If the name begins with “B” this is a batch requestor (used
by agent processing)
• If the name begins with “P”, this requestor is used for
portlet support.
User Name The userID associated with that requestor. “None” signifies
that this requestor is being used by an agent or other process,
or that the user is not currently logged in.
36 CONFIDENTIAL
SMA User Interface
Column Description
Heading
Client Address The IP address of the machine sending the requestor

information.
Last Access The date/timestamp of the last time the requestor performed
an operation
Last Input The last activity or stream that was executed
Traced Whether Tracer is enabled or not.
Java Thread If the requestor is operating in the context of a Java thread

when this report is displayed, that thread is displayed.
NOTE: For an application running on WebSphere, the SMA runs on a SOAP connector;
therefore, there will be at least one SOAP connection visible.
There are a number of different buttons for Requestor Management:
• Clipboard
• Performance Details
• Details
• Interrupt
• Stop
• Tracer
Before pressing any of these buttons, select the requestor for which information is desired.
CONFIDENTIAL 37
SMA User Interface
Clicking on the Clipboard button displays the data on the clipboard for the chosen
requestor.
38 CONFIDENTIAL
SMA User Interface
Choosing Performance Details displays the PAL statistics for this requestor.
CONFIDENTIAL 39
SMA User Interface
Clicking on the Details button displays a Trace Entry screen at the bottom of the window,
showing trace lines for the operations that have been performed by the requestor. This is
a snapshot of the information, and does not update in real time.
The Interrupt button attempts to stop the processing of the chosen requestor at the
beginning of the next activity step. (NOTE: If the requestor is having an issue, such as
executing a Java block which is in a loop, this may not be able to be interrupted.)
The Stop button deletes the requestor. It is removed from the Requestor Status display
and deleted from the system.
40 CONFIDENTIAL
SMA User Interface
Clicking the Tracer button starts the Tracer tool for the chosen requestor. This screen will
update in (almost) real-time, as more operations are performed by the requestor.
CONFIDENTIAL 41
SMA User Interface
System Management
The System Management option shows key technical environmental information about
various aspects of the system. When calling Pega Support about an issue, it is important
to have this information available for the Support Engineer, so they have exact details on
the system.
42 CONFIDENTIAL
SMA User Interface
PegaRULES Node Information
Variable Description
System Name The name of the current node.
System Start Time The date and time that this node was started.
Total Memory The maximum heap size being used by Java when this
report was run.
Total Free Memory Within the total memory, the amount not being used by
Java at this time.
Number Requestors The number of requestors currently in memory on this

node.
Number Active The number of active Java threads for this node.
Threads
Number Agents The number of all agents defined for this node, not just the
agents currently running.
Number Listeners The number of all listeners defined for this node, not just
the listeners currently running.
Number Database The number of database connections currently open for

Connections this node.
Pulse Last Run The date/timestamp for the last time the system pulse ran
on this node.
System wide requestor status
This section of the page tracks how many of each type of requestor have been created in
the node since the node was started. The requestor types include:
• Portlet Initiated
• Browser Initiated
• Batch Initiated
• Service Initiated
CONFIDENTIAL 43
SMA User Interface
PegaRULES Build Information
This section contains information about the Process Commander system installed on this
node.
Variable Description
Name The name of the build, including any service packs.
Date The date and time when the version was built.
Major Version The major point release version of the rules code that was
installed (“05” for Version 5.1)
Minor Version The minor point release version of the rules code that was
installed (“01” or “02”)
Build Label The label that was defined for this build (“SmartBuild”)
Java VM Information
This information is a subset of the information which is available using the getProperties
method on the System Properties from the Java Virtual Machine. (See
http://java.sun.com/j2se/1.4.2/docs/api/java/lang/System.html#getProperties() for
information.)
Key Description of Associated Value
java.version Java Runtime Environment version
java.vendor Java Runtime Environment vendor
java.home Java installation directory
java.vm.version Java Virtual Machine implementation version
java.vm.vendor Java Virtual Machine implementation vendor
java.vm.name Java Virtual Machine implementation name
java.compiler Name of JIT compiler to use
os.name Operating system name
os.arch Operating system architecture
os.version Operating system version
44 CONFIDENTIAL
SMA User Interface
Administration
The Administration option gives access to the following features which aid in the
administration of the system:
• Index Management
• Pulse Status
• Requestor Pools
• Rule Utility Library Extractor
• System Usage History
CONFIDENTIAL 45
SMA User Interface
Index Management
In order to make finding specific rules easier in Process Commander, a full-text search has
been implemented, based on the Apache Lucene open source indexing software. To
enable this search capability on a PegaRULES system, an initial full index build must be
performed on each node of the PegaRULES system. Use the Index Management page to
build the index.
There are four buttons in this section. The build index buttons correspond to the different
types of searches that are available through the drop-down in the Find Rules box (in
Process Commander.)
Button Description
Build PegaRULES Creates the initial build of the index for Rule- instances
Index
Build Work Index Creates the initial build of the index for Work- instances
Build Data Index Creates the initial build of the index for Data- instances
Optimize The Lucene indexing may create several .cfs files for the index.
PegaRULES Index In order to collapse these several files into one file (which can
produce a more efficient Search), the Optimize PegaRULES
Index button may be used.
CAUTION: Using this function takes a long time, and

consumes all the CPU in the system. The feature will use
up to 100% of the CPU for perhaps 20 minutes, preventing
users from using the system, so do not use this button unless
so many files have been created by Lucene that the system is
running out of file handles. (NOTE: This should happen
rarely, if ever.)
Important: The System Administrator must click each button in order to build the
index, before searches on that item (rules, work objects, or data) will return results.
If any user tries to use the search before the index is built, an error will be displayed stating
that the index is not available, and to please contact the System Administrator.
The index build for each item type will take approximately 20 minutes or more; the time
required is proportional to the number of instances. (Thus, if a customer has many
thousands of rules, their index build will take longer than a customer who only uses one or
two thousand rules.) If this is a multi-node system, access the Index Manager for each
node, and build the index for that node.
46 CONFIDENTIAL
SMA User Interface
Pulse Status
When PegaRULES is installed on a multi-node system, then a copy of the various caches
are stored on each node, and each of those nodes must be updated with rule changes.
This update process is managed by the System Pulse functionality.
Saving a rule change (update, add, or delete) to one of the Rule tables in the database will
fire a PegaRULES database trigger, which will then register the change in the
pr_sys_updatescache table (in the same database). Each node records all their
changes in this table; the types of event which are saved to this table include:
• Cache – for any changes to the rule cache (changes to the rules)
• Index – for changes to the Lucene indexes that support full-text search
• DELLC – when the lookuplist cache is deleted
• RFDEL – for any rule-file- deletes
Saving a rule change will also automatically invalidate the appropriate information in the
caches on that node; however, all the other nodes in the system now have out-of-date
information about that rule.
Once per minute, the pulse (which is part of the standard PegaRULES agent) on each
node wakes up (independently) and queries the pr_sys_updatescache table. The query
retrieves records which are “not from this node” (which this node did not create), and
which have a timestamp which falls within the window of time starting with the last pulse
(or system startup) and now. In this way, all of the changes originating on other nodes are
selected, and the appropriate cache entries on this node are invalidated. The next time
one of the rules which has been invalidated is called, it will not be found in the cache, and
the updated version of the rule will be read out of the database and be eligible for caching
again.
The Pulse Status page displays information about the system pulse, which posts
changes made throughout the system to each node. It is vital to make sure that there are
no issues with the system pulse, as otherwise, users on different nodes may be seeing
“stale” data.
CONFIDENTIAL 47
SMA User Interface
Column Heading Description
Node Name Displays the node where each change that the System Pulse
is tracking originated. The names listed are unique identifiers
for each node (pxProcess.pxNodeUniqueID).
Cache Type The type of event which the system pulse needs to publish to
the system nodes. The types include:
• Cache – for any changes to the rule cache (changes to
the rules)
• Index – for changes to the Lucene indexes that support
full-text search
• DELLC – when the lookuplist cache is deleted
• RFDEL – for any rule-file- deletes
• ECHO – tells all nodes on the system to print a message
to the console.
Create Date/Time The date/timestamp when each change was recorded
Obj Class The class of the rule being changed (may not be set for all
cache types, such as ECHO)
Key String The “key string” (pzInsKey) for the rule instance being changed
(for some cache types, may be blank)
48 CONFIDENTIAL
SMA User Interface
Column Heading Description
Parameters Other data for the change which may apply for certain cache
types
Requestor Pools
In Process Commander, any unauthenticated stateless service will use a requestor pool.
This is a collection of requestors which may be used for the requests for this service. The
Pooling tab on each Data-Admin-ServicePackage instance specifies requestor
information.
CONFIDENTIAL 49
SMA User Interface
The Requestor Pools link displays information about the existing requestor pools.
Click Clear Requestor Pool button to remove the specified requestor pool from the
system.
Column Description
Heading
ServicePackage The name of the Data-Admin-ServicePackage instance

(example: “JSR94Administration”).
AccessGroup The Service Access Group specified on the Context tab of the
Data-Admin-ServicePackage instance.
LastAccess The date/timestamp of the last time a requestor was taken from
the pool for this ServicePackage.
Idle The number of requestors in the pool which are available and
waiting to be used.
Active The number of requestors which are currently being used.
MostIdle For the life of the requestor pool, the largest number of
requestors that were idle.
MostActive For the life of the requestor pool, the largest number of
requestors that were used at one time.
MaxIdle The maximum number of idle requestors which may be in the

pool for this Service Requestor.
MaxActive The maximum number of concurrent requestors which may be

created and in use for the services in this package.
MaxWait The maximum time that Process Commander will wait for a
requestor to be returned to the pool when a service request
arrives, but the number of active requestors has reached the
Maximum Active Requestors value.
50 CONFIDENTIAL
SMA User Interface
Column Description
Heading
LongestWait The longest amount of time that the system had to wait for a
requestor to be available.
Timeouts The number of times the system timed out while waiting for a
requestor to be available.
Rule Utility Library Extractor

When creating activities in PegaRULES, there may be functionality written for one activity
that could be used across many activities, such as mathematical, time, or date functions.
These functions are stored in the class Rule-Utility-Function. Rule-Utility-Function is the
mechanism provided in PegaRULES to allow custom Java code to be included and be
referenceable from activities and expressions throughout the system.
These functions are then grouped into java classes, according to the Rule-Utility-Library in
which each Rule-Utility-Function is defined. The libraries are extracted during the startup
of the PegaRULES system, so the functions are available to users.
During some other processes, such as importing, the contents of the libraries are not
checked; if the import brings in new Rule-Utility-Functions, these may not be implemented,
as the library has no information about them. Therefore, for processes such as imports, it
is important to regenerate (or recompile) all the libraries
The Rule-Utility-Library extractor extracts either one or all of the Rule-Utility-Libraries in

the node to the file system.
1. Enter a valid RuleSet in the Rule Set field, and a valid Library for that RuleSet in the
Library Name field.
2. Click the Extract Libraries button. After the library had successfully been extracted, a
“success” message appears at the bottom of the screen:
CONFIDENTIAL 51
SMA User Interface
If either the RuleSet or the Library Name are incorrect, the Status bar is red, and reports
the message “Failed to extract Rule-Utility-Library.”
System Usage History

The System Usage History option displays a report summarizing Process Commander
monthly system usage over the last 13 months. (The last column contains data for the
current month, which will display month-to-date data.) This report may be used by
customers to verify license agreement compliance.
Example display:
Important: For DB2 Databases Only, in Version 5.1 Only

For DB2 databases, when the DBA creates a Database, a default temporary
tablespace and its bufferpool are created using the default page size (normally 4K) as
part of the Database create process. In order to run the Pega System Usage
History report in DB2 in Version 5.1, a temporary tablespace and its associated
bufferpool must be created for the PegaRULES database with a 32K page size.
(This may take some tuning by the DBA. Start with the ability to hold 100 pages at
32K each – 3200K, or 3MB of space in the buffer. If the System Usage History report
takes forever to come up, the buffer may need to be increased. If it appears
immediately, the buffer size may be able to be decreased, to use less system
memory.)
If the temp tablespace is not changed to use a 32K page size, then a
PRRuntimeException will display instead of the System Usage History report.
The report differentiates between Named Users and Invocations.
Named users are people who use a Process Commander application on a regular basis
for their work (a call center, a health insurer, a bank, etc.). Each of these users will have a
unique Operator ID (Data-Admin-Operator-ID instance), and they create and process
some form of work item.
52 CONFIDENTIAL
SMA User Interface
Invocations, on the other hand, measure “users” who invoke the system through one ID
or through an external system. One example might be another customer system, which
uses the PegaRULES engine to do BRE processing (run activities, look up information);
another example might be a company that sets up an application where users would use it
infrequently and irregularly (such as a company suggestion box), where all the accesses
would be through one ID.
The System Usage report then takes these two groupings and breaks them down further:
Report Category Description
Regular Named 3
Named users actively logged in (not passivated ) for four
Users hours or more during any day of the month.
A named user is included in this count if they were logged in

for four or more hours on any one day (or more) during the
month. The four hours does not have to be sequential; the
user could log in for two hours in the morning and two hours in
the evening, and would still be included in the count.
In addition, a named user is included in this count if they have

“allow rule check out” checked in their Operator ID record, and
logged in at least once during the month. These named users
will be included in the count no matter how many hours they
have spent working in the system.
Occasional Named Named users actively logged in (not passivated) for less than
Users four hours during any day of the month.
BPM Invocations A count of invocations where a Flow rule is executed.
Rule Invocations A count of invocations where no Flow rule is executed.
Users in Peak Hour The maximum number of concurrent users during the month.
This count shows the maximum number of users who were

signed on during any one-hour period in the month. The one-
hour period is measured by “clock time” – i.e., from 2:00 to
3:00. The users do not all have to be concurrent – if one user
were signed on at 1:30, and signed off at 2:30, and another
user signed on at 2:45, and signed off at 3:15, they would
both be counted for the 2:00 – 3:00 hour timeframe.
3
Passivation is the act of writing a user instance to the database when the requestor
times out. The data is stored on disk so memory is freed for other users, and restored to
the requestor session once the user has re-authenticated. The System Usage report does
not count the time the user’s requestor is passivated.
CONFIDENTIAL 53
SMA User Interface
Logging and Tracing

This section of the SMA displays information about some of the underlying PegaRULES
functionality, including features such as:
• Garbage Collector and Log Usage

• Log Files
• Logging Level Settings
• Remote Logging
• Remote Tracing
54 CONFIDENTIAL
SMA User Interface
Garbage Collector and Log Usage

This page presents a detailed view of how the system is handling garbage collection,
comparing it to system usage.
When a developer is troubleshooting an issue, sometimes they can determine a very

specific issue and can go directly to that part of the program. On other occasions, the
symptoms are more general (“the system is slow”); in those cases, start with this page to
get some pointers on how the system is behaving overall.
Garbage collection is a key function to check when troubleshooting performance. The

time the system spends collecting garbage is essentially all CPU processing time; thus,
the system can suspend all user processing while running the garbage collection process.
This means that garbage collection can have a massive effect on performance.
Key Concepts for Garbage Collection
There are two ways that garbage collection can be done:
• concurrently (with other processing)

• superceding all other processing (“stop-the-world”)
“Stop-the-world” garbage collection is the most efficient, and is shipped as the default in
most JVMs.
For Sun JVMs, there are two sections of memory:
• Major – for objects which have a long lifetime (“tenured” or “permanent” objects)
• Minor – for objects which have a short lifetime (“new” objects)
IBM doesn’t differentiate between objects for garbage collection – they only have “tenured”
objects. For IBM JVMs, all the garbage collection is “major.”
When doing garbage collections, a minor garbage collection happens frequently, and is
fast and not expensive in terms of system resources. A major (or “full”) garbage collection,
on the other hand, takes more time and is very expensive.
(For more information, please reference the Sun and IBM websites:
http://www-128.ibm.com/developerworks/java/jdk/docs.html
http://java-virtual-machine.net/sun-java-virtual-machine.html)
CONFIDENTIAL 55
SMA User Interface
There are three buttons on this screen:
Button Description
View View the requested data on the page.
Collect Force an explicit garbage collection.
NOTES:
• This button is provided for debugging purposes only –

generally it is recommended to allow the JVM to perform
the garbage collection on its own.
• As this button applies to garbage collection, it is grayed out

when Log Usage Statistics is chosen.
CSV Create a comma-delimited report of the requested data for

download.
56 CONFIDENTIAL
SMA User Interface
Garbage Collector Statistics
This view uses the logfile that is generated by the VerboseGC JVM parameter, and
organizes the GC data (broken out for each hour) in order to give a picture of the garbage
collection activity over time.
NOTE: Verbose GC output must be enabled in the JVM in order to use this feature.
GC Log File: Enter the full path to the garbage collection log output file, including the log
file name.
If the location of the log file is included in the JVM options specified when starting the
application server, then this field will default to that log file path. Recommended garbage
collection switches include:
-XX:+PrintGCTimeStamps –XX:+PrintGCDetails –Xloggc:pathToLog –

verbose:gc
Example:
-XX:+PrintGCTimeStamps –XX:+PrintGCDetails –
Xloggc:d:\pr_temp\gc.log
–verbose:gc
The JVM Start Time displays the start time for the system JVM.
Start Time and Stop Time will display the start and stop time parameters for displaying
the recorded garbage collection data. Change these times to display the garbage
collection information for a particular time and day to investigate.
To view the statistics:
1. Click the radio button next to the Garbage Collector Statistics section.
2. In the GC Log File field, enter the path to the log file, including the file name.
Example: f:\websphere\tempdir\logs\gclog.out
3. Set the Start and Stop times.
4. Click View to view the report on the screen, or CSV to create a CSV file to download
the report to a local machine.
NOTE: The garbage collection statistics all apply to one JVM (one node) in the Process
Commander system.
CONFIDENTIAL 57
SMA User Interface
GC Statistic Description
JVMStartTime The start time for the JVM of the system.
StartTime The beginning of the time period chosen for this

report.
StopTime The end of the time period chosen for this report
58 CONFIDENTIAL
SMA User Interface
GC Statistic Description
TotalNumberOfCollections The total of all garbage collections done in this

JVM/node for the specified time period.
TotalNumberOfMajorCollects The number of major (or “full”) garbage collections

done in this JVM/node for the specified time period
TotalNumberOfMinorCollects The number of minor garbage collections done in

this JVM/node for the specified time period
TotalStorageFreed The amount of space, in bytes, released in this

JVM/node by all garbage collections done in the
specified time period.
When an object is released in Java, it goes to

garbage collection, and the space required to hold
that object in the JVM is freed.
MajorStorageFreed The amount of space, in bytes, released in this

JVM/node by major garbage collections done in
the specified time period.
MinorStorageFreed The amount of space, in bytes, released in this

JVM/node by minor garbage collections done in
the specified time period.
TotalCollectionTime The amount of time, in seconds, required by all

garbage collections done in this JVM/node in the
MajorCollectionTime The amount of time, in seconds, required to do the

major garbage collections in this JVM/node in the
MinorCollectionTime The amount of time, in seconds, required to do the

minor garbage collections in this JVM/node in the
ElapsedTime The amount of time, in seconds, between the Start

and Stop times specified.
FinalCollectTime The last time any garbage collection was run in this
JVM/node.
CollectionElapsedTime A comparison of the elapsed time to the total

Percentage collect time.
IMPORTANT: If the system is spending more than

3% of its processing time doing garbage collection,
it is spending too much time, and a problem exists
somewhere in the system setup. Check this
measurement, and then if that is high, look at the
other collection times to see the collection pattern.
CONFIDENTIAL 59
SMA User Interface
The Hourly Garbage Collection Statistics show the pattern of garbage collection over
time. If the workload on the system is consistent, then the garbage collection should also
be consistent. If the workload is consistent but there is a spike in the garbage collection,
that should be investigated to see what kind of processing caused the spike.
Column heading Description
Hour The hour (or portion of the hour) included in the specified time
period.
Number of GC The Total Number of Collections value for this hour.
Amount The Total Storage Freed, in bytes, for this hour.
Collect Time The Total Collection Time for this hour.
Percentage The Collection Elapsed Time Percentage for this hour.
Log Usage Statistics
Log Usage shows overall system activity. Based on the number of interactions, the Log
Usage will show various Performance Analyzer counts of system usage, so the system
administrator can see what activities are going on from a system-level perspective.
For example, if a user complains that the system is slow at 4 p.m., the sysadmin can
choose Start and Stop parameters to highlight that time and see whether there was a
sudden spike in the number of users, or in activities run by existing users, or some other
occurrence that might cause a system slowdown.
1. Click the radio button next to the Log Usage Statistics section.
2. In the Node Name field, enter the name of the node to be viewed.
NOTE: The Log Usage statistics all apply to one JVM (one node) in the Process
Commander system.
60 CONFIDENTIAL
SMA User Interface
For definitions of these statistics, please reference the Using Performance Tools tech
note, which is available on the PDN website.
Compare Garbage Collector Statistics and Log Usage Statistics
This combined view of the statistics shows an hourly breakdown of the activity in the
system, with an application perspective (Log Usage) vs. a garbage collection perspective
(GC statistics). This report allows the system administrator to see what the system is
doing vs what the JVM is doing, and how they relate together. If there is a garbage
collection problem, and too much garbage is being generated, is that directly or indirectly
related to the activities being run? Is a spike in garbage collection paralleled by a spike in
processing? Is the growth across the two areas consistent – i.e., more activities run
means more garbage - or is one growing faster than the other?
1. Click the radio button next to the Compare Garbage Collector Statistics and Log
Use Statistics section.
CONFIDENTIAL 61
SMA User Interface
2. In the GC Log File field, enter the path to the log file, including the file name.
Example: f:\websphere\tempdir\logs\gclog.out
3. In the Node Name field, enter the name of the node to be viewed.
62 CONFIDENTIAL
SMA User Interface
(See above sections for descriptions of the fields on the report.)
CONFIDENTIAL 63
SMA User Interface
Use Case Example
As stated above, garbage collection can have a detrimental impact on performance.

Many companies measure total requestor elapsed time – the amount of time all
requestors are spending in the system – and the garbage collection time can really skew
these results.
As an example, suppose a company has a system with 50 requestors, and 50 users

which are active on those requestors. The company measures 350 minutes of overall
response time for one hour on the system for those 50 users.
During that hour, the system spends 5 minutes doing garbage collection. Since the
garbage collection takes all available system CPU when it runs, all 50 users will be unable
to process any of their work during the garbage collection execution. Thus, the 5 minutes
of garbage collection must be multiplied by 50 (users); the cost to the system of that 5-
minute garbage collection is 250 minutes overall, which is most of the 350 minutes
measured for that hour. Performance is definitely impacted.
Possible next steps:
For a sudden spike in garbage collection, was the database threshold exceeded? (The
database can create lots and lots of garbage.) Check the alert log for threshold failure
messages.
If there is no spike in garbage collection, but just a gradual or consistent increase, there
may be other causes. Are activities running which are making a lot of page copies? Are
the clipboard pages being reused, or are they being deleted and recreated? If large
quantities of I/O are being processed, lots of garbage will be created.
64 CONFIDENTIAL
SMA User Interface
Log Files
There are two PegaRULES log files:
• the “standard” Pega log

• the PegaRULES Alert log
The Pega log file is named PegaRULES-yyyy-MMM-dd.log (example: PegaRULES-

2006-Apr-13.log). This log file contains information on the startup and shutdown of the
system, as well as fatal error messages.
The Alert log file is named PegaRULES-ALERT-yyyy-MMM-dd.log (example:

PegaRULES-ALERT-2006-Apr-13.log). This log file contains alert messages which relate
to poor performance of the PegaRULES system, such as a query taking too long to return,
or being too large.
The prlogging.xml file (which has taken the place of the log4j.xml file) determines what
information goes into which log. For full information on these logs, please reference the
Administration and Security Guide.
To view the contents of either of the log files, click on the links to download them in either a
text or a zip format.
CONFIDENTIAL 65
SMA User Interface
Logging Level Settings
The Logging Level Settings option enables a developer to change the configuration of the
prlogging.xml file at runtime, rather than having to change the file itself and redeploy the
entire application.
Logging can be set for a specific Java class or a rule (such as an activity, model, etc. –
either the rule type, or a specific instance of the rule).
To set the level for a new logger or to change the level on an existing logger, follow these
steps:
1. In the Logger field, choose or enter the appropriate Java class or rule to be logged.
NOTE: The dropdown list in the Logger field shows only the items which are currently
instantiated. If the item to be logged is not listed here, enter it manually.
66 CONFIDENTIAL
SMA User Interface
2. After the logger has been chosen, click the Get Current Level button to see the
current level of logging set for that logger. This information will be displayed at the bottom
of the screen.
3. Choose the Level
4. Click the Set Level button.
The log4j priority levels of log messages are as follows, in decreasing order of severity:
• FATAL
• ERROR
• ALERT
• WARN
• INFO
• DEBUG
For any issues that arise, messages at or above the specified priority are displayed in the
output. For example, if ERROR is specified for a category, messages of priority levels
ERROR and FATAL are logged. To log all messages, choose the level DEBUG or ALL.
NOTE: If a rule or a Java class is not specified in the prlogging.xml file, and does not have
logging set at runtime through the above functionality, then the default root log setting of
ALERT is used.
For all these levels, log messages are sent to the standard PEGA log – except for
ALERTs, which are sent to the ALERT log. Thus, if the system level is set to WARN or
CONFIDENTIAL 67
SMA User Interface
INFO, any messages which are warnings or errors will be sent to the PEGA log, but an
alert would be sent to the ALERT log.
To turn logging off for a specific logger, choose the level OFF.
The ResetAll button resets all logging to the default specified in the prlogging.xml file.
Remote Logging
The Remote Logging feature uses the log4j socket server to stream the contents of the
standard PEGA log file to the user’s PC. The Remote Logger catches messages before
they are written to the log file, so the developer can see all messages about all processes
running on the server of the System Console being used.
The Apache LogFactor5 analysis module (which can be installed on the PC) then displays
the contents of the log file in real-time as it is being updated.
To set up remote logging, it is necessary to download, install, and run the log4j socket
server.
1. Under Active Loggers, click the word “here” in the sentence .To download logj4
socket server click here.
2. Save the file to your hard drive and extract it with WinZip. Make a note of the directory
that you extracted it to so you know where to locate the startSocketServer.cmd file. This
file starts the LogFactor5 window that displays the contents of the log.
3. Create a shortcut for the startSocketServer.cmd file and place it on your

desktop.
4. To start the LogFactor5 window, use the startSocketServer.cmd file on your

computer. If you created a shortcut for it, double-click the shortcut. Otherwise,
launch a command prompt, navigate to the directory where you installed it, and
invoke the file. The LogFactor5 window appears.
Be sure to start the LogFactor5 window before you add your workstation to the
active logger list.
68 CONFIDENTIAL
SMA User Interface
Once LogFactor5 is started, start the remote logging process:
1. Enter the name of your computer in the Remote host field.
2. In the Remote port field, enter the TCP/IP port number that the log4j package on the
PC will listen on. (By default, this port is 8887.)
3. Click the Add button.
Your PC should display in the list of Active Loggers.
Your PC will remain in the list of active loggers unless the Process Commander system is
restarted. To remove the logger, click the radio button and then click the Remove button
at the top of the screen.
Clicking the RemoveAll button will remove all Active Loggers from the system.
Remote Tracing
The Tracer tool monitors an individual requestor session, tracking the execution of rules.
When testing a connector rule, it is possible to start the Tracer for that requestor session
before running the connector, so the Tracer can capture session information about the
connector’s actions from the moment it starts. Because a connector runs in a requestor
session, Tracer can be started for it from the Requestor Management link.
A service usually runs in a new requestor session with a requestor ID that is not created
until the service begins processing. Therefore, it can be extremely difficult to trace a
service from its starting point; by the time the requestor appears on the Requestor
Management list, the service has finished executing.
If the service is set up to use an authenticated user ID (also known as an “authenticated

service”), then it is possible to use remote tracing to trace that user ID, with a User Watch.
If a service is unauthenticated, it cannot be identified by either a requestor ID or a user ID.

In this case, it is possible to trace the service by tracing the service rule, using a Rule
Watch.
CONFIDENTIAL 69
SMA User Interface
User Watch
When tracing an authenticated service, enter the User ID into the User Name field, and
click the Add User Watch button. The name of the UserID will appear under Active User
Watches, and the user name will be added to the “watch” list.
Then, to start the trace, open the Requestor Management link. On this screen, click the
refresh button continually until the requestor ID for this “watched” user appears in the list;
then click the radio button for that requestor ID and click the Tracer button to start the
trace.
NOTE: The developer will only have 60 seconds from when the requestor appears in the
Requestor Status list to click the radio button and then start the trace for that requestor.
The below list details the User Watch button functionality:
Button Functionality Description
Add User Watch adds a watch on the Enter a User ID into the User Name
specified user field and then click the button. The
name of the UserID will appear under
Active User Watches, and the user
name will be added to the “watch” list.
Remove User removes watch for Enter a User ID into the User Name
Watch specified user field and then click the button. The
name of the UserID will be removed
from the Active User Watches list.
Remove All removes all user watches Click the button to remove all
User Watches watches. (It is not necessary to enter
a specific user ID into the User Name
field.)
70 CONFIDENTIAL
SMA User Interface
Rule Watch
Unlike the User Watch, the Rule Watch must be started in Process Commander. Choose
the instance of the rule to be watched, and then from the menu, choose Run – Trace
Open Rule.
This menu item will start the Rule Watch and open the Tracer screen. The rule will then
appear in the Active Rule Watches section of the Remote Tracing screen.
CONFIDENTIAL 71
SMA User Interface
The following information will be displayed for each Rule Watch:
Column Description
Heading
Rule The rule identifier (pzInsKey value)
Status The status of the rule being watched. Valid status values include:
• Waiting – no one has executed the rule yet

• Activated – the rule was executed, and is now being
traced
• Deactivated – the rule execution is completed, and the
watch is reset. (The deactivated status will go by very
quickly.)
Client The ID of the requestor which is tracing the rule.
Target The ID of the requestor which happened to execute the Rule

being watched
Clicking the Clear Rule Watches button will clear all watched rules from the Active Rule
Watches section. In addition, due to the removal of the Rule Watch, if the Tracer screen
is open, the following error message appears:
Click OK to close this error, and then close the Tracer.
Additional information is also displayed about various tracer sessions:
Field Description
Sessions The number of sessions currently being traced for the node
Total Event Count The number of lines (events) in all Trace sessions currently in
system memory. (This count lets the system administrator
know whether there are so many trace sessions going that it
might affect system performance.)
Total Event Sizes The number of characters for all the events in all Trace
(chars) sessions currently in system memory.
72 CONFIDENTIAL
SMA User Interface
Advanced
This section of SMA contains additional low-level information about the nodes being
monitored. It should not be necessary for most system administrators to view this data on
a regular basis. If a problem is encountered with a Process Commander system, and the
system administrator contacts Global Support, a Pegasystems Support Engineer may
request that the system administrator send them some specific information from this
section; otherwise, it may be ignored.
CONFIDENTIAL 73

System Management Application Reference Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

System Management Application Reference Guide

Uploaded by

Copyright:

Available Formats

System Management Application Reference Guide

PegaRULES Process Commander v 5.1

This document describes products and services of Pegasystems Inc. It may

This document is current as of the date of publication only. Changes in the

Although Pegasystems Inc. strives for accuracy in its publications, any

This document is the property of:

Phone: (617) 374-9600

PegaRULES Process Commander

SMA Security .....................................................................................................16

SMA User Interface ...........................................................................................25

Multiple Node Configuration:

Installing The SMA

The recommended system configuration for installing SMA is:

• local connections are faster

Adding System Nodes

As stated above, it is necessary to have a separate installation of SMA for each

Creating a New Node

Field Name Description Example

PRPC Primary URL Optional (used for the Requestor http://prodserver:

If this information is not present, then

PRPC Diagnostic URL Optional (used for downloading http://prodserver:

Authentication Whether authentication is required in

Connect through local Whether the connection for this node

Field Name Description Example

Node Name Required. A text name that DevArea

Some developers may wish to

Field Name Description Example

Server URL Required. The URL which DevArea:9091

NOTE: For local connections,

Field Name Description Example

Node Name Required. A text name that DevArea

Some developers may wish to

Host/Server Name Required. The name of the host DevArea

Port Required. The SOAP connector 9081

Field Name Description Example

Node Name Required. A text name that DevArea

Some developers may wish to

Server URL Required. The hostname and t3://myserver:7001

NOTE: There will be other text

Server Name Required. The WebLogic DevArea

Field Name Description Example

Node Name Required. A text name that uniquely identifies DevArea

Some developers may wish to have this name

NOTE: There will be other text in this field

The PegaDiagnosticUser role is associated with the SMA through a security-constraint

• Certain application servers (such as IBM WebSphere) allow roles to be mapped

mBean Security – the prmBeans.properties file

Access to the mBean operation/attribute

<?xml version="1.0" encoding="UTF-8"?>

Configuring the prmBeans.properties File

Denying access in prmBeans.properties will have different consequences, depending

3. If an mBean is only partially restricted, or even if it all operations/attributes are

Example entry in prmBeans.properties file:

mBean Level Access

Example entry in prmBeans.properties file:

mBean Attribute Level Access

Each mBean in the system contains the following attributes:

Example entry in prmBeans.properties file:

mBean Operation Level Access

Example entry in prmBeans.properties file:

mBean Operation Signature Level Access

Example entry in prmBeans.properties file:

Example prmBeans.properties File