Event tracing

From Ametys 4.6

Ametys 4.6 enables all user actions to be tracked (connection, creation/modification/deletion of pages or content, etc.).

These events are tracked in a log and a specific category that must be activated.

To do this, in the file WEB-INF/log4j.xml, add (or uncomment) the following lines:

<!-- Specific appender to forensic events -->
<appender name="forensic" class="org.apache.log4j.rolling.RollingFileAppender">
        <param name="Encoding" value="UTF-8" />
        <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
          <param name="FileNamePattern" value="${ametys.home.dir}/logs/forensic-%d.log"/>
        </rollingPolicy>
        <layout class="org.apache.log4j.PatternLayout"> 
            <param name="ConversionPattern" value="%d %-5p [%c] (%t;%X{requestURI}) %m%n"/> 
        </layout>
        <filter class="org.ametys.core.util.AmetysExceptionFilter"/>
</appender>

<!-- Category to uncomment to trace events (and its associated appender) -->
<category name="org.ametys.core.trace.ForensicLogger" additivity="false">
   <priority value="info"/>
  <appender-ref ref="forensic"/>
</category>

The log file generated is named forensic-[DATE].log

The category corresponding to forensic events is org.ametys.core.trace.ForensicLogger

The category must be configured with the INFO log level.

Forensic logs can become very unwieldy very quickly, so make sure you target the tracking you want and, if necessary, set up a rotating log to automatically delete old logs.

Event categories

Events can be restricted to one or more event sub-categories.

For example, if you want to enable tracking of user events that only concern login/logout and account creation/modification, you'll enable only the categories:

  • org.ametys.core.trace.ForensicLogger.user
  • org.ametys.core.trace.ForensicLogger.account
  • org.ametys.core.trace.ForensicLogger.authentication
<!-- Specific appender to forensic events -->
<appender name="forensic" class="org.apache.log4j.rolling.RollingFileAppender">
        <param name="Encoding" value="UTF-8" />
        <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
          <param name="FileNamePattern" value="${ametys.home.dir}/logs/forensic-%d.log"/>
        </rollingPolicy>
        <layout class="org.apache.log4j.PatternLayout"> 
            <param name="ConversionPattern" value="%d %-5p [%c] (%t;%X{requestURI}) %m%n"/> 
        </layout>
        <filter class="org.ametys.core.util.AmetysExceptionFilter"/>
</appender>

<!-- Category to uncomment to trace events (and its associated appender) -->
<category name="org.ametys.core.trace.ForensicLogger.account" additivity="false">
   <priority value="info"/>
  <appender-ref ref="forensic"/>
</category>
<category name="org.ametys.core.trace.ForensicLogger.authentication" additivity="false">
   <priority value="info"/>
  <appender-ref ref="forensic"/>
</category>
<category name="org.ametys.core.trace.ForensicLogger.user" additivity="false">
   <priority value="info"/>
  <appender-ref ref="forensic"/>
</category>

All categories must be prefixed with"org.ametys.core.trace.ForensicLogger."

Here are just a few examples of categories - the list is not exhaustive.

 Category

Description

 account

User account events: registration request, account creation, password modification)

 authentication

Connection/disconnection events, connection failure

 user or group

Events linked to users or user groups (creation, modification, deletion, import)

 profile

Events linked to rights profiles (creation, modification, deletion)

 content

Content-related events (creation, modification, deletion, lifecycle, label assignment, etc.)

 page

Page events (creation, modification, deletion, renaming, label assignment, etc.)

These categories themselves have sub-categories that can be targeted in specific ways.
For example:
- to track only failed login attempts, activate the org.ametys.core.trace.ForensicLogger.authentication.form.failed category
- to track only page deletions, activate the org.ametys.core.trace.ForensicLogger.page.deleted category .

Log format

For each event, a line in the log file is generated in the following format:

date/heure INFO (url) [IP] [login#population] event.id (arg1::value1|arg2::value2|...) (header1::value1|header2::value2|...)

In order of appearance:

  • date and time of event
  • log level
  • url in brackets
  • IP address in square brackets
  • the identifier of the user responsible for the event between brackets
  • event identifier
  • event-related arguments, enclosed in brackets and separated by |.
  • http request headers, enclosed in brackets and separated by |.

Examples:

2022-11-18 17:11:27,056 INFO (http-nio-8080-exec-1;/catalog/_authenticate) [192.168.0.18] [admin#ametys_demo_users] authentication.login (user::UserIdentity [login=admin, population=ametys_demo_users]|credential-provider::org.ametys.core.authentication.FormBased) (host::localhost:8080|origin::http://localhost:8080|user-agent::Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36|referer::http://localhost:8080/catalog/_authenticate?requestedURL=/catalog/fr/index.html)
2022-11-18 17:13:53,869 INFO (http-nio-8080-exec-4;/cms/generate/catalog/fr/mot-de-passe.html) [0:0:0:0:0:0:0:1] [admin#ametys_demo_users] account.password.change (population::ametys_demo_users|login::admin|site::catalog) (origin::http://localhost:8080|user-agent::Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36|referer::http://localhost:8080/catalog/fr/mot-de-passe.html?login=admin&population=ametys_demo_users&token=60331b26ce1b44cf9af633b87c7d009d|host::localhost:8080)
Back to top

Administration manual