Summary

This article explains how to install and use the PegaRULES Log Analyzer (PLA) tool. For an overview of PLA, see Understanding the PegaRULES Log Analyzer.

Suggested Approach

PLA is designed as a single-user Java application on a Windows XP workstation. PLA runs on the Apache Tomcat application server and the Apache Derby database engine, which is an all-Java open-source relational database. For more information about Derby, see http://db.apache.org/derby/. Note that your disk space requirements will be in direct relation to the size of the logs you plan to import into this database.

PLA integrates with Microsoft Excel 2000 or later.

PRPC Versions and PLA

PegaRULES Log Analyzer can be used on V5.1 SP2 and later. For versions prior to V5.4 you may need to install a product patch and update a parameter line in your prlogging.xml file. For instructions, see How to upgrade V5.x systems to enable PLA functionality.

Important: To help Pegasystems ensure your success with PLA, report software issues to Pegasystems.

Installing and starting PLA

You can use either of the following installation zip files:

• PLA_With_Jre.zip (84 MB) — Contains Tomcat, a deployed application, and Java 1.6.
• PLA_WithOut_Jre.zip (11 MB) — Contains Tomcat and a deployed application. This installation requires Java 1.5 JRE or greater available by the JAVA_HOME variable.

To install and start PLA, do the following:

1. Go to Pega Marketplace: PegaRULES Log Analyzer and click the appropriate file link. The following window appears:

   

2. Click Save and specify the folder into which you want to save the file.
3. When the save is complete, navigate to your PLA folder and extract the zip file to its current location. Select the Use Folder Names checkbox in WinZip to retain the path structure in the zip file.
4. When the extract is complete, open the PLA folder and double-click startup.bat to start Tomcat.
5. After Tomcat has successfully started, double-click to start the application on your workstation.

    

When you first start PLA, the Home view appears in a window:

This is the view in which you upload alert, Pega (system), and GC log data. When you have completed an upload, the window populates the table with statistics that flag issues requiring immediate attention. They include:

• Errors, Debug, and Exceptions — Should be 0
• Critical alerts — Should be 0
• Total alerts — This figure includes warning alerts. If the number is large, they should be evaluated for their impact on production before being considered acceptable
• Excessive GC time — Should not exceed 2%

When you start PLA for the first time, no data appears, because you have not yet uploaded data into the Derby database.

Before you begin

Copy into a local directory the log files you plan to load into PLA. To obtain current Pega and Alert log files, do any of the following:

• In the System Management application, open the Log Files selection in the Logging and Tracing section and download the text versions.
• 
• Select Tools > Log Files in the developer portal and download the text version.
• 
• Retrieve GC log data from your application server system directory. If necessary, you can retrieve from the server old Alert and Pega log data not directly available from Process Commander.

Upload log files

To load log data, do the following in the Manage Data bar:

1. 1. Click on the type of log you want to upload. When you click Alert, the following fields appear:

      

      The Purge Data Before Load check box is selected by default. This means that when you upload a new log file, all alert log data in the database is deleted. If you want to keep the existing data, uncheck the box. In this example, there is no existing data to purge.

   2. Use the Browsebutton to navigate to the log file you want to upload. It must be a text file, not a zip file. The file size cannot exceed 500MB. Here is an example:

      

   3. Click the Upload Alerts button. Depending upon the size of the log, processing may take a minute or more. Here are the results of the upload:

1. 1. The Home view contains a table organized into rows of log dates and columns of log types. In this example, there are 28 and 66 critical alerts for April 15 and 16, respectively. Critical alerts are PEGA0004, PEGA0017, PEGA0019, PEGA0026, and PEGA0028. There should be no critical alerts.

1. 1. Note also that on those dates, the total number of alerts (critical and warnings) exceeded 4000 and 5500, respectively. These are unusually large numbers and should be investigated before putting the application into production. To quickly identify the alerts with the greatest frequency, you can use the Alert Summary report (described later in this article).

1. 1. Use the options in the left panel to open various reports.

Alerts

For a list view of the alert data, click Alerts on the left panel. Here is an example:

You can sort the report by any of the columns except for Msg ID. To bring the critical issues to the top of the report, sort by Severity. To display information about the type of alert, click on the link in the Msg ID column.

Tip: If there is a large number of rows in the report, you can display more rows per page by increasing the default value of 20 in the field and clicking Refresh on the top of the report.

Click on a row to display details about the alert as shown here:

You can use the tabs at the bottom of the page to display PAL data, trace list information, and so on.

Alert Summary

For a graphical representation of the alert data, click Alert Summary in the left panel.



In this example, the number of alerts in categories Browser Time (PEGA0001) and DB List Rows (PEGA0027) were unusually high.
 

• • To take a closer look, click the graph or on the Click for Detail link to return to the list view report. Sort by Category to group them and determine a commonality among them. In the above example PEGA0027 alert, many users were using a query that contains 12 properties (see Line row), which may indicate that the query should be reconfigured to reduce the number of properties.
  • Click System in the Manage Data bar to upload a Pega (system) log. The fields are the same as those used for uploading the Alert log. Here are the results:

