Migration to Log4j version 2.x

Information about the Akana platform's migration to Log4j 2.x in version 2020.2.16.

Note: Log4j 2.x requires Elasticsearch version 7.16.2.

Valid in Version: 2020.2.16 and later

Table of Contents

Overview

Versions of Akana products prior to 2020.2.16 use Log4j version 1.x. Version 2020.2.16 and later versions use Log4j 2.x.

If you are upgrading from a previous version of the product, and have no customized logging, the change is transparent. No additional configuration is required.

If you have custom logging in place, and are upgrading from a previous version, refer to the information in Information for users with custom Log4j logging configuration below, and the Apache Log4j version 2.x documentation: see Welcome to Log4j 2. Examine your previous settings, and update accordingly following the instructions for the new version.

Upgrade path with default configuration

Note: When upgrading to a version of the platform that uses Log4j 2.x, it's important that you recreate the containers in your implementation, rather than trying to upgrade existing containers.

Assuming you create new containers, and you are using the default logging settings, no additional configuration is required.

In looking at log files you might notice slight differences in the contents of the log file.

If you've customized your logging, review the documentation and examples below, and the Apache Log4j documentation, to set up your custom loggers.

Configuration properties for loggers

The configuration properties for loggers are in the Admin Console: Configuration Properties > com.soa.log.

Some properties are provided/configured by default. You can define one or more new loggers as needed. For an example, see Sample configuration below.

You might want to set up a custom logger in either of these scenarios:

  • If you had custom loggers defined in an earlier version, and are upgrading to version 2020.2.16 or later, you'll need to redefine your customized settings. The new logger then becomes part of the configuration for the logging subsystem.
  • If you haven't used custom logging before, you might want to configure a new logger for the first time.

In either case, refer to the Apache Log4j version 2 documentation, section Configuration Syntax. Note that the Akana platform uses a properties file, not XML or JSON configuration files.

The first part of the property name must be one of these:

  • logger: defines a new logger.
  • appender: appends to an existing logger.

For the rest of the property name you are defining, refer to the configuration syntax guidelines.

Information for users with custom Log4j logging configuration

This section includes general information, and an example, to help you get started with defining Log4j version 2.x logging configuration settings.

The newer configuration is more powerful, but is also slightly more complex than the 1.x format, and is incompatible with it. This section details the new configuration used in the product, with information about how it relates to the older format and an example of the new configuration.

In this section:

Appenders and Loggers

The core Log4J model is similar between the two versions. Both have the notion of Appenders that perform the actual writing of log data to a destination. The selection of Appenders for Log4J 2.x is extensive. For a list, see Appenders in the Apache Log4j 2.0 documentation.

In general, the Akana product uses a simple Log4J configuration. All logging is delegated to a single root appender, which is usually a rolling file appender in both versions (see RollingFileAppender in the Log4J 2.x documentation).

In earlier versions, the Akana SaaS platform used a proprietary Elasticsearch Appender for Log4J 1.x. With the transition to Log4J 2.x, this is replaced by an off-the-shelf version.

Loggers and categories

In Log4J 1.x, logging configuration for individual Java packages was managed by defining categories. In Log4j 2.x, this has been replaced by the idea of Loggers. As with categories, any number of Loggers may be configured, and each Logger applies to a specific scope which is generally a Java package name.

Log4J 1.x

In Log4J 1.x, a category could be defined using a single line syntax. For example:

log4j.category.com.soa=ERROR

Log4J 2.x

In Log4J 2.x, this is now done using a Logger configuration. For example:

logger.soa.name = com.soa
logger.soa.level = error

This new configuration is more flexible, if slightly more verbose. The name property specifies the package or category, and the level property specifies the log level for that specific category. The logger name is extracted from the configuration as logger.<logger name>.<property name>, and can be any string used to identify and associate the specific logger and level.

Sample configuration

The following configuration is based on the default distributed with the product. The configuration properties are in the Admin Console, com.soa.log configuration category.

01 rootLogger.level = error
02 rootLogger.appenderRef.rolling.ref = rolling
03 
04 name = AkanaConfig
05 status = error
06 shutdownHook=disable
07 
08 appender.rolling.name = rolling
09 appender.rolling.type = RollingFile
10 appender.rolling.fileName = log/${container.name}.log
11 appender.rolling.filePattern = log/${container.name}.log.%i
12 appender.rolling.bufferedIO = true
13 appender.rolling.layout.type = PatternLayout
14 appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
15 appender.rolling.policies.type = Policies
16 appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
17 appender.rolling.policies.size.size=5MB
18 appender.rolling.strategy.type = DefaultRolloverStrategy
19 appender.rolling.strategy.max = 10
20 appender.rolling.strategy.fileIndex = min
21 
22 logger.http.name = org.apache.http
23 logger.http.level = off
24 
25 logger.wire.name = org.apache.http.wire
26 logger.wire.level = off
27 
28 logger.headers.name = org.apache.http.headers
29 logger.headers.level = off
30 
31 logger.jetty.name = org.eclipse.jetty
32 logger.jetty.level = off
33 
34 logger.digev.name = com.digev
35 logger.digev.level = error
36 
37 logger.soa.name = com.soa
38 logger.soa.level = error
39 
40 logger.akana.name = com.akana
41 logger.akana.level = error

In the above:

  • Lines 1–2: These define the root logger. The root, default, log level is error, and the root appender is the rolling file appender.
  • Lines 4–6: General configuration. The name of this configuration is AkanaConfig and the internal Log4J shutdown hook is disabled because the Akana container manages the logging subsystem lifecycle. The status property defines the level of internal Log4j events that should be logged to the console, which is useful for troubleshooting logging problems.
  • Lines 8–20: These lines define the rolling file appender. For more details on these configuration properties, see RollingFileAppender.
  • Lines 22 to end: These are the individual Logger configurations that correspond to the default category configuration shipped with the old Log4J 1.x configuration.

Configuring Elasticsearch logging

In versions prior to 2020.1.16, the Akana platform used a proprietary Elasticsearch Appender for Log4J 1.x. With the transition to Log4J 2.x, this is replaced by an off-the-shelf version. For information about configuring logging for Elasticsearch, see Configuring Elasticsearch Logging (2020.2.17 and later).