Audit Configuration Reference

Configuration settings for audits are available at a system scope. You can find these settings by opening the Global Menu () and navigating to Control Panel → System Settings → Audit.

Audit

Enable or disable audit logging for your instance entirely.

Use this checkbox to enable or disable auditing entirely for your Liferay instance. Note that when auditing is enabled, you can adjust the Audit Message Maximum Queue Size field from its default value.

CSV Logging Message Formatter

Control the number of columns in the exported CSV file.

Use this to define the columns, such as userEmailAddress, that appear in the CSV export of audit events. You cannot create new columns. You can only remove existing columns and add them back later.

Logging Message Audit Message Processor

Enable logging of events to Liferay DXP's log and console.

Configure audit events to be written to Liferay DXP’s log and console:

Select Enabled to report audit events in Liferay DXP’s log.
Select Output to Console to print audit events to the console.
Select the Log Message Format (CSV or JSON).
Click Save.

Persistent Message Audit Message Processor

Enable this setting to write audit logs to the database.

Enable this setting to write audit messages to the database. The Audit interface uses data from the database to display audit messages. If you turn it off, the interface does not display entries.

Audit Log Context

Add additional audit information to Log4J logs.

Enable this setting to include audit metadata (such as clientIP, userId, and emailAddress) in log messages written by Log4j. This is useful for cross-referencing Liferay activity with external logs.

Important

Enabling this setting alone does not display information in your logs. You must manually configure your Log4j layout to output the Mapped Diagnostic Context (MDC) using the %X specifier or a JSONLayout with properties enabled.

When Use Incoming X-Request-ID is enabled, a client can send the X-Request-ID header. Liferay tags each log statement with this value, which helps trace requests across systems.

Configuring the Log4j Layout

To display audit information, modify your Log4j configuration by creating a portal-log4j-ext.xml file with the following structure:

<?xml version="1.0"?>
<Configuration strict="true">
   <Appenders>
      <Appender name="CONSOLE" type="Console">
         <Layout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p [%t][%c{1}:%L] %m%n %X%n" type="PatternLayout"/>
      </Appender>

      <Appender name="JSON_CONSOLE" type="Console">
         <JSONLayout properties="true" />
      </Appender>
   </Appenders>

   <Loggers>
      <Logger name="com.liferay.portal.security.audit" level="DEBUG" />

      <Root level="INFO">
         <AppenderRef ref="CONSOLE"/>
      </Root>
   </Loggers>
</Configuration>

strict="true": Required for Liferay’s Log Bridge to validate the configuration.
%X: The conversion pattern that prints the thread context (MDC) metadata.

Important

This specifier is essential. Enabling the setting in the UI alone does not display information. You must use %X (standard logs) or set properties="true" (JSON) to make metadata visible.
properties="true": Required for JSONLayout to include thread context values in JSON output.

Deploy the Configuration File

Place the portal-log4j-ext.xml file in Liferay’s classpath to override the default settings.

For example, in Tomcat you’d place it here: [Liferay Home]/tomcat-[version]/webapps/ROOT/WEB-INF/classes/portal-log4j-ext.xml

In other application servers, you may have to add it to the Liferay WAR file and redeploy.

Tip

If the file is not detected at the root of the classes folder, try placing it in a META-INF subfolder (.../WEB-INF/classes/META-INF/portal-log4j-ext.xml).

Adjust Log Levels

To see the audit metadata, set the com.liferay.portal.security.audit log level to DEBUG. Many audit details are only captured and displayed when this higher logging level is active.

You can set this in the portal-log4j-ext.xml file or via the UI for immediate effect.

To adjust the level via the UI,

Open the Global Menu, (), navigate to Control Panel, and select Server Administration → Log Levels.
Click New and add com.liferay.portal.security.audit under Logger Name.
Set the Log Level to DEBUG and click Save.

Verify the Output

Once configured, log entries include a metadata block (AuditLogContext).

Restart your portal to apply changes.
Log out and log in again with an incorrect password. A message similar to this appears in your terminal:

2026-02-27 12:51:59.885 INFO [http-nio-8080-exec-6] User login failure detected. {AuditLogContext.clientIP=127.0.0.1, AuditLogContext.companyId=10154, AuditLogContext.userEmailAddress=test@example.com, AuditLogContext.userId=20102, AuditLogContext.xRequestId=89f24950-ff28-1450-a97f-4b8f79148ea3}