Close popover
Kensho Tsuchihashi (KenshoTsuchihashi)
Project Delivery Leader
Pegasystems Inc.
KenshoTsuchihashi Member since 2010 137 posts
Posted: 4 weeks 1 day ago
Last activity: 3 weeks 6 days ago

Understanding PegaRULES logs



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.

No Name File Name Description
1 PEGA PegaRULES.log The PEGA log contains warnings, errors, and information messages about internal operations.
2 ALERT PegaRULES-ALERT.log The ALERT log contains performance-related alerts.
3 ALERTSECURITY PegaRULES-ALERTSECURITY.log The ALERTSECURITY log contains alerts (identified by the prefix SECU) that suggest improper configuration of Internet Application Composer facilities, or overt attempts to bypass system security features through URL tampering.
4 BIX PegaBIX.log

The BIX log is created by the Business Intelligence Exchange during extract operations.

5 SECURITYEVENT PegaRULES-SecurityEvent.log The SECURITYEVENT log includes actions performed by any requestor who accesses the application, data accesses or changes, security policies changes or security-related rules or landing pages, and so on.

The CLUSTER log contains information about the setup and run-time behavior of the cluster.

7 DATAFLOW PegaDATAFLOW.log The DATAFLOW log contains Kafka related data flow log.
10 USAGEMETRICS PegaUSAGE.json.log -


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.

No Logging Level Description
1 OFF Turns off logging.
2 ALERT Pega Platform-specific messages that indicate that a performance threshold has been exceeded, or that an event has occurred that has an adverse performance implication.
3 FATAL Indicates severe errors that can cause the application to terminate.
4 ERROR Indicates serious errors that might allow the application to continue running.
5 WARN Indicates situations that might have an adverse performance implication.
6 INFO Indicates that a run-time event, such as startup or shutdown, has occurred.
7 DEBUG Indicates informational events useful for debugging.
8 ALL Indicates that all messages are logged

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.

oLog output


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.

No Layer Description Managed by Expiration
(1) Individual Logger

Individual Logger is the smallest granularity of the three layer. For example, if you are having an issue with OpenID Connect authentication process, you can change the logging level of ” com.pega.pegarules.integration.engine.internal.auth.oidc.OIDCClientHandler" from the defaulted "Error" to "All" or "Debug" to get useful information for debugging. This settings can be done from Dev Studio. Since this is managed by memory, it won't be reflected to other app nodes. Also, the change remains effective until the app node is stopped. If you want to keep the settings after system restart, do it from (3) prlog4j2.xml.

Individual Logger

Memory Ineffective after system restart
(2) Log Category

Log Category is Pega's own implementation and it can bundle multiple Individual Loggers. For example, out-of-the-box Log Category "pxIntegration.Service.REST" contains the following Individual Loggers: - com.pega.pegarules.integration.engine.internal.services.http.HTTPService - com.pega.pegarules.integration.engine.internal.services.ServiceAPI - com.pega.pegarules.integration.engine.internal.util.ServiceAPIUtils

You can change the logging level of this Log Category from Admin Studio. Once you change it to a certain level, it automatically updates all Individual Loggers and it is reflected in above (1) screen on Dev Studio. Log Category is an instance of Data-Logger-Category class and it is managed by database table. So unlike (1), the change will be applied on all app nodes and remains effective even after system restart. In 8.4.1, 37 out-of-the-box instances are inserted with Pega Platform installation. Also you can create your own Log Category.

Admin Studio Log Categories

Database Remains effective after system restart
(3) prlog4j2.xml

If no entry is found in (1) and (2), the default of prlog4j2.xml is applied. Below is the screenshot of the default prlog4j2.xml. There is no level specified in the <asyncRoot> tag, which means "Error" is applied implicitly in Log4j. If you modify it as <asyncRoot level="INFO">, the defaulted logging level becomes "INFO". Earlier sample code of oLog can then output "warn", and "info" without modifying (1) or (2). However, do not modify this level as changing this will output massive logs, and more importantly if you change it to "All" or "Debug", Pega will fail to start up. prlog4j2.xml is per node, and the change won't be reflected to other nodes.

Default Logging Level in prlog4j2.xml

File Remains effective after system restart


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

Individual Logger Settings in prlog4j2.xml

* 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".

View Java  How to figure Individual Logger Name from View Java


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

Directory path change in prlog4j2.xml

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.

File name change in prlog4j2.xml


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.

Delete Old Logs by prlog4j2.xml


4-5. Changing rotation specification

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

Rotation in prlog4j2.xml


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.




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

***Edited by Moderator: Pooja Gadige to add Developer Knowledge Share tag***
Pega Platform 8.4.1 Data Integration Java and Activities Developer Knowledge Share