Administration Q

Administration Q

SYSTEM DEBUGGING

Tools:

• Clipboard
• Tracer
• UI Inspector
• Log
• Remote Logging app

Logs:

• ALERTSECUTITY
• BIX
• ALERT
• Pega
• (all logs)

Clipboard 

The clipboard tool arranges the top level pages into four categories.

• User Pages – this contains the top-level pages created by the requestor during normal processing, sorted alphabetically by page name.  For example, an execution of a “Page-New” method in an activity results in a new page being added to this category.
• Data Pages – this contains all the data pages instantiated in the system.  See the lessons on data pages for information on their usage.
• Linked Property Pages – this contains all the pages created by a linked property.  See the lesson on properties for information on their usage.
• System Pages – this contains special, reserved pages the system relies on to function.  Within this category, three pages are always present.
• pxThread – this contains the information about the current PRThread.
• pxRequestor – this contains the information about the requestor and HTTP protocol parameters.
• pxProcess – this contains information about the server’s Java Virtual Machine and the operating system.

Additional pages that contain information on the access group, application rule, operator ID, organization, org division and org unit may appear as required.  Guest users do not have these pages as they’re part of the authentication for a named user.

The clipboard provides us a menu through which pages can quickly be manipulated.

The menu provides the commonly used options of Edit and Refresh as separate buttons.  The rest of the options are available by clicking on the Actions button.

• Edit - allows us to update values on the page.  This is useful to prepopulate data during testing that the system might not currently process.  For example, if we’re calculating a full name out of the user’s first and last names, we can enter those values here to test our calculation instead of waiting for the screen to be built that lets the user enter them.  Of course, our testing shouldn’t end here.  Don’t forget to also test once the screen has been created!
• Refresh - gets the latest values from the system.  Since the clipboard opens in a separate screen, it is possible for the system to continue processing even though the local copy we have on our desktop does not match the one at the server.  As a best practice, if the clipboard is left open and the system has moved screens, we should use the refresh button to update our view of the clipboard before examining any values.
• Show XML - provides a raw XML view of the entire page.  This is useful to see the entire page, including the embedded pages, on one screen.  It also has the added benefit of displaying any of the properties that start with ‘pz’ which are reserved by the system and therefore not shown on the clipboard.
• Execute Activity - allows us to run an activity using this page as its step page.  This provides the same functionality as the run button available when an activity is open in the designer studio.

Above the menu we find the clipboard’s toolbar.
This toolbar provides us a search box to locate values on any clipboard page, a tools menu with the options Analyze and Collect Details.  These are advanced tools used to track approximate sizes of pages on the clipboard.

PRPC requires users to have access to the @baseclass.clipboardViewer privilege in order to be allowed to access the Clipboard tool. The Action menu items that update the clipboard contents are available only to users who hold the @baseclass.clipboardViewerUpdate privilege.  The standard access roles are listed below and all provide access to these privileges:

• PegaRULES:SysAdm4
• PegaRULES:SysArch4
• PegaRULES:ProArch4
• any <application name>:Administrator access roles created when we run Application Express

Generic users should not be granted any of these roles if they do not require access to the clipboard.

Tracer

The tracer displays an area for the results and a toolbar.  We’re going to take a look at the toolbar first.

• Pause/Play – this icon starts or stops the tracer.  Pause displays when the tracer is currently capturing events and play is displayed when the tracer is not.
• Clear – this icon removes the results visible in the window.  This is useful when restarting the tracer.
• Settings – this icon allows us to configure the options for the tracer.  We’ll review the options a little later in this lesson.
• Breakpoints – this icon allows us to define a breakpoint for the tracer.  This is useful when we want to automatically pause the execution at a predefined point in the process to closely examine the system.
• Watch – similar to breakpoints, this allows us to define when to automatically pause the tracer.  With watch we define to pause when the value of a property changes, instead of a predefined point.  This is useful to track down where a value gets set if we are unfamiliar with the process setting that value.
• Remote Tracer – this allows us to select other requestors to trace.  This is useful for debugging from one system while logged in as a test user in another system.  We’ll discuss more about this option a little later in this lesson.
• Save – this saves a copy of the tracer results for analysis in a separate application called Tracer Viewer.  This application will be discussed later in this lesson.

The tracer provides us with many options to control the output to the tracer.  The first thing to note is that the Tracer Settings are broken into several categories.  These are all described in detail in the help files, but let’s take a high level look at some of the more commonly used ones.

The events to trace and break conditions category provides us with the ability to select some of the more critical events, such as data transforms and when rules.  Unless we need the data, we recommend using the defaults as selected.

The next set of options is the Break Conditions.  This causes the tracer to automatically pause if one of these is encountered.  Again, unless needed, it is recommended that we use the defaults as selected.

The last set of options can affect the performance of the tracer.  Tracer by itself can greatly impact the system performance.

• Abbreviate Events – this option reduces the performance impact, but sacrifices keeping the clipboard detail.  When this is selected the step pages are not available and we cannot view the values associated with their properties.
• Expand Java Pages – this is only useful if the system contains any properties of mode Java Page.  This option should be turned off if such properties are not in use.
• Local Variables – this option provides the means to view the local variables which are not available from the parameter page.  This option should only be turned on when we specifically need to debug an issue with a local variable.

The next category is event types.  This category provides additional, optional events that we can trace.  These events can be things like Flow, Declare Expression or DB Query.  By selecting one of these anytime the associated rule type is executed an event is written to the tracer.  The event type Stream Rules encompasses all UI rules, such as a Harness or a Section.

At the top of the list, we have the option to add additional event types.  Since the most common types are already provided, we should not need to use this capability except as directed by your Lead System Architect.

The next big category is the rulesets to trace.  This category allows us to eliminate some rulesets from the tracer output, to improve its performance.  The entire ruleset stack is available to us, but as a general rule we shouldn’t need to trace any of the Pega* rulesets.  Our primary concern with debugging is our rules, so by removing these rulesets we can potentially save thousands of lines of results.

The tracer only provides the step page and the parameter page by default for each event it traces.  We have the option of tracking additional named pages when necessary.  This capability is very powerful, but comes at the cost to performance.  When one of these is enabled the system requires much more memory to keep a record of this additional page at every step of every event.  It should only be used when there is interactions between multiple pages that cannot be traced separately.  This option is not available if Abbreviate Events is selected.

Remote Logging

Via the System Management Application, we have the ability to perform remote logging.  Remote logging establishes a connection between the server and a standalone application running on our desktop.  To run the remote logger, first access the SMA and select Remote Logging under the Logging and Tracing category.

From this page, download and extract the log4j socket server, available at the bottom of the page.  Once this has been extracted and run, we’re presented with the remote logger user interface.

Once this is running, we can establish the connection by returning the SMA and specifying the host as our system, the port as shown in the first line of the logger (default is 8887) and any filters.  The filters work the same way as the Log File tool in the developer studio.

A really nice feature of the remote logger is that it is updated near real-time, without having to constantly download the log files.  This allows us to watch the log files as we’re stepping through a process and identify when certain exceptions or events occur.  Remember that this is only near real-time as the log4j appenders work in the background, so it’s important not to jump through our steps too fast and allow the remote logger to keep up with us.