sma ref guide v61
TRANSCRIPT
-
7/22/2019 SMA Ref Guide V61
1/63
SMA Standard Tools
System Management Application Reference Guide
PegaRULES Process Commander V6.1
-
7/22/2019 SMA Ref Guide V61
2/63
II CONFIDENTIAL
Copyright 2010
Pegasystems Inc., Cambridge, MA
All rights reserved.
This document describes products and services of Pegasystems Inc. It may contain trade secretsand proprietary information. The document and product are protected by copyright and distributedunder licenses restricting their use, copying distribution, or transmittal in any form without priorwritten authorization of Pegasystems Inc.
This document is current as of the date of publication only. Changes in the document may bemade from time to time at the discretion of Pegasystems. This document remains the property ofPegasystems and must be returned to it upon request. This document does not imply anycommitment to offer or deliver the products or services described.
This document may include references to Pegasystems product features that have not beenlicensed 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 orproduct names are trademarks of their respective holders.
Although Pegasystems Inc. strives for accuracy in its publications, any publication may containinaccuracies or typographical errors. This document could contain technical inaccuracies ortypographical 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 StreetCambridge, MA 02142-1590
Phone: (617) 374-9600Fax: (617) 374-9620www.pega.com
PegaRULES Process CommanderDocument: System Management Application Reference GuideSoftware Version 6.1Updated: J uly 21, 2010
-
7/22/2019 SMA Ref Guide V61
3/63
CONFIDENTIAL III
Contents
1 INTRODUCTION ............................................................................................................. 12 INSTALLATION AND CONFIGURATION............................................................................ 2
2.1 Installation Considerations .......................................................................................................... 22.1.1 Installing on Multiple Server Types ..................................................................................... 22.1.2 Single-Node and Multi-Node Configurations ...................................................................... 22.1.3 SMA, RMI, and Garbage Collection .................................................................................... 3
2.2 Deploying the WAR File............................................................................................................. 32.3 Setting up a Temporary Directory for WebSphere on z/OS ...................................................... 4
3 SMASECURITY ............................................................................................................ 63.1 Restricting Access with Role-Based Security ............................................................................ 63.2 Configuring MBean Security in the prmbeans.properties File .................................................. 7
3.2.1 Defining Settings in the prmbeans.properties File ............................................................... 83.2.2 Security Denials in the Default prmbeans.properties File ................................................... 9
3.3 Security Messages and Log Entries ............................................................................................ 94 THE SMAUSERINTERFACE .........................................................................................12
4.1 Management Panel .................................................................................................................... 124.1.1 System Home ...................................................................................................................... 134.1.2 Add a Node Entry ................................................................................................................ 134.1.3 Modifying a Node Entry ..................................................................................................... 15
5 LISTENERMANAGEMENT .............................................................................................17 5.1 Listeners Toolbar ....................................................................................................................... 17
6 MEMORY MANAGEMENT..............................................................................................19 7 REQUESTORMANAGEMENT .........................................................................................21
7.1 Requestor Management Toolbar ............................................................................................... 217.2 Requestor Status ........................................................................................................................ 227.3 Clipboard Size Command Output ............................................................................................. 237.4 Tracer.......................................................................................................................................... 23
7.4.1 Tracer Controls .................................................................................................................... 247.4.2 Tracer Results Display ........................................................................................................ 247.4.3 Interacting with Tracer Results ........................................................................................... 25
7.5 Performance Profiler Controls .................................................................................................. 26
-
7/22/2019 SMA Ref Guide V61
4/63
IV CONFIDENTIAL
8 SYSTEM MANAGEMENT................................................................................................28 8.1 System Management Toolbar ................................................................................................... 298.2 System Summary Information .................................................................................................. 30
9 ADMINISTRATION.........................................................................................................33 9.1 Configuration Management ...................................................................................................... 339.2 Index Management .................................................................................................................... 339.3 Pulse Status ................................................................................................................................ 349.4 Requestor Pools ......................................................................................................................... 369.5 Rule Utility Library Extractor ................................................................................................... 37
10 AGENT MANAGEMENT .................................................................................................39 10.1 General Information .................................................................................................................. 4010.2 Agents Summary Report ........................................................................................................... 4010.3 Agent Management Toolbar ..................................................................................................... 4110.4 System Queue Management ..................................................................................................... 43
11 LOGGING AND TRACING...............................................................................................46 11.1 Garbage Collector and Log Usage ............................................................................................ 46
11.1.1 Garbage Collector and Log Usage Toolbar ....................................................................... 4711.1.2 Garbage Collector Statistics ................................................................................................ 4811.1.3 Log Usage Statistics ............................................................................................................ 5011.1.4 Comparing Garbage Collector and Log Usage Statistics .................................................. 53
11.2 Log Files ..................................................................................................................................... 5311.3 Logging Level Settings.............................................................................................................. 5411.4 Remote Logging ........................................................................................................................ 5511.5 Remote Tracing ......................................................................................................................... 57
11.5.1 Remote Tracing Toolbar ..................................................................................................... 5811.5.2 User and Rule Watches ....................................................................................................... 58
-
7/22/2019 SMA Ref Guide V61
5/63
Introduction
CONFIDENTIAL 1
1 Introduction
The System Management Application (SMA) is set of utilities distributed with
PegaRULES Process Commander that enable system administrators and developers tomonitor and manage Process Commander nodes. SMA is a standalone implementationand requires a separate installation.
SMA is built on Java Management Extensions (JMX) interface and is instrumented usingJMX objects called Managed Beans (MBeans), which expose their management interfaces
to the SMA applications through a JMX agent. JMX provides a standard API to monitorand manage resources either locally or via remote access.
There are two sets of utilities in SMA, a standard set with functionality suitable for alladministrative and support users, and an advanced set whose functions are appropriate todevelopers as they build and debug new applications. The advanced tools might also be
used under the guidance of Pegasystems support.
This document describes the standard set of SMA functions. These are:
Listener Management: Displays information on running listeners; can be used tostart, stop, and restart listeners.
Memory Management: Provides the counts and KB size in memory of activerequestors, system caches, and classes.
Requestor Management: Displays information on requestors; can be used tointerrupt or stop requestors; provides access to the Profiler and Tracer tools.
System Management: Displays information on the selected nodes system,requestor counts, JVM, and build.
Administration: Provides tools for monitoring aspects of the PRPC configuration.
Agent Management: Displays information on running agents; can be used to startand stop agents.
Logging and Tracing: Displays information on garbage collection and log data.
For Further Information
For further information on the topics discussed in this document, review the documents in
the Performance areas in Developer Help and on the Pega Developer Network
(pdn. pega. com). You may also wish to refer to these documents on the EngineeringSharepoint site:
Configuration Settings Reference Guide (pr conf i g. xml file settings)
SMA Advanced Tools: Rule Assembly Cache and Rule Cache Management(available for V5.5 and V6.1)
SMA Advanced Tools: ETier and Web Tier Static Content Management(V6.1)
-
7/22/2019 SMA Ref Guide V61
6/63
Installation and Configuration
2 CONFIDENTIAL
2 Installation and Configuration
SMA is installed as a standalone application, but does not need to be installed on every
node in a cluster. SMA installation and configuration is a three-step process:
Choose an SMA installation location.
Deploy the prsysmgmt . war file.
Add entries to the SMA configuration for each node that will be monitored.
Some application servers, in particular WebSphere on z/OS, may require the creation of atemporary directory in a location that persists across sessions. Refer to the section Settingup a Temporary Directory for WebSphere on z/OS, for instructions on setting up this
directory.
2.1 Installation ConsiderationsSince SMAs function is to monitor Process Commander nodes, we recommend that youinstall it on a server that is not running Process Commander. This precaution ensures thatSMA will continue to operate even if a Process Commander node fails. However, it does
not affect operations if Process Commander and SMA both reside on the same node.
In a small development or test system, it might be useful to have the SMA installed on the
same server to assist in application development. However, once that application goes intoproduction, reinstall SMA on a separate system.
2.1.1 Installing on Mul tiple Server Types
An SMA instance can only monitor Process Commander nodes running on a single servertype, for example only WebLogic servers or only WebSphere servers. SMA must berunning on the same type of application server as the nodes it is monitoring. If your
Process Commander installation includes five servers running WebSphere and fiverunning WebLogic, the installation requires two instances of SMA, one to monitor eachapplication server type.
2.1.2 Single- Node and Multi- Node Configurations
The number of nodes on which the Process Commander application runs determines howto configure it in SMA.
In a single-node system, install both the Process Commander application and theSMA in the same application server, and specify that the node will connectthrough the local JVM on the nodes Configuration Details setup screen.
In a multi-node system, install the SMA in a JVM that is separate from theProcess Commander application, preferably on another node. Do not specify alocal connection on any of the nodesspecify a Server URL for the JMX serveron the nodes Configuration Details setup screen instead. All nodes will then useRMI (Remote Method Invocation) to communicate.
-
7/22/2019 SMA Ref Guide V61
7/63
Installation and Configuration
CONFIDENTIAL 3
2.1.3 SMA, RMI, and Garbage Collection
In a multi-node installation, JMX uses RMI to communicate with the other nodes beingmonitored. In Java, explicit garbage collection is forced once per minute in any system
using RMI, although it is possible to configure the JVM to suppress this by disablingexplicit GC calls. If not suppressed, frequent garbage collection can lead to degraded
system performance.
If a Process Commander node and SMA are sharing a JVM on such a system, that systemwill collect garbage once per minute, because of the systems use of RMI. Again, it will
adversely affect Process Commander performance on that node.
This issue can affect all server types except WebSphere, which uses SOAP services for
intranode communications, not RMI.
A single-node installation connecting through the local JVM avoids RMI and the forcedgarbage collection problem, and the attendant performance issues.
2.2 Deploying the WAR File
The prsysmgmt . war file is included as a component of all versions of ProcessCommander.
The SMA WAR file should be deployed at the same time as Process Commander. Referto the installation guide for your platform for details on deploying the WAR file.
-
7/22/2019 SMA Ref Guide V61
8/63
Installation and Configuration
4 CONFIDENTIAL
2.3 Setting up a Temporary Dir ector y for WebSphere on z/ OS
Note While the following instructions apply to all application servers on all
operating systems, this step is requiredonly for WebSphere on z/OS, and isoptional for other environments.
SMA requires as part of its operation a temporary directory in which to store configuration
information including the file Nodes. xml , the list of nodes being monitored.
When deploying SMA in a dynamic servants configuration with WebSphere and z/OS, theapplication server may dynamically replicate the SMA instance in separate processes, and
each of these processes must be able to find and persist the set of nodes being monitored in
Nodes. xml . The temporary directory location specified here remains invariant betweensessions, and allows SMA to persist its state.
The temporary directory is defined as a new Java system property. Before defining theproperty, first check that the directory exists. If necessary, create it with the appropriate
permissions. Start the server, then set the temporary directory location by defining the Java
system property com. pega. sma. t mpdi r , using the - Dcommand line option. Consult yourWebSphere documentation for details on how to set a system property.
For example, here are the steps needed for WebSphere 6.x, where SERVER_NAMEis
your server and/SYSTEM/tmp/SMA is the temporary directory.
1. Create a folder where SMA can write the Nodes. xml file and authorize it:
mkdi r / SYSTEM/ tmp/ SMAchmod 770 / SYSTEM/ t mp/ SMAchown ASSR1: WSCFG1 / SYSTEM/ t mp/ SMA
2. Set the property com. pega. sma. t mpdi r on the WebSphere console. Navigate to your
server: Application Servers > Servers > SERVER_NAME .3. Open Server Infrastructure > Java and Process Management > Process
Definition > Servant > Additional Properties > Java Virtual Machine. Under
Generic JVM arguments, add or replace the property:
- Dcom. pega. sma. t mpdi r=/ SYSTEM/ t mp/ SMA
4. Recycle WebSphere and start SMA.
Java 2 Security and the Temporary Directory
If Java 2 Security is enabled, then the applications security policy must grant permissionsto certain components of SMA for them to perform read and write operations on the
temporary directory. To do this on WebSphere, package the application in an EAR file,
and place a was. pol i cy file in the META- I NF directory of the EAR file that grants thefollowing permissions:
grant codeBase "f i l e: ${webComponent}" {permi ssi on j ava. ut i l . Propert yPermi ssi on "com. pega. sma. t mpdi r ", "r ead";permi ssi on j ava. i o. Fi l ePermi ssi on "${com. pega. sma. t mpdi r}${/ }- ",
"r ead, wr i t e";};
For other application servers, refer to the application server documentation for instructions
on where to place these permissions.
-
7/22/2019 SMA Ref Guide V61
9/63
Installation and Configuration
CONFIDENTIAL 5
If the specified directory does not exist, or the permissions are not set correctly, SMA does
not start, and returns an error indicating that it could not findNodes. xml .
If Temp di r Is Not Set
If the com. pega. sma. t mpdi r system property is not specified, SMA will proceed as
follows. If there is a Nodes. xml file in the directory specified by the user . home system
property, that file is used. Otherwise, the system looks forNodes. xml in the directory
specified by thej avax. servl et . cont ext. t empdi r property retrieved from theServletContext object, and creates the file there if it does not exist. This directory is not
guaranteed to be invariant among multiple SMA sessions when SMA is deployed indynamic servants mode on z/OS, so using it may lead to unexpected behavior in this case.
-
7/22/2019 SMA Ref Guide V61
10/63
SMA Security
6 CONFIDENTIAL
3 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, Pegasystems provides an access controlmechanism for the System Management MBeans.
JMX security mechanisms vary among the different web servers. Tomcat provides the
functionality to set up role-based access to the MBeans in the SMA, but neitherWebSphere nor WebLogic have finalized their security mechanisms for individual
MBeans. Therefore, Pegasystems has added additional security through use of a propertiesfile to control access to the system management MBeans.
3.1 Restri cting Access wi th Role- Based Secur it y
If implementing role-based security, users who will access the SMA must be assigned thePegaDiagnosticUser role in order to have complete access to SMA functions.
PegaDiagnosticUser is defined as a security constraint in the ProcessCommanders web. xml file (found, for example, at
TOMCAT_HOME/ webapps/ prweb/ WEB- I NF/ web. xml ).
PegaDiagnosticUser is assigned to individual users in the application serversuser definitions file (found, for example, at TOMCAT_HOME/ conf / t omcat -
user s. xml ).
If you do not want to restrict SMA access, remove the constraint with either of thesemethods:
Edit the PegaRULES web. xml file and comment out the security constraint. Ifyou make this change in web. xml , you may need to redeploy the prwebapplication.
Certain application servers (such as WebSphere) allow roles to be mapped to allusers, including unauthenticated users. If you want to map thePegaDiagnosticUser role to all users, consult your application serversdocumentation to see how to accomplish the mapping.
Securi ty Constr aint Defini tion
This XML fragment shows the PegaDiagnosticUser security constraint as defined in the
web. xml file.
- - >
Diagnostic Data
Serves diagnostic files generated by the JMX client
/DiagnosticDataGETPOST
-
7/22/2019 SMA Ref Guide V61
11/63
SMA Security
CONFIDENTIAL 7
PegaDiagnosticUser
To assign the role to users and thus restrict SMA access to those users, add the role and the
user assignments in the servers user file. For example, for the usersmauser in t omcat -users. xml :
3.2 Configuring MBean Security in the prmbeans.properties File
Process Commander denies access to one or more MBeans, MBean operations, or MBean
attributes through use of a Java properties file, prmbeans. propert i es. The file is locatedin the same directory as prconf i g. xml , for example on Tomcat in
TOMCAT_HOME/ webapps/ prweb/ WEB- I NF/ cl asses.
The properties file describes a negative security policy, meaning that it containsinformation only on actions that are explicitly denied. All other operations are allowed.This provides a level of security for the MBeans, and ensures that there is a universalmethod of securing MBean access across all web servers.
Upon startup, the settings in prmbeans. propert i es are read into memory. Each time thatan MBean attribute or operation is accessed by the SMA, the cached security settings forthat MBean are checked, and access is either allowed or denied to all users. The
PegaDiagnosticUser role setting for any given user is not pertinent to this security policy.If access to an MBean is denied, it is denied to everyone. If access is denied, an error
message like this one is returned to the caller:
Access to t he mBean operat i on/ att r i but eRequestorManagement . RequestorDetai l s[ j ava. l ang. St r i ng] has been deni ed.I f you bel i eve that you shoul d have access t o thi s operat i on oratt r i but e, pl ease check your mBean secur i t y set t i ngs or cont act yoursystemAdmi ni st rat or .
Note: The prmbeans. propert i es settings are read only on application startup. If
you later change a security setting in this file, stop and restart SMA for thatchange to be referenced.
If direct access to an MBean is denied, the error is fatal and the message returned is:
Access to t he mBean operat i on/ at t r i but eRequestorManagement . Cl i pboard[ j ava. l ang. St r i ng] has been deni ed. I f youbel i eve t hat you shoul d have access t o t hi s operat i on or at t r i but e,pl ease check your mBean secur i t y sett i ngs or cont act your syst emAdmi ni st rator .
-
7/22/2019 SMA Ref Guide V61
12/63
SMA Security
8 CONFIDENTIAL
3.2.1 Defining Settings in t he prmbeans.properti es File
MBean security access can be denied at four levels: to all MBeans, to individual MBeans,at the attribute level, or at the operation level.
All examples shown in this section are valid in the prmbeans. propert i es file. Thecomplete list of MBean descriptors indicating what you can change is in the file
PRMBeanDescr i ptor . xml , in the jar file PRWEB_HOME/ WEB- I NF/ l i b/ pega/ prpubl i c. j ar .
No Access
If access to all MBeans is denied, then no MBeans are registered with the JMX server, andall other settings in the file are ignored.
Syntax: deny = t rue
Example: deny = t rue
MBean Level Access
MBeans are registered in the JMX server unless specifically denied. If access to a namedMBean is denied, it is not available for use in SMA, and not listed in the navigation pane.Any other file settings for this MBean are ignored.
Syntax: deny. mBeanName = true
Example: deny. RemoteTraci ng = t rue
MBean Att ri bu te Level Access
Each MBean contains four attributes where access can be denied: name, major version,
minor version, and category.
Syntax: deny. mBeanName.AttributeName = true
Example: deny. Request orManagement. Name = t rue
MBean Operat ion Level Access
If an MBean is only partially restricted, then it is registered with the JMX server, but
access to the restricted value is denied. This means that although a remote user can see thatrestricted properties exist, their values cannot be accessed either programmatically orthrough the SMA user interface.
If the MBean has multiple operations with the same name, but different signatures, this
entry in the prmbeans. propert i es denies access to all of them.
Syntax: deny. mBeanName.OperationName = true
Example: deny. Request orManagement . Cl i pboard = t rue
-
7/22/2019 SMA Ref Guide V61
13/63
SMA Security
CONFIDENTIAL 9
MBean Operati on Signatu re Level Access
If access to an MBean with the given operation and signature is denied, all other settingsfor the given operation are ignored. More than one signature can be included in a comma-separated list. Do not include spaces in the signature list, or the security rule will notmatch.
Syntax:deny. mBeanName.OperationName[ OperationSignature, ] = t rue
Example:deny. HeapProf i l i ng. Anal yze[ j ava. l ang. St r i ng, j ava. l ang. St r i ng] = t rue
3.2.2 Securi ty Denials in the Default prmbeans.properties File
The default properties file on Tomcat is: TOMCAT_HOME/ webapps/ prweb/ WEB-
I NF/ cl asses/ prmbeans. propert i es. It includes three statements:
#Defaul t mBean secur i t y conf i gurat i on.deny. DatabaseManagement . DatabaseConnect i onDetai l s = t ruedeny. Request orManagement . Request orDetai l s = t ruedeny. Request orManagement . Cl i pboard = t rue
The default settings deny access to three functions at the MBean operational level, asdescribed in this table. To enable that access, comment out this denial in
prmbeans. propert i es.
Table 1: Default prmBeans.properties Security Denials
On SMA Screen Access Denied To What Is Denied
Requestor
Management
Details command Prevents display of a trace entry with details
of the requests sent by this requestor,including specific database information.
Requestor
Management
Clipboard command Prevents display of clipboard data for that
requestor.
Database
Management (in
SMA Advanced)
Database Connection
Details command
Prevents the display of the managed
connections to the selected database (that is,
the running requestors), which in turn
prevents the display of all commands recently
executed by that requestor, including specific
database information.
3.3 Security Messages and Log Entries
Ifprmbeans. propert i es is left in the default state, then during startup, the followingmessages are written to the PEGA log:
Located App Server i ndependent MBean securi t y conf i gurat i on:f i l e: / D: / programs/ t omcat5. 5/webapps/ prweb0601/ WEB-I NF/ cl asses/ prmbeans. propert i es13: 58: 45, 807 [ wabcdexp] ( pri v. management . MBeanSecur i t y)I NFO - The f ol l owi ng MBean secur i t y conf i gurat i on has been appl i ed:
deny. Request orManagement . Cl i pboard=t rue
-
7/22/2019 SMA Ref Guide V61
14/63
SMA Security
10 CONFIDENTIAL
deny. Request orManagement . Request orDetai l s=t ruedeny. DatabaseManagement . DatabaseConnect i onDetai l s=t rue
10: 53: 27, 639 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - mBean Management (Web) i ni t i al i zed f or Def aul t Domai n
If the system could not locate the prmbeans. propert i es file, then no security is appliedto the SMA, and all operations are allowed by default. The following messages are writtento the PEGA log:
Unabl e t o l ocat e App Server i ndependent mBean secur i t y conf i gurat i onaf t er t ryi ng:
abcde- prmbeans. propert i eswabcdexp- prmbeans. propert i esprmbeans. propert i es
11: 36: 08, 264 [ wabcdexp] ( pri v. management . mBeanSecur i t y)WARN - mBean securi t y conf i gurat i on has not been def i ned. Al l mBeanoperat i ons wi l l be al l owed.11: 36: 08, 702 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - mBean Management (Web) i ni t i al i zed f or Def aul t Domai n
If the default prmbeans. propert i es file was changed, and an entire MBean was disabled,messages such as these are displayed at startup:
Located App Server i ndependent mBean securi t y conf i gurat i on:f i l e: / D: / programs/ t omcat5. 5/webapps/ prweb0601/ WEB-I NF/ cl asses/ prmbeans. propert i es
11: 37: 48, 046 [ wabcdexp] ( pri v. management . mBeanSecur i t y)I NFO - The f ol l owi ng mBean secur i t y conf i gurat i on has been appl i ed:
deny. Request orManagement . Request orDetai l s=t ruedeny. Request orManagement=t ruedeny. DatabaseManagement . DatabaseConnect i onDetai l s=t rue
11: 37: 48, 327 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBean com. pega. pegarul es. management . Request orManagement hasnot been regi st ered due to the mBean secur i t y conf i gurat i on.11: 37: 48, 405 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - mBean Management (Web) i ni t i al i zed f or Def aul t Domai n
If the default prmbeans. propert i es file was changed, andall MBeans were disabled,messages similar to the following will appear at startup:
11: 38: 44, 358 [ wabcdexp] ( pri v. management . mBeanSecur i t y)I NFO - The f ol l owi ng mBean secur i t y conf i gurat i on has been appl i ed:
deny. Request orManagement . Request orDetai l s=t ruedeny. Request orManagement=t rue
deny. DatabaseManagement . DatabaseConnect i onDetai l s=t ruedeny=t rue
11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBean com. pega. pegarul es. pri v. management. web.Servl etManagement has not been regi st ered due to t he mBean securi t yconf i gurat i on.11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBean com. pega. pegarul es. management . HeapProf i l i ng has notbeen regi st ered due to the mBean secur i t y conf i gurat i on.
-
7/22/2019 SMA Ref Guide V61
15/63
SMA Security
CONFIDENTIAL 11
11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement) I NFO- The mBean com. pega. pegarul es. management . DatabaseTabl eI nfo has not beenregi st ered due t o t he mBean secur i t y conf i gurat i on.11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBean com. pega. pegarul es. management . LogFi l eAccess has notbeen regi st ered due to the mBean secur i t y conf i gurat i on.11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)
I NFO - The mBean com. pega. pegarul es. management. Li st enerManagement hasnot been regi st ered due to the mBean secur i t y conf i gurat i on.11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBeancom. pega. pegarul es. pri v. management . web. WebTi erRunt i meEnvi ronment has notbeen regi st ered due to the mBean secur i t y conf i gurat i on.11: 38: 44, 593 [ wabcdexp] ( r i v. management. mBeanManagement)I NFO - The mBean com. pega. pegarul es. management . Cl assLoader Managementhas not been regi st ered due to the mBean secur i t y conf i gurat i on.
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 the log, setthe logging level for the class com. pega. pegarul es. pri v. management . mBeanSecur i t y
to INFO, so every use or attempted use of SMA is logged. Refer to Section 11.3 forinformation on changing the logging level.
Example PEGA log entries:
11: 28: 32, 561 [ t i on( 70) - 10. 60. 51. 54] ( pr i v. management . mBeanSecur i t y)I NFO - GRANTED access t o mBean Operat i on. Rel evant rul e:deny. Request orManagement . Request orLi st [ ]11: 28: 37, 624 [ t i on( 70) - 10. 60. 51. 54] ( pr i v. management . mBeanSecur i t y)I NFO - DENI ED access t o mBean Request orManagement. Rel evant rul e:deny. Request orManagement . Cl i pboard
The relevant rule refers to entries in the prmbeans. propert i es file. When access isgranted, the log file contains a message stating that the listed configuration setting was notfound in the properties file. When access is denied, the log message references theconfiguration setting which denied access to the requested feature.
To record less detail in the PEGA log, disable INFO-level logging after SMA security isconfigured satisfactorily.
-
7/22/2019 SMA Ref Guide V61
16/63
The SMA User Interface
12 CONFIDENTIAL
4 The SMA User Interface
SMA can be accessed through Process Commander, the application servers
administration page, or directly through a browser.
Through Process Commander: Start PRPC as a developer. From the Pega button,select System > Tools > System Management Application.
Through the application server: Navigate to your web server administration pageand click the prsysmgt link.
Through the browser: Enter the URL and port number for SMA on the browsersaddress bar
4.1 Management Panel
Use the management panel to add nodes, edit the configuration properties of an existingnode, run SMA monitoring and management programs, and delete or disconnect a
selected node from the SMA configuration.
Table 2 identifies the node management tool icons and their functions.
Table 2: SMA Node Management Functions
Element Description
Displays a summary of all defined nodes. For each node, the
summary includes the node name, the system name, totalsystem memory in KB, number of requestors, number ofagents, number of listeners, and the PRPC version. Refer toTable 3.
-
7/22/2019 SMA Ref Guide V61
17/63
The SMA User Interface
CONFIDENTIAL 13
Opens the Enter Node Configuration Details setup screen to
add a new node.
Opens the Edit Node Configuration Details setup screen,which displays the selected nodes current configuration.
Removes the selected node from the SMA configuration.
Disconnects the selected node from the SMA configuration.It remains part of the SMA system but its data is notincluded in system-wide summaries.
When SMA is first opened, the console lists only the node where SMA is running. Entermore nodes to add them to the list. Selecting a node highlights its name and displays itsSystem Management summary. SMA functions will act on this selected node. To change
nodes, click on another node name.
4.1.1 System Home
Click to display a snapshot of all connected nodes in the system. Table columns aredescribed in Table 3.
Table 3: System Details Summary, All Nodes
Column Description
Node Name The name of the Process Commander node.
System Name The name of the server on which the named node runs. More than one
Process Commander node can run on one server.
Total Memory The current size of the JVM in bytes. This can show whether memory for
one or more nodes is over-allocated [HOW?].
# Requestors The number of requestors in memory for this node. This number can point
to a load balancing situation in the cluster. If one node has many
requesters and others have only a few, users on the heavily loaded node
may experience performance slowdowns.
# Agents The number of agents defined on this node.
# Listeners The number of listeners defined on this node.
Version The Process Commander version being run on the node.
4.1.2 Add a Node Ent ry
To add a node entry, click to open the Enter Node Configuration Details setupscreen. SMA automatically completes as many fields as it can.
Add an entry for each node to be monitored. There are minor differences in the
information required for different server types, as noted in Table 4.
-
7/22/2019 SMA Ref Guide V61
18/63
The SMA User Interface
14 CONFIDENTIAL
When all fields are complete, clickSubmit to add the node to the node list.
Table 4: SMA Configuration Details Setup Screen Fields
Field Name Description
Current Server Version of the server to which this node connects. This field is
automatically filled by SMA.
Server Connection Type The type of server to which this node connects. This field is
automatically filled by SMA.
Node Name Required. A user-defined text name that identifies this node in
SMA and appears in the node list. Node names must be unique
within the SMA configuration. A node name can be the same as
a server name.
PRPC Primary URL The URL used to start Process Commander on this node.
Optional; used for the Requestor Trace functionality. If a value
is supplied, verify that it points to the appropriate server name
and port for the Process Commander server. If the context root
of the Process Commander installation is notprweb, also enter
the correct context root.
PRPC Diagnostic URL The URL used to start the Diagnostic Data servlet
(pr sysmgmt ) on the Process Commander server. Optional;
used for downloading reports. If a value is supplied, verify that
it points to the appropriate server name and port, and the path
indicates the correct context root.
-
7/22/2019 SMA Ref Guide V61
19/63
The SMA User Interface
CONFIDENTIAL 15
Port (WebSphere only) Required. The SOAP connector port, which is defined in the
WebSphere Administrative Console and listed in the
WebSphere log:The SOAP connect or i s avai l abl e at
por t 8880.
Server Name (WebLogic
8 only)
Required. The WebLogic application server name for this node,
set up when the node was defined in WebLogic.Connection Type Select the connection type from the drop-down list, either
Remote Connection SMA is standalone, or Local JVM
Connection SMA is installed on PRPC server.
Server URL (Tomcat) The URL for this nodes JMX server. The necessary JMX
protocol information is prefilled, so all you must do is change
the default server and port (l ocal host : 9004) to the correct
JMX server name and port for this node. Do not change any of
the protocol information. Required for remote connections and
optional for local connections. For example,servi ce: j mx: rmi : / / / j ndi / rmi : / / myserver : 9004/j mxrmi
Server URL (WebLogic) The URL for this nodes JMX server. The necessary JMXprotocol information is prefilled, so all you must do is change
the default server and port (l ocal host : 7001) to the correct
JMX server name and port for this node. Do not change any of
the protocol or service information. Required for remote
connections. For example,servi ce: j mx: t 3: / / myserver : 7011/ j ndi / webl ogi c.management
Authentication Mode Select a JMX server login option from the drop-down list.
There are three choices: Credentials not required (no
authentication); Always prompt for credentials; or Always use
the following credentials.
Admin Username The username and password fields are shown only if you
selected the authentication mode Always use the followingcredentials. Enter the name of the administrative user with
access rights to the JMX server.
Admin Password The JMX server administrators password.
Node ID Identifies this instance of PRPC. Used only when multiple
instances of PRPC operate on a single host and IDs are needed
to distinguish between them. The ID is a 32-bit string and is the
value of the property pxSyst emNodeI D. You can obtain this
value from the Clipboard, under the pxProcess property.
4.1.3 Modif ying a Node Entr y
To edit the properties of a node already in the configuration, click to display theModify Node Configuration Details screen. Properties that can be modified include thenode name, primary and diagnostic URLs, connection type, remote server URL, node ID,and administrative credentials. Refer to Table 4: SMA Configuration Details Setup ScreenFields, for descriptions of these fields. ClickSubmit to enter the data.
-
7/22/2019 SMA Ref Guide V61
20/63
The SMA User Interface
16 CONFIDENTIAL
-
7/22/2019 SMA Ref Guide V61
21/63
Listener Management
CONFIDENTIAL 17
5 Listener Management
The Listener Management function displays information about listeners on the selected
node. Its toolbar contains commands to start, stop, and restart listeners.
Click to refresh the displayed listener data.
The data display contains information on available and running listeners:
The Available Listeners drop-down lists all listeners defined in this ProcessCommander system.
The Running Listeners report lists data on all listeners that are or were runningin the Process Commander system.
5.1 Listeners Toolbar
Available Group
Button Description
Start Starts a listener selected from the Available Listeners drop-down and
adds its information to the Running Listeners listing. Refresh the
screen to display the Listener information if necessary.
Runn ing Group
Button Description
isAlive Shows whether the selected listener is enabled.
Query Displays information about the selected listener.
Listener Rule Data Data provided about this listener from the Data- Admi n-Connect -
instance.
Restart Stops and then restarts the selected listener.
Stop Stops the selected listener and removes its information from the
Running Listeners list.
-
7/22/2019 SMA Ref Guide V61
22/63
Listener Management
18 CONFIDENTIAL
By Type Running Group
These commands affect all listeners of the same type as the selected listener in theRunning Listenerssection. The listener types include Email, File, JMS, JMSMDB, andMQ. MQ listeners are available only when Process Commander is deployed as a webapplication.
Button Description
RestartType Stops and then restarts all listeners of the specified type.
StopType Stops all listeners of the specified type.
All Runni ng Group
These commands affect all listeners in the Running Listenerslist. It is not necessary to
select a specific listener in order to use them.
Button Description
RestartAll Restarts all listeners on this node.
StopAll Stops all listeners on this node.
Each running listener included in the summary is described by the data listed in Table 5.
Table 5: Running Listeners Summary Fields
Heading Description
Listener ID A unique string assigned to the listener by the Listener manager. The
Listener ID does not exist until the listener is started.
Status The state of the listener. A listener can be running, sleeping (waiting to
run), or disabled.
Listener Class The name of the Process Commander class that defines this listener
(example: Data-Admi n- Connect - Emai l Li st ener).
Listener Java Class The name of the Process Commander Java class that implements the
listener. All class names begin with
com. pega. pegarul es. servi ces. The classes include
EmailListener, file.FileListener, JMSListener, JMSMDBListener, and
MQListener.
Listener Name The name of the rule instance. 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, for example DevServerCust omerEmai l .
Time Started The date and time when this listener was started.
Last Access The time when this listener last woke from sleep mode to process a
request.Request Count The number of requests this listener has processed.
Last Request The last time listener processing was requested.
Error Count The number of errors in requests for this listener.
Last Error The timestamp of the last error.
-
7/22/2019 SMA Ref Guide V61
23/63
Memory Management
CONFIDENTIAL 19
6 Memory Management
The Memory Management function displays a statistical snapshot of memory-intensive
processes, including count and size information on requestors, caches, and class loaders.
Click to refresh the displayed data.
Table 6: Count and Size Data for Requestor and Cache Objects in Memory
Type Description
Requestors Same as Summary of Requestors table on the Requestor
Management screen. The total count of the four requestor
types is the same as the Number of Requestors listed on the
System Management screen.
Caches/Rule Instance Same as the Instances count in the Rule Cache Summary
category on the Advanced > Rule Cache Management
screen.
Caches/Rule Assembly Same as the Count in the FUA Alias Entries category on the
Advanced > Rule Assembly Cache Management
screen.Caches/Declarative The sum of two fields on the Advanced > Declarative
Rules Management screen, Classes in the Global Network
category and Unique Networks in the RuleSet List Defined
Networks category.
Caches/Dictionary The number of conclusions in the Dictionary cache is not
shown directly, but is available in the Conclusion Cache in
Memory report generated from the Advanced >
Dictionary Cache screen.
Caches/Class Map Class map information is not available on any other screen. The
-
7/22/2019 SMA Ref Guide V61
24/63
Memory Management
20 CONFIDENTIAL
class map describes class instances and their relationships,
including inheritance, keys, assembler associations, and
database tables where stored.
Class Loader Count and bytes are reported in the Current column in the Class
Summary table on the Advanced > Class Loader
Management screen.
-
7/22/2019 SMA Ref Guide V61
25/63
Requestor Management
CONFIDENTIAL 21
7 Requestor Management
The Requestor Management function displays information about the requestors (users)
running on this node. The toolbar also provides access to the Profiler and Tracer tools foruse with a specific requestor.
The Summary of Requestors shows the count for each of the four types of requestor on
this node browser, batch, portal, and application. This count information is also madeavailable on the Memory Management screen. That screen also shows the size in memory
of all requestors of each type.
7.1 Requestor Management Toolbar
All Requestors Group
Button Description
Estimate Size The Data Size column in the Requestor Status table registers zero for
all requestors by default. Clicking Estimate Size refreshes the table to
show the estimated size in bytes for each requestor.
Specifi c Requestors Group
To execute a command in the Specific Requestor group, select a requestor from thesummary report.
Button Description
Clipboard Size Displays requestor data and the estimated data size in KB for this requestor
and all threads. The size estimate is further broken down by size in KB per
thread, and within each thread, by estimated size in KB per page.
Clipboard Displays the data on the Clipboard for the selected requestor. If the default
security properties file is still in effect (refer to Section 3), clipboard access is
denied.
Refer to publication PRKB-25011,Data Structures, for information on the
Clipboard.
Performance
Details
Displays PAL statistics for the selected requestor. Refer to PRKB-24177,
Overview of the Performance Tools (PAL), for information on these statistics.
-
7/22/2019 SMA Ref Guide V61
26/63
Requestor Management
22 CONFIDENTIAL
Details Displays a trace of the operations performed by the selected requestor. This is
a snapshot display that does not update in real time. Access is denied if the
default security properties file is still in effect (refer to Section 3).
Interrupt Stops the processing of the selected requestor at the beginning of the next
activity step. If the requestor is in an error condition, such as executing a Java
block that is in a loop, this command may be unable to stop the requestor.Stop Stops the requestor, removes it from the requestor status display, and deletes it
from the system.
Tracer Starts the Tracer for the selected requestor. Refer to Section 7.3 for
information.
Start Profiling Starts the Performance Profiler tool, which reports performance details on
activities, When conditions, stream instances, and model instances for the
selected requestor. Refer to for information.
Stop Profiling Stops the Profiler.
7.2 Requestor Status
Data for all requestors displays in the requestor status report, a portion of which is shown.
Table 7 defines the column data in the requestor status report.
Table 7: Requestor Status Summary Fields
Heading Description
Requestor Name The unique ID of the requestor. The first character of the name
indicates how the requestor is used:
A indicates a listener or service rule.
B indicates a batch requestor, used by agent processing.
H indicates a user (an HTTP interaction).
P indicates portlet support.
User Name The user ID associated with this requestor. None signifies that thisrequestor is being used by an agent or other process, or that the user is
not currently logged in.
Application The rule application namethe container of RuleSet names and
versions in this user session.
Last Access The date and time the requestor last performed an operation.
Last Input The last activity or stream that was executed.
Last Thread The last PegaRULES thread in the requestor, such as Developer or
Desktop.
-
7/22/2019 SMA Ref Guide V61
27/63
Requestor Management
CONFIDENTIAL 23
Threads Number of threads associated with this requestor.
Pages The number of named pages on the last thread.
Data Size The size in bytes of the requestor page and all its associated thread-
level pages.
Traced Whether Tracer is enabled for this requestor.
Profiling Whether the Profiler is enabled for this requestor.
Client Address The IP address of the machine sending the requestor information. If
User Name is none, the client address is a process.
Java Thread The thread ID of an active requestor, if the requestor is operating in the
context of a Java thread. The field can be empty if there is no activity
at the time of the snapshot. As one example, SMA on WebSphere runs
on a SOAP connector, and in that case the thread number in the SOAP
connector thread pool is shown in this column.
7.3 Clipboard Size Command Output
The Clipboard Size command displays requestor data, and reports estimated data size inKB for this requestor and all threads. The size estimate is further broken down by size in
KB per thread, and within each thread, by estimated size in KB per page. The Pagecolumn names the primary page of the request, and the Class column identifies that pagesclass. The Creation Stack column is empty in this screen. Creation stack information isavailable in the Clipboard Viewer.
7.4 Tracer
Use the Tracer to debug flows, activities, services, parse rules, and declarative rules. Usethe Tracers controls to configure the session and run the work you want to trace. The
Tracer lists the events of each type specified in your session configuration.
This screen continuously updates as the requestor performs more operations.
-
7/22/2019 SMA Ref Guide V61
28/63
Requestor Management
24 CONFIDENTIAL
7.4.1 Tracer Controls
Tracer configuration and operation is controlled from the menu bar. From left to right, thecontrols are:
Connection: Serves two functions, to display information on the current requestor
such as host or thread, and to select a new requestor from a drop-down list ofrequestors.
Options: Sets events to trace (for example starts and ends associated withactivities or when condition rules), event types to trace (for example DeclareTriggers or Stream Rules), RuleSets to trace, and the maximum number of eventsto trace. If events exceed the maximum number, the oldest events fall off the listas new ones are added.
Pause/Continue: Toggles between functions; pauses the session being traced, orresumes processing after you have paused it, or after a breakpoint event.
Clear: Clears all events from the tracer session.
Breakpoints: Sets or changes Applies-To class, activity, and where to break (onall steps or at a selected step).
Watch Variables: Use the watch function to detect when the value of a propertychanges, and use the Watch Variables configuration form to set or change thenamed page and the named property or message to watch.
Save: Saves Tracer data as a CSV or XML file.
7.4.2 Tracer Results Display
The Tracer adds a row for each of the events selected in Trace Options and for activities
executing in the selected RuleSets.
Rows with a gray background identify activity processing. Rows with an orangebackground identify events from flow, decision, or declarative rules if selected for tracing.
-
7/22/2019 SMA Ref Guide V61
29/63
Requestor Management
CONFIDENTIAL 25
Table 8: Tracer Output Fields
Column Description
Line Number of events traced, starting at 1 for the first (oldest).
Rule # Count of distinct activity rules traced. This is not reset to zero if
you clear all the events. When a single activity is re-executedlater, the previously assigned number is repeated. Rules other
than activities are not assigned a number.
Step Method For an activity, the method in this step.
For a declarative rule or decision rule, indicates the start or end
of a computation.
For a when condition rule or Boolean expression, identifies the
rule name or (a portion of) the expression.
Step Page Name of the step page, or =unnamed= if the Step Page column
of this step is blank.
Step Step number of this step. When two or more rows appear with
the same step number, an iteration is in process at that step.
Step Status Status of the method in the step, from the pxMethodStatus
property, such as Good, Fail, or Warn. A red background marks
Fail steps that are not addressed by a transition.
Exit Iteration marks the end of an iteration step.
In this context, a red Fail row indicates an unhandled exception
condition. If a method returns a Fail status but the step contains
a transition, the Tracer row displays the status as Good and has
a normal gray background. This is consistent with the
processing status passed to the next activity step, which notes
known error conditions.
Watch (Optional column.) Watch Variable properties.
Event Type Type of event or rule: Step Begin, Step End, Activity End,
Constraint, Expression, DecisionTree, MapValue, and so on.
When Begin and When End events identify the start of a when
condition rule or similar test, such as in a precondition or
transition.
Elapsed For Step End and Activity End rows, elapsed time in seconds
for the step. (This time interval may be seriously degraded by
Tracer operation.)
Name Full name of the rule being traced as a blue-text link, showing
all key parts.
RuleSet RuleSet and Version containing the rule being traced.
7.4.3 Interacting with Tracer Results
This window supports five types of interactions:
Click within the blue text in the Name field on any row to open thecorresponding rule instance in your portal workspace.
-
7/22/2019 SMA Ref Guide V61
30/63
Requestor Management
26 CONFIDENTIAL
Click the Line, Rule # orStep fields to learn more about the event that causedthe row to be displayed, including a Java stack trace if an exception occurred.
Click the Step Page value in a row to review properties on the step page as ofthe time this step began.
From the Line display, click the blue ParameterPageName link to see thecontents of the parameter page.
From the Line display, click the blue PrimaryPageName link to see thecontents of the primary page.
A blue arrow marks the row of your most recent interaction.
For information on the Tracer, refer to the Process Commander Help topic,Debuggingwith the Tracer.
7.5 Performance Profiler Controls
The Start Profiling andStop Profiling buttons control the Performance Profiler, whichproduces a detailed trace of activity, when condition, model, and stream rule execution.The Performance Profiler traces every execution in all threads of rules of these types in allRuleSets.
This is the same tool that is accessed through the Pega buttons System > Performancemenu in the developer portal. To start the Profiler from the Requestor Manager:
1. ClickStart Profiling to initialize the data collector for the selected requestor andbegin data collection to a trace log.
2. Run the activities or other rules to be profiled.3. ClickStop Profiling.
4. Data can be saved to a CSV-formatted file in the PegaRULES temporary directory.Files are named by requestor identifier_thread name, for example:
HCF9AC2433F6D7C1FECACEB1F5EE8A0F9_STANDARD. csv.5. Open the CSV file in Excel to review and analyze the data.
The Performance Profiler lists items in the order they were completed, and therefore rowsmight not be written to the trace file in the order the sequences were started. To see thesteps in consecutive order for a given interaction, sort on the Sequencecolumn for thatinteraction in the output table.
Table 9: Performance Profiler Output File Contents
Column Name Description
Sequence Marks the beginning of an activity step.
Interaction The number of this client-server request/response interaction. An
interaction can include many sequenced steps. Interaction
numbers can be used to correlate Profiler output with
Performance Analyzer data.
Activity The internal key (pzI nsKey) of the activity, When condition, or
model rule instance involved in this step.
Caller The internal key (pzI nsKey) of the class calling the current
activity.
-
7/22/2019 SMA Ref Guide V61
31/63
Requestor Management
CONFIDENTIAL 27
Step For activities, displays the step number. For model rules,
displays M. For stream rules, displays S. For when conditions,
displays W.
Method Name or When
Result
For activities, displays the step method. For when conditions,
displays the true/false status returned by this call. For stream
rules, displays Cont r i but ed- Lengt h: n , where n is thenumber of bytes added to the stream by this step. For model
rules, is blank.
Inlined The true/false status returned depending on whether this when
condition or stream rule is inlined (is already rule-resolved and
its assembled Java code is included in the assembly of a calling
rule). The field is blank for activities and models, which do not
use inlined rules.
Total CPU Time Displays the CPU time in seconds for this step, including calls to
substeps.
CPU Time Without
Children
Displays the CPU time in seconds for this step, excluding calls
to substeps. This number is useful for isolating Java steps which
may perform other work in addition to calling other activities.Total Wall Time Displays the actual elapsed time in seconds required to complete
this step, including calls to substeps.
Wall Time Without
Children
Displays the actual elapsed time in seconds required to complete
this step, excluding calls to substeps. This number is useful for
isolating Java steps which may perform other work in addition to
calling other activities.
-
7/22/2019 SMA Ref Guide V61
32/63
System Management
28 CONFIDENTIAL
8 System Management
The System Management tool displays the management summary, key information about
the selected PegaRULES node (PegaRULES Node Information
Table 11), number of requestor starts, the PegaRULES build(Table 12), and the JVM(Table 13). When calling Pega Support, have this information available for the Support
Engineer.
Click to refresh the screen with the most recent information for the selected node.
-
7/22/2019 SMA Ref Guide V61
33/63
System Management
CONFIDENTIAL 29
8.1 System Management Toolbar
ClickRetrieve System Info to package and prepare for download a zip archive
containing system data and log files. Log files include the date of retrieval in the file name.
This download requires HTTP authentication. If the user running this command is notassigned the PegaDiagnosticUser role, the zip is not created. For information, refer to the
topic, Restricting Access with Role-Based Security.
Table 10: Data Returned by Retrieve System Info Command
System Data File File Content
AgentStatus.xml Content reported on the Agent Status
screen, refer to the topic Agent
Management.
AuthorizationReport.xml Content reported on the Advanced >
Authorization Management screen.
ClassLoaderSummary.xml Content reported on the Advanced >Class Loader Management screen.
ConfigurationStatus.xml Content of the nodes prconf i g. xml file,
this file is also shown on the
Administration > ConfigurationManagement screen.
ETierRuntimeEnvironment.xml Content reported on the Advanced >
ETier Runtime Environment screen.
ListenerStatus.xml Content reported on the Listener
Management screen; refer to the topic
Listener Management.
ModuleVersionReport.xml Content reported on the Advanced >
Module Version Report screen.RequestorList.xml Content reported on the Requestor
Status screen; refer to the topic Requestor
Status.
RuleAssemblyCacheManagement
Summary.xml
Content reported on the Advanced >
Rule Assembly Cache Managementscreen.
RuleCacheManagementSummary.xml Content reported on the Advanced >
Rule Cache Management screen.
RulesetVersionReport.xml A listing of all RuleSet version instances.
SystemStatus.xml Content reported on this System Status
screen.
WebTierRuntimeEnvironment.xml Content reported on the Advanced >
Web Tier Runtime Environmentscreen.
PegaRULES-Date.log.txt The standard log file reporting system
errors, exceptions (with their stack trace
statements), debug statements, and any other
messages not specified as alerts.
-
7/22/2019 SMA Ref Guide V61
34/63
System Management
30 CONFIDENTIAL
PegaRULES-ALERT-Date.log.txt A log of messages that identify individual
events with adverse performance
implications.
PegaRULES-ALERTSECURITY-
Date.log.txt
A log of messages generated when the
security of a Process Commander web node
server is at risk.PegaRULES-SERVICES-PAL-
Date.csv.txt
A trace of service requests and their PAL
statistics by requestor. This log is not created
by default and will not be included in the
downloaded if it was not created in
pr l oggi ng. xml .
8.2 System Sum mary Inform ation
PegaRULES Node In fo rm ation
Table 11: System Management: PegaRULES Node Information
Variable Description
System Name The name of the current node.
System Node Unique ID System-assigned ID for this node. The ID is a 32-character string.
System Start Time The date and time that this node was started.
Pulse Last Run The date and time that the system pulse last ran on this node.
Total Memory The maximum heap size being used by Java at the time of this
report snapshot.
Total Free Memory Within the total available memory, the amount not being used by
Java at the time of this report snapshot.
Production Level Identifies the functional purpose of a system in order to control
access to it. Value is an integer, and valid values are 1 for an
experimental system, 2 for development, 3 for test, 4 for pre-
production, and 5 for production. A value of 0 or a blank field
indicate that production level is not set on this node.
Concurrent Sessions
Allowed
Specifies whether concurrent sessions are allowed under the same
user ID on this node. Valid values are None and Unlimited. A
login attempt is rejected if the setting is None and the user already
has an active session.
Number Active Threads The number of active Java threads for this node, as reported as the
number of threads on the Advanced > Web Tier Thread
Management screen.
Number Requestors The number of requestors currently in memory on this node.
Number Agents The number of agents defined for this node that are running, as
indicated by the green check marks on the Agent
Management screen.
Number Listeners The number of running listeners, as reported on the Listener
Management screen.
Number Database
Connections
The number of database connections currently open for this node,
as reported as Connection Counts in the Active Database category
-
7/22/2019 SMA Ref Guide V61
35/63
System Management
CONFIDENTIAL 31
on the Advanced > Database Management screen.
System Wide Requestor Status
This section of the page tracks how many of each type of requestor have been created in
the system since it was started. There are four types of requestor: those initiated by portlet,
browser, batch, and service.
PegaRULES Build Information
Table 12: System Management Build Information
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
(06 for Version 6.x).
Minor Version The minor point release version of the rules code that was installed
(01 for Version 6.1).
Build Label The label that was defined for this build.
Java VM Information
Displays a subset of the current system properties for this nodes JVM returned by the
j ava. l ang. Syst em. getPropert i es( ) method. Not all properties are implemented by all
JVMs, so some fields might be empty on your System Management summary. In addition,some fields might be empty if access to this method is restricted on your node.
Table 13: System Management JVM Information
Property Description of Associated Value
j ava. vers i on Java Runtime Environment version.
j ava. vendor Java Runtime Environment vendor.
j ava. f ul l vers i on Java Runtime Environment full version, which differs from the
value returned byj ava. vers i onby appending a build
number.
j ava. home Java installation directory.
j ava. compi l er Name of JIT compiler in use.
j ava. vm. versi on Java Virtual Machine implementation version.
j ava. vm. vendor Java Virtual Machine implementation vendor.
j ava. vm. i nfo Java Virtual Machine sharing mode, for example mixed.
j ava. vm. name Java Virtual Machine implementation name.
os. name Operating system name.
os. ar ch Operating system architecture.
os. versi on Operating system version.
f i l e. encodi ng The character set identifier used in the JVM, for example
-
7/22/2019 SMA Ref Guide V61
36/63
System Management
32 CONFIDENTIAL
Cp1252.
-
7/22/2019 SMA Ref Guide V61
37/63
Administration
CONFIDENTIAL 33
9 Administration
Administration tools include:
Configuration Management Index Management
Pulse Status
Requestor Pools
Rule Utility Library Extractor
System Usage History
9.1 Conf igu ration Management
The Configuration Management tool displays the current version of the prconfig.xml file
for the selected node. This is the file at SERVER_HOME/ webapps/ prweb/ WEB-
I NF/ cl asses/ pr conf i g. xml .
Note Unless the system is set up to encrypt the database password, that password
will be visible in this display ofprconf i g. xml . If the system is not using adata source, be sure to encrypt your password for safety!
For full details on prconf i g. xml file settings, refer to the Configuration Settings
Reference Guide available on the PDN.
9.2 Index Management
NoteAmong the changes introduced in Process Commanders Find tool in V6.1were changes to the process used to generate the initial Rul e- , Wor k- , and
Data- class indexes the tool uses. Prior versions of Process Commander usedthis SMA Index Management utility to build the initial indexes. In V6.1, theinitial build process is automated, and any subsequent administration can be
performed within Process Commander itself. To open the relevant landingpage from the Pega button, navigate to System > Settings > Search.
Documentation is available in the Help system.
We recommend that you use the landing page in Process Commander forindex management rather than the build tools in this SMA utility. Use of
these SMA tools can produce inconsistent results in V6.1.
Table 14: Index Build Tools
Button Description
Build PegaRULES
IndexBuilds the index forRul e- instances.
Build Work Index Builds the index forWor k- instances.
Build Data Index Builds the index forData- instances.
Optimize PegaRULES Creates a single file from multiple Lucene CFS (compound file
-
7/22/2019 SMA Ref Guide V61
38/63
Administration
34 CONFIDENTIAL
Index system) files. It is more efficient to search a single file, but the
optimization process is expensive. It has a long elapsed time, and
is CPU-intensive to the point of blocking user access while it runs.
Do not optimize unless the system is running out of file handles, a
condition which is unlikely to occur.
9.3 Pulse Status
When Process Commander is installed on a multi-node system, a copy of each of the
caches is stored on each node, and each must be updated with rule changes. This updateprocess is managed by the System Pulse, which is part of the standard PegaRULES agent.The Pulse Status summary displays system pulse changes made to each node.
Saving a rule change (update, add, or delete) to one of the rule tables in the databaseregisters the change in the pr_sys_updatescache table. Each node records all its changes
in this table. The types of events saved to this table are listed in Table 15 under the cachetype.
Saving a rule change also automatically invalidates the appropriate information in thecaches on that node. However, all the other nodes in the system now have out-of-dateinformation about that rule.
To maintain cache coherence, the system pulse on each node wakes up once per minuteand queries the pr_sys_updatescachetable. The query retrieves any records that this node
did notcreate, and which have a timestamp later than the last pulse time. These cacheentries on each node are invalidated. The next time one of these rules is called, an updatedversion of the rule is retrieved from the database and added to the cache.
-
7/22/2019 SMA Ref Guide V61
39/63
Administration
CONFIDENTIAL 35
Table 15: Pulse Status Summary Table
Heading Description
Node Name Displays the node where the change being tracked by System Pulse
originated. The name listed is the unique identifier for each node
(pxProcess. pxNodeUni queI D).
Cache Type The type of event which the system pulse publishes to the system
nodes. The types include:
Cache changes to the rule cache (that is, changes to the rules).
Index changes to the Lucene indexes that support full-text search.
DELLC when the lookuplist cache is deleted.
RFDEL indicate rule-file- deletes.
ECHO tells all nodes on the system to print a message to the console.
Create Date/Time The date and time when each change was recorded.
Obj Class The class of the rule being changed. This may not be set for all cache
types, such as ECHO.
Key String The key string (pzI nsKey) for the rule instance being changed. This
may be blank for some cache types.
Parameters Other change data which may apply for certain cache types.
-
7/22/2019 SMA Ref Guide V61
40/63
Administration
36 CONFIDENTIAL
9.4 Requestor Pools
In Process Commander, an unauthenticated stateless service uses a collection of requestors
called a requestor pool to handle its service requests. The Requestor Poolstoolsummarizes information about existing requestor pools for each service package.
Process Commander uses a single user account but may make multiple simultaneous
connections to each external database, on demand. Connections are shared amongmultiple requestors, a technique known as connection pooling.
Use the Rules Explorer to review or create Data-Admin-ServicePackage instances (part ofthe Integration-Resources category), or from the Pega button, navigate to the Integration >
Integration Overview landing page. In the Integration Resources area, select ServicePackages to browse service package instances.
Requestor pool information is available on the Service Packages forms Poolingtab:
Maximum Idle Requestors, Maximum Active Requestors, and Maximum Wait.
To clear all requestor IDs and reset the requestor count to zero, select a service package
and clickClear Requestor Pool. New requestors are then created as needed.
-
7/22/2019 SMA Ref Guide V61
41/63
Administration
CONFIDENTIAL 37
Table 16: Service Requestor Pools Summary Fields
Heading Description
ServicePackage The name of the Data- Admi n-Servi cePackage instance, for
example JSR94Administration.
AccessGroup The Service Access Group specified on the Context tab of the Data-
Admi n-Servi cePackage instance, for example
PegaRULES:Unauthenticated.
LastAccess The date and time a requestor was last taken from the pool for this
service package.
Idle The number of requestors available for use at the time of the snapshot.
Active The number of requestors currently in use at the time of the snapshot.
MostIdle Over the life of the requestor pool, the greatest number of requestors
that were idle at one time.
MostActive Over the life of the requestor pool, the greatest number of requestors in
use at one time.
MaxIdle The maximum number of idle requestors allowed in this requestor pool.
Specified on the Service Package Pooling tab.
MaxActive The maximum number of requestors that may be in concurrent use.
Specified on the Service Package Pooling tab.
MaxWait The maximum time in seconds that Process Commander will wait for a
requestor to become active when a service request is pending and
MaxActive requestors are already busy. Specified on the Service
Package Pooling tab.
LongestWait The longest time a service request waited for a requestor to become
available.
Timeouts The number of times the system timed out while waiting for a requestor
to become available.
9.5 Rule Utility Library Extractor
When creating activities in PegaRULES, functions may be written for one activity thatcould be used across many activities. Examples include mathematical, time, or date
functions. These are stored in the class Rul e- Uti l i t y- Functi on, which allows customJava code to be included and referenced from activities and expressions throughout thesystem.
Functions are grouped into Java classes, according to the rule utility library in which eachfunction is defined. The libraries are extracted during PegaRULES startup and madeavailable to other users.
During some processes, such as importing, the contents of the libraries are notchecked. Ifthe import brings in new rule functions, they may not be implemented, as the library hasno information about them. Therefore, for processes such as imports, it is important to
regenerate (or recompile) all the libraries.
-
7/22/2019 SMA Ref Guide V61
42/63
Administration
38 CONFIDENTIAL
The Rule Utility Library extractor extracts either one or all of the libraries in the node tothe file system. To do this on the Library Extractor screen, enter a RuleSet name, and thelibrary name for that RuleSet, and clickExtract Libraries.
If the operation is successful, the Extractor displays a confirmation message. If either the
RuleSet or the Library Name are incorrect, the Status bar is red, and the Extractor reports itfailed to extract the library.
-
7/22/2019 SMA Ref Guide V61
43/63
Agent Management
CONFIDENTIAL 39
10 Agent Management
The Agent Management tools collect 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.
-
7/22/2019 SMA Ref Guide V61
44/63
Agent Management
40 CONFIDENTIAL
10.1 General Information
Displays the current values for the agent configuration settings in the prconf i g. xml file.
Table 17: prconfig.xml Agent Configuration Settings
Agent Configuration(prconfig.xml Setting)
Description
Minimum allowed wakeup time for all
agents (mi ni mumwakeup)
The shortest allowable interval between wakeup
triggers for agents. Default: 30,000 ms.
Wakeup interval for requestor-timeout
(master agent)
(r equest ort i meoutwakeup)
The interval between checks for stale requestors.
Default: 60,000 ms.
Wakeup interval for new agent
processing (master agent)
(newqueuewakeup)
The interval between checks for new rules.
Default: 600,000 ms and must be at least 5,000
ms.
Initial startup delay for master agents
(mast erdel ay)
The interval in minutes following startup that the
master agent waits before executing for the firsttime. Default: 600,000 ms.
Java thread pool size (t hreadpool si ze) The number of threads on which agents and
batch requestors can run. Only valid for web tier
deployments. Default: 5 threads.
For full details on these prconf i g. xml settings, refer to the Configuration SettingsReference Guide.
10.2 Agents Sum mary Report
The agent summary (Table 18) describes all agents that are running or have run in thesystem.
Table 18: Agents Summary Fields
Heading Description
Enabled? Shows whether the agent is running (a green checkmark) or not (a red
x).
To disable an agent, click a Stop button on the toolbar, or by disable
the Data- Agent- Queue instance. An agent can also be disabled by
an error condition, in which case the information is contained in the
exception information column.
RuleSet The name of the agents RuleSet
# The index number of the Agent Activity entry as listed in the Rule-
Agent-Queue. Numbering starts with 0.
Description Short description of the agent, which can include the Agent Activity
class and name.
Scheduling Displays either the current wakeup interval for the agent, in
milliseconds (for a periodic agent), or the description of settings
chosen for the next time the Agent Activity runs, which can be a
string like daily, weekdays only (for a recurring agent).
-
7/22/2019 SMA Ref Guide V61
45/63
Agent Management
CONFIDENTIAL 41
Last run start The start time of the last run for this Agent Activity.
Last run finish The end time of the last run for this Agent Activity.
Next run time The next time this Agent Activity is scheduled to run.
# of memory errors Indicates the number of times the Agent Activity was restarted due to
a Java OutOfMemoryError exception.
Exception
information
Any exception information that was generated when the Agent
Activity was disabled due to an error.
10.3 Agent Management Toolbar
Agent commands are listed in three groups, for working with a single activity, allactivities, and listing rules.
Sing le Acti vit y in Queue
Single activity commands operate on a single agent. Select a RuleSet and a single agent,
for example Pega- ProComandServi ceLevel Event s, and the command returns datadescribing just that agent.
Button Description
Start Starts the selected 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 the selected agent activity and then restarts it.
isAlive Shows the RuleSet name, queue number, and enabled status (true or
false) for the selected agent activity.
Query Displays information on the selected agent activity. It shows the same
information as the complete summary, but it isolates it in its ownwindow on the bottom of the screen.
Delay Delays the next start of this activity to permit Tracer startup. The
execution of an Agent Activity can go by too fast to enable the Tracer.
This button sets the Agent Activitys status to waiting. When the
Tracer is enabled, the activity can be started.
All Activities in Queue
The All Activities commands, which operate on all activities in a RuleSets queue, are
functionally similar to the single activity commands. Selecting any single activity in effectselects all activities for that RuleSet queue. Select a RuleSet and a single agent, for
example Pega- ProComandServi ceLevel Event s, and the command returns data
describing all Pega- ProComagents, and not just the selected one.
Button Description
Start Starts all agent activities in a RuleSet queue.
Stop Stops all agent activities in a 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 queue or RuleSet.
-
7/22/2019 SMA Ref Guide V61
46/63
Agent Management
42 CONFIDENTIAL
isAlive Shows for a selected agent activity whether all queued agent activities
for that RuleSet are enabled or disabled.
Query Displays information on all agent activities in a queue or RuleSet.
For example, selecting one activity in the Pega-RULES queue (in this case, 1) and
executing the All Activities in Queue > Query command splits the screen. Allactivities, enabled or disabled, are included.
Other Comm ands
The Query RuleSets command lists the names of all RuleSets for all agents. Scanningthis list is a quick way to see whether there is a problem with agents from a particularRuleSet. If there are noagents from one RuleSet, there may have been an issue with that
Rule.
-
7/22/2019 SMA Ref Guide V61
47/63
Agent Management
CONFIDENTIAL 43
10.4 System Queue Management
A system queue is a queue of work to be done by an agent. Syst em- Queue- is thequeue base class. Items sent to a queue are added to the database table
pr_sys_queues. Entries for all agent tasks are stored in this queue, and identified bythe agent RuleSet (which is also the name of the Agents rule) and the agent name.Items in the queue are assigned one of five statuses, defined in Table 19.
Use the System Queue Management tool to diagnose agent processing problems, for
example to follow the life cycle of items when developing a new agent.
Table 19: System Queue Status Values
Queue State Descrip tion
Scheduled An item has been created by a flow, activity, etc. and sent to the
queue, where it is waiting to be processed. No action has been taken
yet.
Broken-Process The agent tried to process an item but encountered an error. The
item is moved to Broken-Process for analysis.
Immediate An item has been created and sent to the queue, for processing by a
queued integration service component.
Now-Processing The item is locked and being worked on by an agent.
Success Item processing completed. Normally this status is not used in
production, as the general practice is to discard completed items
rather than save them in the database .
-
7/22/2019 SMA Ref Guide V61
48/63
Agent Management
44 CONFIDENTIAL
Table 20: System Queues Summary
Column Description
Queue Classes Number of classes represented by the queued items.
Oldest Item Time the first item in the queue was enqueued.
Newest Item Time the last item in the queue was enqueued.
Total Retries Total retries for all items of this status.
Item Count Queue size for this status.
Selecting a status and clicking Details displays the Details Summary for queued items ofthat status, as shown in the screen below for items of the Broken-Process status.
The toolbar commands on the Details Summary (Table 21) operate on a single item
selected from the summary. Not all commands are valid for items of all statuses. Thebuttons are dimmed when commands are not available. Table 22 defines the DetailsSummary fields.
-
7/22/2019 SMA Ref Guide V61
49/