Change the format of messages

You can change the format of messages by adjusting the prlogging.xml file output format. For example, you can create a console output format that keeps data aligned in columns, as well as having valid time stamps.

Under WebSphere, the "double spacing" of output on the console can be eliminated by removing the final "%n" from the CONSOLE ConversionPattern (in bold in the text below). However, if system.out is then captured to a file with the property set (as described in the Capture Console Output section), there will be no line feeds in that file.

This does not change the format of the log file to which WebSphere copies the console output; it only eliminates the extra blank lines on the console display.

Review the prlogging.xml example at the bottom of the topic, Customizing logs. (The example also contains examples of one of the file appenders.)

Roll log files daily

The prlogging.xml file contains settings that can be used to automatically "roll" the log file on a daily basis, creating separate files for each day. You can specify monthly, weekly, half-daily, daily, hourly, or minute rollover schedules.

1. In the prlogging.xml file, locate the <appender name="ASYNC"> section. Add the following reference:

   <appender-ref ref="dailyRollFile"/>

2. Insert the following code between the last appender entry and the first category entry:

   <appender name="dailyRollFile"
               class="com.pega.apache.log4j.DailyRollingFileAppender">
     ​<param name="DatePattern" value="'.'yyyy-MM-dd-HH-mm"/>
     <param name="File" value="logs/PegaRULES-.log"/>
     <layout class="com.pega.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d{ABSOLUTE} [%20.20t] (%30.30c{3}) %-5p -
               %m%n"/>
     </layout>
     </appender>

The DatePattern value yy-MM-dd-HH-mm causes the log to be rolled over at the beginning of every minute. Settings should follow the SimpleDateFormat.

Get more (or fewer) messages from Whens, Models, and Activities

The prlogging.xml file contains settings that you can use to control the level of messages reported. In this file, the <category> listings indicate Java classes to which logins should be applied, activities, when rules, and models. The format of the listing is slightly different for each of these classes.

Within a category, there are five classes or priorities of messages. In decreasing order of severity, these are:

• fatal
• error
• warn
• info
• debug

For each category, specify one of the above five priorities to be displayed. For any issues that arise in the code execution, messages at or above the specified priority will be displayed in the output. For example:

• If the level "error" is specified in the prlogging.xml file, messages of priority "error" and "fatal" would be displayed.
• If the level "info" is chosen, messages of priority "info", "warn", "error", and "fatal" would be displayed.

For Java classes, specify the fully qualified package and class name in the log4j file, along with the priority value:

<category name=" com.pega.pegarules.engine.context ">

<priority value ="error" />

</category>

If the system receives a message for any classes in or below that package and class name, it includes messages of the specified priority in the log output. Using the above example, messages of type "error" and "fatal" are displayed for these Java classes (and others):

• com.pega.pegarules.engine.context.Agent
• com.pega.pegarules.engine.context.Authentication
• com.pega.pegarules.engine.context.Authorization
• com.pega.pegarules.engine.context.InitialConfiguration
• com.pega.pegarules.engine.context.PageDirectoryImpl

The priority value specified above is not applied to:

com.pega.pegarules.engine.clipboard.BasicPage

because this class does not include the .context class level.

You can change values within a class level:

<category name="com.pega.pegarules.engine.context">

<priority value ="error" />

</category>

<category name="com.pega.pegarules.engine.context.Agent">

<priority value ="info" />

</category>

In this example, all the classes under com.pega.pegarules.engine.context have a priority value of "error," except for the class com.pega.pegarules.engine.context.Agent, which would have its own priority level of "info."

Errors also can be specified by using the Pega Platform class name instead of the Java class name. If you need to see messages for an activity named "Validate", which was created on the Pega Platform Class Work-General, you can specify this activity in the log4j file.

The format for the Pega Platform Java class instances is a three-part name, separated by periods.

• The leftmost part refers to whether the object in question is an activity, a when rule, or a model. The name refers to the class of those objects: Rule-Obj-Activity, Rule-Obj-When, or Rule-Obj-Model, with underscores instead of hyphens.
• The middle portion of the reference is the actual name of the object (the activity, when block, or model).

• The final portion of the reference is the class on which the activity, when or model is defined. For the example above, the reference would be:

  Rule_Obj_Activity.Validate.Work_General

Adding this to the log4j file displays messages only for the Validate Activity that was defined for the class Work-General, and does not show Activities defined on other classes. If the final portion of the name was omitted (Rule_Obj_Activity.Validate), then messages for all Validate activities would print out, regardless of in what class they were defined. Likewise, if developers are interested in printing out messages for all Activities, they should use the first part of the reference (Rule_Obj_Activity), to get all messages for activities.

Because of the complexities of rule inheritance, it might not be possible to know exactly which class of activity will get selected; this setting in the log4j file lets you see the messages for a particular instance name, regardless of where it is in the rule resolution hierarchy, so tracing and debugging can be done.

If warn is enabled when using the Microsoft SQL driver, the following warnings might be encountered:

• Database changed to PR3SQL​
• Changed database context to 'PR3SQL.'
• Language changed to us_english

You can ignore these routine messages sent by Microsoft SQL Server when connecting.

Capture console output in a file

The LogHelper.java class provides a log and trace facility to applications. It is implemented as a wrapper around the Jakarta Log4J logging facility to enable the underlying logging framework to be changed without rewriting application code.

This does not prevent the information from also being written to the console.

Example PRLOGGING.XML with dailyRoleFile and priority changes: