Discussion
Pegasystems Inc.
JP
Last activity: 27 Feb 2024 5:22 EST
Understanding PegaRULES logs
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.
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.
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. |
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. |
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. |
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".
* 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****