• There are 16 and 15 exceptions and 2,523 and 5,130 errors for April 15 and 16, respectively. There should be no errors or exceptions.

System Summary

For a summary view of the system log data, which includes error, debug, warn, and exception totals, click System Summary in the left panel. Here is an example:

Exceptions

For a list view of the exceptions, click Exceptions in the left panel. Here is an example:

You can click on an exception in the list to display exception details. You can sort on either column.

Garbage collection data

Click GC in the Manage Data bar to upload a GC log. Select the appropriate JVM type and enter a start time, if necessary. Note the required option settings for the type of JVM type you are uploading. Here is an example:

Here are the results:

The % GC time for April 15 was .9%, which is acceptable. On April 16, it was 2.6%, which is not acceptable.

GC Summary

For a summary description of the GC log, which includes the type, count, and time(s), click GC Summary in the left panel. This option also provides a graphical representation of the memory used after GC, GC count by day, and GC time by day.

GC Data

For a list view of the GC data, select GC Data. This report includes the event time, type, duration, and so on. You can sort on any of the columns.

Tip:For Sun JVM's that do not support the PrintGCDateStamps option, loading a group of GC logs can help you correlate Alerts and Exceptions with GC behavior.

Exporting PLA data to an Excel spreadsheet

You can export the log data to a pre-configured Excel spreadsheet. You can export log data for a single date or for all log dates by clicking All in the Manage Data bar and clicking Export All.

The following describes the export process and the results using a single log date:

1. 1. In the Home view table, click the button for the date row you want to export. This message appears:

1. 1. The following window appears:

1. 1. Click Open. A read-only populated Excel spreadsheet opens.

Note

1. 1. : If the spreadsheet contains no data, it may be due to an Excel macro security setting. To enable macros in the PLA spreadsheet, open the Excel Options window, open the Trust Center Settings, and set the radio button in Macro Settings to allow digitally signed macros as shown here:

The spreadsheet organizes the data into the following reports:

• Alerts
• Alert Summary
• Critical Alerts
• Exception
• Exception Summary
• Garbage
• Garbage Summary

These correspond to the view options in the PLA window (with the addition of a Critical Alerts list report). Here is an example of the Critical Alerts report:

By default, the alert instances are organized by category and include KPIVALUE, KPITHRESHOLD, and SEVERITY values. You can use the PivotTable Field List to add other fields.

For more information about the spreadsheet and instructions on how to use it, click the Import tab to display this page:

There are four buttons:

• Import — Re-run the import process from the data directory.
• Clear Data — Delete all data from the spreadsheet.
• Generate Pivots — Turns on PivotTable functionality. By default, PivotTables are turned on when the data is exported to Excel.
• Clear Pivots — Turns off the PivotTables, which significantly reduces the size of the Excel file. This is useful when distributing it to other users or when storing it for later use. Users can turn on PivotTables by clicking Generate Pivots.

Creating and managing log profiles

You can load log files into discrete database instances called log profiles. This enables you to organize log results to suit your requirements. When you first use PLA, there is one profile (database instance) called Default.

To create additional log profiles, do the following:

1. Click the Manage Profiles option in the left panel or the Add button in the Current Profile bar.
   
   
    
2. Enter a profile name of up to 64 alphanumeric characters in the Add a profilefield. If you include spaces, they are replaced with an underscore ( _ ) character.

    

3. Click Add. Here is an example:

   

4. The Current Profilefield displays the new profile. When you are in the Home view, you use the drop-down menu in this field to specify the profile into which you want to import data.

   Note: When you import data and Purge Data Before Load is selected, only the data in the current profile database instance is purged.

5. To delete a profile, click the Manage Profiles option, select the profile you want to delete from the Select a profile pull-down menu, and click Delete. All the data associated with the profile is purged.

PLA performance and purging data

You may notice that as you import and save data over a number of sessions, the PLA application becomes progressively slower due to an increasingly large number of rows in the database (or database instance). For example, paging through an alerts view report may be very slow. It is suggested that you purge data when performance becomes an issue. You can purge data by doing any of the following:

• Purge log data for a specific type of log within a log profile:
  1. Select the profile in the Current Profile field.
  2. Select Alert, system, or GC in the Manage Data bar on the Home view.
  3. Click the Purge Alerts button.
• Purge log data for a specific date within a log profile:
  1. Select the profile in the Current Profile field.
  2. Select Alert, System, or GC in the Manage Data bar on the Home view.
  3. Click the button on the row for the date you want to purge.
• Purge all of the log data within a log profile:
• 1. Select the profile in the Current Profile field.
  2. Click All in the Manage Data bar.
  3. Click Purge All.
• Delete a log profile:
• 1. Select the Manage Profiles option.
  2. Select the profile from the pull-down list.
  3. Click Delete.
• Delete all log profiles (except Default):
• 1. Select the Manage Profiles option.
  2. Click Delete All.
  Note: Deleting a log profile does not affect the size or performance of the other profiles. You cannot delete the Default profile.