Description

In Jira 9.5, we’ve upgraded the Log4j runtime logging library to version 2. This means that if you’re using a custom Log4j 1.x configuration with your Jira instance, you’ll need to manually migrate it to the Log4j 2 XML configuration file format. This guide describes the necessary steps to complete the migration and provides examples to help you along the way.

If you didn’t customize the logging configuration of your Jira instance before upgrading to Jira 9.5, you can skip this page.

To learn more about what’s new in Log4j 2, see Apache Log4j 2.

Jira Log4j configuration files are located in the Jira application home directory:

• For Jira older than 9.5 and Log4j 1.x: log4j.properties
• For Jira 9.5 and newer: log4j2.xml

If your instance has any custom plugins not available on marketplace, please refer to the plugin migration guide and adjust them if necessary.

Resolution

To migrate any custom logging configurations, use the following steps.

Step 1: Migrate logging level configurations

In the following example, we’ll migrate the com.atlassian.jira logger level configuration.

In Log4j 1.x, the logging level configuration for the com.atlassian.jira logger would look like this:

log4j.logger.com.atlassian.jira = INFO, filelog
log4j.additivity.com.atlassian.jira = false

log4j.logger.com.atlassian.plugin.remotable.host.common.service.http.bigpipe.DefaultBigPipeManager = INFO, remoteappssecurity
log4j.additivity.com.atlassian.plugin.remotable.host.common.service.http.bigpipe.DefaultBigPipeManager = false

log4j.logger.com.atlassian.cache.event.com.atlassian.jira.crowd.embedded.ofbiz.EagerOfBizUserCache.userCache = INFO

(other loggers added as additional examples)

The same configuration in Log4j 2 requires that we migrate the com.atlassian.jira logger configuration to an XML logger under the name com.atlassian.jira, as a child of the Loggers XML element:

<Logger name="com.atlassian.jira" level="INFO" additivity="false">
    <AppenderRef ref="filelog"/>
</Logger>

<Logger name="com.atlassian.plugin.remotable.host.common.service.http.bigpipe.DefaultBigPipeManager" level="INFO" additivity="false">
    <AppenderRef ref="remoteappssecurity"/>
</Logger>

<Logger name="com.atlassian.cache.event.com.atlassian.jira.crowd.embedded.ofbiz.EagerOfBizUserCache.userCache" level="INFO">
    <AppenderRef ref="filelog"/>
</Logger>

As part of this migration, we gave the new logger the following properties:

• level defines the logging level (in this case, the logging level is INFO)
• name indicates the package we are configuring the logging level for (in this case, com.atlassian.jira)
• additivity means that the logger doesn’t inherit parent package's configuration

Step 2: Migrate Log4j appender configurations

Appender property definitions have also changed in Log4j 2. In the following example, we’ll migrate the JiraHomeAppender appender with the same configuration as in Log4j 1.x.

This is what the JiraHomeAppender appender configuration would look like in Log4j 1.x:

log4j.appender.filelog=com.atlassian.jira.logging.JiraHomeAppender
log4j.appender.filelog.File=atlassian-jira.log
log4j.appender.filelog.MaxFileSize=20480KB
log4j.appender.filelog.MaxBackupIndex=10
log4j.appender.filelog.layout=com.atlassian.logging.log4j.NewLineIndentingFilteringPatternLayout
log4j.appender.filelog.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSSZ} %t %p %X{jira.username} %X{jira.request.id} %X{jira.request.assession.id} %X{jira.request.ipaddr} %X{jira.request.url} [%q{2}] %m%n
log4j.appender.filelog.layout.StackTracePackagingExamined=false
log4j.appender.filelog.layout.MinimumLines=6
log4j.appender.filelog.layout.ShowEludedSummary=false
log4j.appender.filelog.layout.FilteringApplied=true
log4j.appender.filelog.layout.FilteredFrames=@jira-filtered-frames.properties

And this is what the configuration should look like in a Log4j 2-compatible format as a child of the Appenders XML Element:

<JiraHomeAppender name="filelog"
                  fileName="atlassian-jira.log"
                  filePattern="atlassian-jira.log.%i">
    <PatternLayout alwaysWriteExceptions="false">
        <Pattern>
            %d{yyyy-MM-dd HH:mm:ss,SSSZ} %t %p %X{jira.username} %X{jira.request.id} %X{jira.request.assession.id} %X{jira.request.ipaddr} %X{jira.request.url} [%q{2}] %nlm%n%stf{stackTracePackagingExamined(false)}{filteringApplied(true)}{filteredFrames(@jira-filtered-frames.properties)}
        </Pattern>
    </PatternLayout>
    <Policies>
        <SizeBasedTriggeringPolicy size="20480 KB"/>
    </Policies>
    <DefaultRolloverStrategy fileIndex="min" max="10"/>
</JiraHomeAppender>

Once you’ve completed all the steps above, your custom configuration should be perfectly compatible with Log4j 2.

If you want to use the JSON layout for your configuration, you have the following options:

• use the official Log4j 2 JsonLayout (see Log4j — Log4j 2 Layouts)

• use AtlassianJsonLayout (analogous to JsonLayout in Atlassian Log4j 1) by adding new appenders:

  <AtlassianJsonLayout
  	filteringApplied="true"
  	filteredFrames="@jira-filtered-frames.properties"
  	minimumLines="6"/>

  Warning

  Replacing the existing PatternLayout will change the format of application logs. This customization may cause problems in the parsing of the support zips at the Atlassian Support Teams. If you want to use JSON Layout, please proceed with adding a new logging appender.

  You can additionally change the following properties:

  • filteringApplied enables or disables stack trace filtering
  • filteredFrames can be either a comma-separated list of packages or a reference to a file, like in the Log4j 1.x configuration
  • minimumLines specifies the threshold for trace filtering

Step 3: Remove the log4j.properties file from the home directory

Make sure that there is no log4j.properties file in the Jira application home directory as it might unnecessarily trigger Log4j 1.x compatibility mode and cause problems with logging.