Loggers and Log Categories in Pega

In this blog article, we will see how to add log levels for different loggers and also group the loggers into a log category for easy maintenance purposes.

Let’s start with the logging framework.

What is a logging framework?

The three main components of logging framework are

a) Loggers – Captures the logged message and pass it to logging framework

b) Formatter – Formats the output message

c) Appender/handler – writes the messages to the configured destination

In this blog article, we will see in detail about loggers only!

What is a logger?

– A logger object is used to log messages for a system or an application.

– Logger names can be based on the package name or class name and uses a hierarchical dot-separated namespace.

– Each logger has a level associated with it.

What is a log level?

Log level can also be called as security level and it varies slightly per logging framework used.

Every log message is logged at a certain level.

We know that Pega uses the Log4j framework (ofcourse it is all everywhere with zero-day vulnerability on log4j)

Let’s look at the log levels for the Log4j framework in detail.

OFF – When you set the logging level as OFF to any logger, then it just turns of logging

FATAL – This is the highest logging level. Very severe errors that can lead to the application to stop functioning. For example – The database is not reachable. Setting at this level will only log the fatal messages.

ERROR – normal error events that still allow the application to function.  For example – Connector timeout exception. Setting this level will log both the ERROR and FATAL messages.

ALERT – System alert messages. Pega generates a lot of performance-related alerts under this level.

WARN – Indicates potential harmful situations. Logs WARN, ALERT, ERROR and FATAL messages. For example – memory usage reaching the threshold limit.

DEBUG – This level is used by application developers to trace and debug. For example – if you want to debug and trace the OAuth flow, then you can enable debug level for the OAuth related loggers. Setting this level logs the DEBUG and other higher log levels.

INFO – Provides the information message. For example – the star up time of server is 15056ms. Setting this level logs the INFO and other higher log levels.

ALL – Logs all the levels.

Okay enough of theory now. Let’s get back to the usage of loggers in Pega.

As I told you before, Pegasystems uses the log4j libraries for logging purpose.

Let’s verify the Log4j classes in our pr_engineclasses table.

Execute the query in your Postgres database – select * from rules.pr_engineclasses where pzpackage like ‘org/apache/logging/log4j%’

You see a list of classes under the log4j packages

It is clear Pega is using the apache log4j framework for logging.

Now the question is about the loggers. Who creates it? Do we need to manually create a logger every time?

The answer is NO.

Pega takes care of it.

Step 1: Create a simple activity with three steps.

Step 2: View Java for the activity

Click on the actions button and view Java.

You can find the logger name for your activity as – Rule_Obj_Activity.ProductDetails.OLM5RD_SecondApp_Int.Action

Note: LogHelper references a particular logger name, but the logger object is not created at this moment.

Now we know the logger name. So how do we set the log level for this logger?

Step 1: Navigate to the log level settings landing page.

Configure -> System -> Operations -> Logs

Step 2: Set the log level

Click on the log level settings link.

Search for the new logger name. For the first time, you will see the logger object does not exist.

You can add the current level to DEBUG.

Now you see a new logger is created with level Debug.

Step 3: Execute the activity and check the log file.

There you see each step is logged for the activity since it is running in debug mode.

Important note: prlog4j2.xml controls the default log level settings for each logger. For all Pega loggers, the default setting is ERROR. The main reason is not to flood the log files (and its corresponding storage space) with info and debug messages.

For debugging purpose, you can always change the log level setting to debug mode. Changing the log level settings will take effect immediately but only for that particular node or server. ( loggers settings will not be stored in the database and hence it cannot be shared across nodes/servers)

How to revert back to the log level settings?

1. On server restart –  all the loggers level will be reset based on the configuration on prlog4j2.xml in the server location.

2. Using the log level settings, you can revert back the log level per logger or you can reset the entire loggers to default settings.

Tip: Always make sure to reset all your loggers to default settings after you are done with debugging 🙂

Now if you search for the logger again, it will be reset to Error.

Pega also prints a log entry whenever the logging level settings are changed, so we know when and by whom the log level settings are changed.

If you want to permanently change the log level settings for any logger, you need to update the Log4j2.xml file accordingly. Please do it only when necessary.

There are a list of useful loggers that can be used for debugging services and connectors. Please follow the link for more details on it.

Till now we saw about updating individual logger instances, wouldn’t it be easy to manage and update a group of loggers together?

Now the second part of the tutorial

From Pega 8.4, we have a new data instance called – Log categories.

What is a log category instance?

You can organize log messages into categories by creating a custom log category instance.

For a common functionality, you can create a log category and add all the loggers inside the log category instance. In this way, it can be easily maintained and managed without remembering each individual logger names 🙂

First lets, look at the existing OOTB log categories.

Records -> SysAdmin -> Log categories

As per 8.5.1, there are 37 log categories already configured in the system.

Just open anyone to look into the configuration.

In the Integration, connector SOAP  log category, you will the related loggers and their default log level as ERROR.

You also see an information message at the top saying, this is OOTB and cannot be deleted or modified!!, yeah it is read-only!

Let’s say, you are getting issues with Connect SOAP and you want to debug the connector. So you need to set the level to debug.

a. You can either set the log level to debug for each individual logger as we saw in the first part of this tutorial (or)

b. You can update the connect SOAP log category’s log level settings to Debug.

So how do we manage the log categories?

Note: To create/update you need to have the pzLogLevelAdministrators privilege.

Step 1: Switch to admin studio, resources

Step 2: Click on log categories. You will find all the available log categories.

Step 3: Find the connector SOAP OOTB category and click change log level.

There you can change it to DEBUG mode.

Important note: As you see in the message, the changed log level will be applied across the cluster and affect all users of the system!!

Update in higher versions

You can see the same pop-up redesigned with Reset in (hours) – with minimum of 2 hours to maximum 24 hours.

This reset configuration can ensure to take care of careless behaviour, if a developer updates and failed to revert back 😉

Click submit and you will see the log level is changed to DEBUG.

Important note: The log level setting, updated for the log category persist in the database and get applied after server restart as well. You need to change it manually or reset the settings to default for all log categories from admin studio. I will keep on saying, use effective logging don’t flood your log files 😛

There may be situation, where you want to update one of the loggers in the log category into different log level settings. In that case, you can use the advanced settings link, to change for individual logger (same like part 1 of this tutorial)

And then you can change to error or other log level setting.

Important note: The log level setting updated for the individual logger will always be applicable only for the single node and will be reset at server restarts!

As a hands-on you can try creating a new log category for any functionality and try it out.

As a summary,

– Pega uses Log4j java logging framework libraries to log the messages.

– The default log level settings are controlled in the log4j2.xml file which can be overridden per node by updating the log level settings.

– Log level changes per logger is applicable only for the particular node and stay effective till the node gets restarted or updated manually.

– Log categories – a new data instance is introduced in 8.4 version, that helps to group the logs for easier maintenance.

– Log categories can be managed by the admin studio, and the changes persist in the database – meaning it apply to all nodes in the cluster and stay effective even after server restarts. It can only be updated manually with the right privilege.