Audit

Audit trail allows an administrator to record user activity in the system. An audit trail typically captures the who, what, when and where. The default implementation is based on Log4j 2 and the files used for logging can be configured to suit your requirements. Magnolia also provides a Log Viewer tool, located in the Tools menu, to visualize these and other log files.

auditLogging configuration

This feature is configured in the log4j2.xml file and in the auditLogging configuration.

Defining loggers

Here you define the loggers to be used by the audit logging. Here is an example extracted from the application log4j2.xml :

<RollingFile name="sync-log-audit"
             fileName="${magnolia.logs.dir}/magnolia-audit.log"
             filePattern="${magnolia.logs.dir}/magnolia-audit-%i.log"
             append="true">
   <PatternLayout pattern="%d{dd.MM.yyyy HH:mm:ss}%m%n"/>
  <Policies>
    <SizeBasedTriggeringPolicy size="1MB"/>
  </Policies>
  <DefaultRolloverStrategy max="5"/>
</RollingFile>
<Async name="log-audit">
  <AppenderRef ref="sync-log-audit"/>
</Async>

Configurable properties of a LogConfiguration object

A LogConfiguration object defines how specific audit logging actions are handled in Magnolia, including where log entries are written, how they’re formatted, and whether they trigger system events.

Example configuration

auditLogging:
  class: info.magnolia.audit.AuditLoggingManager
  defaultSeparator: ',' (1)
  logConfigurations:
    publish:
      active: true
      logName: log-audit
      separator: '|' (2)
    unpublish:
      active: true
      logName: log-audit
1 The defaultSeparator is a property of the main AuditLoggingManager. It sets a global, default separator that is used for all audit log messages.
2 This separator override applies only to the publish action.

Properties

Property Description

name

required (type: String)

A unique but arbitrary identifier node name for the configuration. It’s used to match an incoming logging request’s action to its specific configuration.

logName

required (type: String)

Defines the name of the logger that receives and writes the audit log message.

active

optional (type: boolean), default is false

A flag that enables or disables this specific log configuration.

sendEvents

optional (type: boolean), default is false

If set to true, an info.magnolia.audit.AuditLoggingManager.AuditLoggingEvent is fired on Magnolia’s event bus each time a log entry is made.

This allows other parts of the system, such as a custom AuditLoggingEventHandler, to listen for and process these events.

separator

optional (type: String), default is ,

The character or string used to separate the different fields (action, data) within the final log message.

If this property isn’t set, a default separator (, a comma) from the AuditLoggingManager is used instead.

Defining actions

Define the actions you want to log in auditLogging configuration. You can enable the preconfigured actions and define which logger they should use. Define separators for each action or use the default separator (comma) for all of them.

Node name

Value

📁 server

     📁 auditLogging

         ⸬ logConfigurations

             ⸬ deactivate

             ⸬ activate

                 ⬩ active

false

                 ⬩ logName

log-audit

             ⸬ copy

             ⸬ login

             ⸬ logout

             ⸬ move

             ⸬ modify

             ⸬ create

             ⸬ delete

             ⬩ class

info.magnolia.audit.AuditLoggingManager

             ⬩ defaultSeparator

,

Below is an extract of the log output. The general pattern is when, what, who, where.

20.10.2008 11:59:33 , create , superuser , website , /untitled4

The move and copy actions log the source node path and the destination node path.

The login action logs the IP address and the result.

21.10.2008 12:21:59, logout, anonymous
21.10.2008 12:22:05, login, superuser, 127.0.0.1, Success

Excluding workspaces

To reduce the amount of noise in your logs, you way want to exclude certain workspaces in the auditLogging configuration even when logging is activated for a certain action. Examples:

  • If you have logging activated for the create action, you may want to exclude the messages workspace from the logs so that the creation of messages isn’t logged.

  • If you have logging activated for the modify action, you may want to exclude the userranking workspace from the logs to avoid the log being flooded with entries every minute when users search for terms.

To exclude a workspace from auditLogging:

  1. In the Configuration app, go to server/auditLogging.

  2. Add a content node named excludeWorkspaces.

  3. Under that node, add a property for each workspace you want to exclude. The value of the node should be the workspace name.

    Node name

    Value

    Type

    📁 server

    …​

         📁 auditLogging

             📁 logConfigurations

             ⸬ excludeWorkspaces

                 ⬩ Messages workspace

    messages

    String

                 ⬩ User Based Ranker

    userranking

    String

             ⬩ class

    info.magnolia.audit.AuditLoggingManager

    String

             ⬩defaultSeparator

    ,

    String

    …​

Including metadata

By default, auditLogging ignores changes to properties and nodes prefixed with jcr: or mgnl:. You can configure a list of properties to audit those property changes. In the example configuration below, page template modifications are included.

To whitelist a property:

  1. In the Configuration app, go to /server/auditLogging.

  2. Add a content node named includeMetadata.

  3. Under that node, add a property for each node/property name you want to include.

    /server/auditLogging
    Node name Value

    📁 auditLogging

         ⬩ defaultSeparator

    ,

         ⬩ class

    info.magnolia.audit.AuditLoggingManager

         📁 logConfigurations

         ⸬ includeMetadata

             ⬩ template

    mgnl:template

    The mgnl:template property is included in the audit logging.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules