# Understanding PegaRULES logs

**URL:** <https://forums.pega.com/t/understanding-pegarules-logs/1314>\
**Category:** General\
**Tags:** java-and-activities, 8-4-1\
**Created:** [April 13, 2021, 4:19pm UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314 "2021-04-13T16:19:21Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![KenshoTsuchihashi](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/kenshotsuchihashi/32/16482_2.png) [@KenshoTsuchihashi](https://forums.pega.com/u/KenshoTsuchihashi)\
**Post date:** [April 13, 2021, 4:19pm UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/1 "2021-04-13T16:19:21Z")

</div>

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.

| 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. |
| 6 | CLUSTER | PegaCLUSTER.log |   
  
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. |
| 8 | MOBILE | PegaMOBILE.log | - |
| 9 | MOBILEBUILD | PegaMOBILEBUILD.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.

 ![oLog.png](https://pega1.discourse-cdn.com/pega/original/2X/d/dd030ee33764133e73b4200316c0812487858ea5.png)

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.png](https://pega1.discourse-cdn.com/pega/original/2X/5/5330e1fb2dc9a21956449c918329060cea4f558e.png)

**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.png | 1385x217](upload://zAEmziHrLb8mvDvHnEiHDmwbUQE.png)  
  
 | Memory |
| (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.png | 1435x545](upload://ebf7v2maNfG9KOD8i0FXj0Ad3CV.png)  
  
 | Database |
| (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 tag, which means “Error” is applied implicitly in Log4j. If you modify it as , 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.png | 974x184](upload://bwE1tCg1q9Sy3aSuIMcGDhrUjPv.png)  
  
 | File |

**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.png](https://pega1.discourse-cdn.com/pega/original/2X/e/ea423817eb4ee171f74708e21eb75f3e6bb4b6f3.png)

- 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.png](https://pega1.discourse-cdn.com/pega/original/2X/5/5c4a915e7b3fbb799b11f54be00b402401737348.png) ![How to figure Individual Logger Name from View Java.png](https://pega1.discourse-cdn.com/pega/original/2X/6/6087dd7a75ef206dfc8509a180828968958d5f09.png)

**4-2. Changing the log directory path**

To change the defaulted log directory path, modify _fileName_ in 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.png](https://pega1.discourse-cdn.com/pega/original/2X/2/2ecee8d0f73ba8a64578083cd528c2d4e13bbaaf.png)

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.

 ![setenv.png](https://pega1.discourse-cdn.com/pega/original/2X/f/fef47c19f5a406b59381091f23a1060843ded7e5.png)

**4-3. Changing the log file name**

Similarly to 4-2, modify _fileName_ and _filePattern_ in tag. Below is a sample to change it to PegaBLUE instead of PegaRULES.

 ![File name change in prlog4j2.png](https://pega1.discourse-cdn.com/pega/original/2X/8/8c8f0fb4e8e259e61ad7d59b0084ee14cd078cca.png)

**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 tag in prlog4j2.xml. Below is a sample to delete log files that are older than 7 days.

 ![Delete Old Logs by prlog4j2.png](https://pega1.discourse-cdn.com/pega/original/2X/4/4a655f154779e81a73c48e4ea88ec81120e6a806.png)

**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.png](https://pega1.discourse-cdn.com/pega/original/2X/d/df9befacbb37230e5bf8d51d596b80d33d222b5e.png)

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

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

**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** _\*

---

<div class="post-metadata">

**Author:** ![RaviKumarP17776803](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/ravikumarp17776803/32/19855_2.png) [@RaviKumarP17776803](https://forums.pega.com/u/RaviKumarP17776803)\
**Post date:** [April 14, 2021, 11:38pm UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/2 "2021-04-14T23:38:29Z")

</div>

@KenshoTsuchihashi Nice post to understand logs concept well in Pega.

---

<div class="post-metadata">

**Author:** ![VishnuBoyidi](https://avatars.discourse-cdn.com/v4/letter/v/9e8a1a/32.png) [@VishnuBoyidi](https://forums.pega.com/u/VishnuBoyidi)\
**Post date:** [March 6, 2023, 11:04am UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/3 "2023-03-06T11:04:55Z")

</div>

@KenshoTsuchihashi Awesome post

---

<div class="post-metadata">

**Author:** ![Suraj](https://avatars.discourse-cdn.com/v4/letter/s/ecccb3/32.png) [@Suraj](https://forums.pega.com/u/Suraj)\
**Post date:** [March 13, 2023, 9:07am UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/4 "2023-03-13T09:07:02Z")

</div>

@KenshoTsuchihashi Thanks for the post, can you pls help us understand how to integrate these logs with Splunk?

---

<div class="post-metadata">

**Author:** ![BrahmeshTech](https://avatars.discourse-cdn.com/v4/letter/b/13edae/32.png) [@BrahmeshTech](https://forums.pega.com/u/BrahmeshTech)\
**Post date:** [February 27, 2024, 10:22am UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/5 "2024-02-27T10:22:23Z")

</div>

@KenshoTsuchihashi

We don’t want to print UserID in logs due to some security reason and need to display another internal id/user name of the customer instead of userID .

I see the following default pattern layout in log4j2.xml .Is it possible to send/configure custom parameters to log4j2.xml to print the log messages in desired pattern.

\<§§\>%d [%20.20t] [%10.10X{pegathread}] [%20.20X{tenantid}] [%20.20X{app}] (%30.30c{3}) %-5p %X{stack} %X\*\*{userid}\*\* - %m%n

---

<div class="post-metadata">

**Author:** ![Kishore\_Sanagapalli](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/kishore_sanagapalli/32/4954_2.png) [@Kishore\_Sanagapalli](https://forums.pega.com/u/Kishore_Sanagapalli)\
**Post date:** [November 25, 2024, 12:34pm UTC](https://forums.pega.com/t/understanding-pegarules-logs/1314/6 "2024-11-25T12:34:36Z")

</div>

@KenshoTsuchihashi

I implemented Pega Application Logs retention in our environment similar passion but logs will be generated with pod name as prefix of log name successfully. But Deleting the aged logs is not worked for us as per your suggestion in the article.

Please advise.
