Hi,

Pega Platform uses Apache Log4j for logging service internally and it was upgraded from Log4j 1 to Log4j 2 as of Pega 7.3 for better performance and flexibility. As a result of this upgrade, the prlogging.xml file has been replaced with prlog4j2.xml. In this post, I am sharing things I know about Pega logs and how to customize it.

1. Pega log files

Below is the list of log files that Pega produces. The defaulted log directory path is %CATALINA_HOME%\work\Catalina\localhost\prweb if you are using Tomcat.

2. Logging Level

Below is a list of logging level, listed from highest (most severe) to lowest (least severe), except for "ALERT". Some screens or Help have different orders - for example, you may find "ALERT" between "ERROR" and "WARN" but I think it is a bit misleading. "ALERT" is special because it is the only logging level created by Pega and outputted into a separate PegaRULES-ALERT.log file while all others are Log4j out-of-the-box logging level, outputted into a PegaRULES.log file. "ALERT" is by nature different from the rest and should be treated separately.

Developers can print logs using two approaches below. Be noted that "ALERT" can't be used in either of approach.

(1) Log-Message method in an activity You can specify 5 logging level - "Error", "Warn", "Info", "InfoForced", and "Debug".

(2) oLog in a Java step You can specify 6 logging level - "fatal", "error", "warn", "info", "infoForced", and "debug".

Now, just because developer specifies a certain logging level, doesn't mean the log is actually outputted. Let's say, some developer writes below code, intending to output all logging level.

However, against expectations, above code prints only three lines of message; that come from "fatal", "error", and "infoForced". Other three lines of code, "warn", "info", and "debug" are ignored. This is because default logging level at Log4j is "Error". Any logs that have "Error" or "Fatal" can be outputted. "InfoForced" is a special logging level that can forcibly log "Info" regardless of the settings. Let me explain how this works in the following section.

3. Three layers of logging level settings

The table below explains three layers of logging level settings, and it is listed in order of high to low priority. That means, if the same settings exist in all three layers, the one in Individual Logger is applied.

4. How to customize PegaRULES log

prlog4j2.xml, is a Pega version of log4j.xml. For customization, there are not really Pega specific settings and it basically follows Log4j 2 manner. So if you have any specific requirements you can look up Apache Log4j 2 documentation. In this section I will summarize a couple of use cases that are frequently asked. FYI, the defaulted Pega logging specifications are:

• The log files are created at %CATALINA_HOME%\work\Catalina\localhost\prweb directory.
• PegaRULES.log is archived as .gz (ex. PegaRULES-MM-DD-YYYY-1.log.gz) and cleared daily when time passes midnight.
• If file size reaches 250MB in a day, the sequence number is incremented and archived as .gz (ex. PegaRULES-MM-DD-YYYY-2.log.gz).
• If file is rotated 20 times a day, archived file starts being deleted from the oldest.

4-1. Changing logging level of Individual Logger

To change logging level for Individual Logger, it is more common to do this from Dev Studio, but the change is rolled back when the app node restarts. Some Dev environment reboots often, and in that case developers should redo the settings, which could be painful. If you do this from prlog4j2.xml, the changes remains even after system restarts. Below is a sample when you set "OIDCClientHandler" logger to be "All".

* If you want to know the logger name of Activity, you can select "View Java" from Actions menu in the rule form. In below example, logger name is "Rule_Obj_Activity.Test.MyCo_MyApp_Work_PurchaseRequest.Action".

4-2. Changing the log directory path

To change the defaulted log directory path, modify fileName in <RollingRandomAccessFile> tag. If you want to also change it for archived file, modify filePattern as well. Below is a sample to change it to "C:\MyDir".

Actually you can accomplish this by adding -DPega.logdir in JVM options in setenv.sh (bat) as below. I recommend this approach as you don't have to maintain prlog4j.xml.

4-3. Changing the log file name

Similarly to 4-2, modify fileName and filePattern in <RollingRandomAccessFile> tag. Below is a sample to change it to PegaBLUE instead of PegaRULES.

4-4. Deleting old logs

Some people may delete old logs by shell scripts or operation management software but this can be easily done by adding <Delete> tag in prlog4j2.xml. Below is a sample to delete log files that are older than 7 days.

4-5. Changing rotation specification

The specification of rotation explained earlier is accomplished by time based policy (TimeBasedTriggeringPolicy) and size based policy (SizeBasedTriggeringPolicy).

4-5-1. TimeBasedTriggeringPolicy

Pega's default time based rotation is daily basis, and this is because in filePattern, {MM-dd-yyyy} is specified. When the minimum timespan, dd (date) changes at midnight (00:00), the archive is created. So if you change this settings to {MM-yyyy}, it will be monthly basis, and if you change it to {MM-dd-HH-mm-yyyy}, it will be minute basis. If you want to disable time based policy, you can comment out <TimeBasedTriggeringPolicy>. 

4-5-2. SizeBasedTriggeringPolicy

Pega's default size base policy is 250MB. You can change this value if it's preferred. If you want to disable size base policy, you can comment out <SizeBasedTriggeringPolicy>.

4-5-3. DefaultRolloverStrategy

Pega's default maximum number of files that can be archived is 20. If rotation occurs 21 times a day, the oldest archive file gets deleted. You can change this value, but you can't make it unlimited - if you skip this size or comment out this tag, Log4j's default, "7" is applied.

* It is not recommended to disable both time base policy and size base policy, as there is no rotation, and PegaRULES.log will get very large. The file may not be even openable by editor, or it may lead to full disk space situation.

Thanks,

***Edited by Moderator Kayla to update Platform Capability tags****