Configuring and managing logs
|Description||An overview of logging tools in Pega Platform|
|Version as of||8.5|
|Capability/Industry Area||System Administration|
Pega Platform offers logging capabilities in line with industry standards and integrates well with the best industry logging tools and techniques. This design pattern introduces the concept of logging, its importance, and how Pega applications offer flexible customization options for different logging needs.
Logging is a fundamental part of any application, and every application has a different flavor of logging mechanism. A well-designed logging system is a huge utility for system administrators and developers, especially the support team. Logs save many valuable hours for both the support team and developers. As the end-users navigate through the portals and use a Pega application's features, the system invisibly builds a vault of event information (in the form of log entries), for system administrators and the support team.
Use case examples
During application development, while authoring the logic you might be unsure about how the state of the application is being manipulated. In this case, you could try logging the variables' values to a logfile and analyzing them. In a production application, if there is an unexpected behavior in a particular use case, enabling logging can give necessary insights about the cause of the issue and the further steps to take.
Setting up logging to enhance debugging and troubleshooting
Logs are extremely useful in diagnosing issues in any application, but optimal configuration of your logging tool sets you up for the quickest turnaround time on debugging issues in Pega Platform. Logs in Pega Platform can be configured, managed and viewed differently, depending on the deployment model of your application.
Pega Cloud manages application logs by using the popular ELK stack.
For more information, see Accessing server logs using Kibana.
On Premises or Pega Cloud Environments
Logging in Pega Platform is optimally configured so that that new files are created everyday, and older logs are archived to save disk space. Additionally, you can also configure ELK to analyze and manage your logs.
For more information, Configuring ELK for log management.
Configuring cluster-wide logging at runtime
Pega Platform can be configured for logging at runtime across an entire cluster, without the need for a server restart. This is accomplished by creation and customization of Log Category rules. A Log Category rule is a convenient means of grouping your loggers by feature, or by any specific purpose, such as for troubleshooting an issue. You can also set the log levels for each of the categories and for individual loggers.
For more information, see Understanding logs and log categories.
Creating log categories to configure what the system prints in the logs
Logging in Pega Platform uses Apache Log4j 2 under covers, and so the filtering of messages also works according to Log4j 2. The kinds of events that are captured in the logs can be configured through log-level settings. The following guidelines should be considered when configuring your logging settings:
- Create and configure log categories
- In previous releases of Pega Platform, in which logging categories were not available, customizing logs was accomplished by updating the
prlog4j2.xml files. If you upgrade to version 8.x or later, it is advisable to move these customizations to Log Category I.
- From Pega version 7.3.1 and upwards, the underlying logging framework has been enhanced. Thus,
prlogging.xmlcustomizations need to be moved to
prlog4j2.xml. It is recommended that you make use of Log Category rules to customize your logging requirements. However, under circumstances in which a new log file needs to be created for a special logging requirement,
prlog4j2.xmlneeds to be updated. For more guidelines, see Customizing prlog4j2.xml for custom logger.
- Pega Platform offers all of the logging levels offered by log4j2 viz., INFO, DEBUG, WARN, ERROR, FATAL and ALL. Additionally, there is a custom logging level ALERT, which is used internally by Pega Platform. For more information, see Understanding the log levels and their ordering
For quick viewing of logs localized to the node to which a developer or admin has logged in, follow the directions in the viewing logs Community article.
Viewing logs offline for extensive log analysis
You can also download the log files and view them offline by using the Pega-LogViewer. The Pega-LogViewer is enriched with filters and other capabilities that greatly aid log viewing. You can download the tool here: Pega Log Viewer
External Log viewers (for ELK)
In cases when ELK is configured to manage your Pega Platform logs, it is still possible to view the logs in Kibana. This is especially preferable when you want to look at logs across a cluster and not just a single node. For guidelines on setting up ELK, see the Viewing logs using external log Community article.
Alert Logs (view in PDC)
One should not confuse Alert logs with application logs. Whenever there is an anomaly detected during the runtime of an application, Pega Platform raises an alert by logging an event of the ‘ALERT’ level. The event data for the alert is logged in the
PegaRULES-Alert-YYYY-MMM-DD.log file, not
PegaRULES.log. For more information about Alerts, see the Alerts concept Community article.
Note: Alert logs are not meant for analysis. All alert data is published to and best viewed in Pega Predictive Diagnostic Cloud (PDC). For more information, see the PDC Community article.