SMA Ref Guide V61

7/22/2019 SMA Ref Guide V61

1/63

SMA Standard Tools

System Management Application Reference Guide

PegaRULES Process Commander V6.1


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


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


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


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)


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/63


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.


8/63


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.


9/63


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.


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


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 .


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


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


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.


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.


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.


17/63


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.


18/63


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.


19/63


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.


20/63


16 CONFIDENTIAL


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.


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.


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


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.


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.


26/63


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.


27/63


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.


28/63


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.


29/63


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.


30/63


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.


31/63


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.


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.


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.


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


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


36/63

System Management

32 CONFIDENTIAL

Cp1252.


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


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.


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.


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.


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.


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.


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.


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).


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.


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.


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 .


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.


49/

Documents

SMA Ref Guide V61