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
- Upgrade path with default configuration
- Configuration properties for loggers
- Information for users with custom Log4j logging configuration
- Configuring Elasticsearch logging
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).