Logging

All codes within The World Avatar project (TWA) should ensure they adequately use logging to record their actions and the occurrences of any warnings/errors. To that end, a common logging approach is presented below. Unless a specialist approach is needed for a particular code base (if so, please consult senior developers), then it's expected that this approach is followed in all TWA projects.

Note: A previous logging framework is present in some older code bases; previously, the JPSBaseLogger class within the JPS Base Library was created with the intention that all codes would log through this central location, and that logs were remotely sent to a Servlet running using the JPS_BASE project. Whilst this JPSBaseLogger class still exists, it is now deprecated and should be avoided wherever possible. The logging Servlet provided by the JPS_BASE project is also not currently in use and should be avoided.

Logging in Java projects

Logging within all Java projects should now be handled via the use of Log4j2. Older versions of Log4j, and any use of SLF4J are now discouraged.

Log4j2 uses a configuration file to define the destination of logging statements, their format, and the minimum logging level. Two Log4j configuration files (one for development environments, one for production) have been created for use with TWA Java code bases and can be downloaded from the package repository using Maven. See the Packages page of the Wiki for details on how to connect to the package repository.

Adding logging to your code

New codes

If you're starting a new Java code base, it's highly suggested that you take a copy of the example Java agent. This has already been configured to include the required libraries, download the config files, and contain example logging statements. Comments are provided within the pom.xml, source code, and Docker configuration of this example agent; it's worth taking the time to read and understand what's going on before adding your own changes.

Existing codes

If adding (or updating) logging to an existing code base, simply follow the below steps.

1. Add the parent pom to your project.
2. Ensure the below dependencies are added to your project (any other logging libraries can be removed).

<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-api</artifactId>
</dependency>
<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-core</artifactId>
</dependency>

3. If using a Java project that builds as a WAR file (i.e. a Servlet), also include the following dependency.

<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-web</artifactId>
</dependency>

4. Add the following plugins to your project's pom.xml file. If definitions of these plugins already exist in your project, their configuration should automatically be merged with the one declared in the parent pom (so you don't need to add these elements). If this causes issues, please contact senior developers.

<!-- Used to build into a WAR file and ensures everything in ./WEB-INF
gets copied into the final WAR file's internal WEB-INF directory. -->
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-war-plugin</artifactId>
	<!-- Version, configuration, and executions should be pulled from the 
	parent POM unless overridden here. -->
</plugin>

<!-- Downloads and extracts ZIP archives from Maven repository -->
<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-dependency-plugin</artifactId>
	<!-- Version, configuration, and executions should be pulled from the 
	parent POM unless overridden here. -->
</plugin>

5. Add the following profiles to your project's pom.xml file. This will allow you to choose which logging configuration file (development or production) will be used in your project via a command line argument.

<!-- Profiles are used to switch between building for development and production 
environments. Use "-P profile-id" within an mvn command to build with a profile -->
<profiles>
<!-- This profile should be used for development builds. -->
<profile>
	<id>dev-profile</id>
	<activation>
		<activeByDefault>true</activeByDefault>
	</activation>
	<properties>
		<!-- Set property to download development logging config -->
		<log.classifier>java-log-config-dev</log.classifier>
	</properties>
</profile>

<!-- This profile should be used for production builds. -->
<profile>
	<id>prod-profile</id>
	<properties>
		<!-- Set property to download production logging config -->
		<log.classifier>java-log-config-prod</log.classifier>
	</properties>
</profile>
</profiles>