Understanding log files

Logs files contain diagnostic messages that Pega Platform^TM generates. Log files support debugging of a feature or functionality, such as agents. Centralized logging provides an application-centric view of the log files that are generated by nodes throughout the cluster. You can see the logs for all nodes in a single view, without having to navigate from node to node. However, understanding this type of output requires that you remember the names of loggers for specific features. To more easily determine which loggers are for which features, you can categorize your loggers by using Pega-provided log categories or custom log categories.

Understanding log categories

A log category is a set of message codes that describe a process, a method, a flow, or a use case. You can configure custom log categories to enable or disable log messages. You can associate log levels with your log categories to include messages of that level and above in the log file. Log levels that you apply to a category are applied to all nodes in a cluster. For example, you do not need to change the log level for each logger in a specific category across all nodes in a cluster. If a logger belongs to multiple categories and has different logging levels set, the last log level is used for all categories that contain this logger. For example, if the DatabaseImpl logger is set to ERROR in one category and DEBUG in another category subsequently, the logger will show DEBUG-level messages for all categories.

You can select which log messages to write to a log file, based on your specific needs. You need the pzLogLevelObserver privilege to view log categories and the pzLogLevelAdministrator privilege to edit log categories.

For example, Pega provides the following loggers for agents in the pxBackgroundProcessing.Agents category:

• com.pega.pegarules.session.internal.async.Agent
• com.pega.pegarules.session.internal.async.BatchRequestorTask
• com.pega.pegarules.session.internal.async.agent.QueueManagerImpl
• com.pega.pegarules.session.internal.mgmt.base.RequestorChildren
• com.pega.pegarules.session.internal.async.agent.QueueProcessor
• com.pega.pegarules.session.internal.async.BatchUtils

When you create or modify custom log categories, you do not modify the prlog4j2.xml file. Instead, you create custom log categories by using Dev Studio. To modify custom log categories at run time, use Admin Studio. You can update and delete loggers in your custom categories or you can delete an entire category. You can also change the current log level of your category. If you want an individual logger within a category to work at a different log level than the log level that you associate with this category, you can also change the log level of that individual logger. This change only affects a current node and is temporary, which means that this setting is not persisted after system restarts.

Pega provides a set of default log categories, whose names start with px, for example, pxDatapages.Editable. You can change the log level of the default categories, but you cannot add or delete loggers from those categories.

For more information see, Managing log categories.