Log4j upgrade details for third-party app vendors

Jira 9.5 への準備

このページの内容

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

If you’re an app vendor and your app currently uses a custom Log4j 1.x configuration, you’ll need to update your code to make it compatible with Log4j 2 shipped with Jira 9.5.

To test your apps with the EAP release available, download the source files from here.

要約

Here’s a quick rundown of the changes we’ve made in Jira 9.5:

  • We’ve removed the log4j:log4j package from jira-api and replaced it with org.apache.logging.log4j:log4j-1.2-api to minimize the number of changes required to make apps compatible. If your app uses the Log4j 1.x API just for logging without any additional customizations, it should already be compatible with Jira 9.5.
  • We’re now using org.apache.logging.log4j:log4j-core and org.apache.logging.log4j:log4j-api in jira-core. We strongly advise against using it directly as it’s not part of the Jira API.
  • We’ve migrated our configuration files, custom layouts, appenders, and code configuring additional appenders dynamically to use Log4j 2 APIs.
  • slf4j-api remains in jira-api. If your app uses this logging API exclusively, it should not require any changes.

Recommended approach

We recommend that you make logging independent from the product and the logging backend. If your app uses the Log4j 1.x API only for logging and not configuration purposes, you should use slf4j-api provided by Jira instead.

If you need full configuration and customization capabilities of the logging backend, bundle the logging backend with your app. Log4j 2 (or, for example, reload4j) should be used as a dependency within the compile scope and no Log4j 2 packages should be imported through OSGi. This has the additional benefit of allowing backward compatibility with current LTS releases of Jira.

If you also need your app to write to the product logs, simply use slf4j-api without any additional slf4j bindings. This way, events logged through the slf4j package will be saved to the product logs, and events logged through the bundled backend API can be saved to your app’s log files.

What if I don’t want to or can’t use my own logging backend?

In that case, you’ll need to import log4j-api and log4j-core through OSGi. To do this, you can define the provided dependency on those packages.

To minimize the breaking aspect of the change, we decided to replace log4j in jira-api with the log4j-1.2-api (see Log4j 1.2 Bridge) so that basic logging calls don’t require migration. The actual version of this package is 2.x.x but we’re still exporting this package to OSGi with the version specified as 1.2.

You should analyze and check your app’s code for the conditions listed in the following table.

If you have any further questions, join the discussion on Atlassian Developer Community.


What might happen移行の手順Action required
1

My app depends on jira-api and does not use log4j as an explicit dependency or uses a provided dependency. Only slf4j-api is used.

Such apps (even if compiled with an older version of Jira) should work fine without changes.

TEST WITH EAP

2

My app depends on jira-api and does not use log4j as an explicit dependency or uses a provided dependency. Only the log4j basic logging API and the slf4j API are used in code.

If only the Log4j1 API (for example, Logger.getLogger(Something.class).error("error message");) is used, it should work without the need for any extra changes.

TEST WITH EAP

3

My app uses Log4j 1.x configuration API and/or custom components (like appenders and layouts).

All the runtime configurations must be written using Log4j 2 private APIs if you want to use the version of Log4j provided by the product.

You can use provided log4j-core and/or log4j-api dependencies. You also have to import org.apache.logging.log4j in OSGi if you don’t import * already. However, this is not a public API and might change in the future.

The Log4j 1.x configuration API will not work correctly when using a log4j-1.2-api bridge.
The basic logging API might be left as described in the previous point.

CODE CHANGE

4

My app uses Log4j 1.x MDC API to store objects.

This will not work with Log4j 2. The code has to be adapted to store Strings. Storing Strings will keep working as before.

CODE CHANGE

5

My app uses log4j in scope compile bundled in its jar.

Since logging was independent from Jira, it should work correctly. However, it might be non-compliant with many corporate policies.

TEST WITH EAP

6

My app uses com.atlassian.jira.log.LoggingConfiguration.

This class was removed. If required, you can use your own logging pattern. Default patterns used in Jira are available in log4j2.xml.

CODE CHANGE

7

My app uses the AMPS log4jProperties property to provide my own Log4j configuration for testing purposes.

  1. Upgrade AMPS to version 8.7.0 and maven to version 3.6.3 or newer.
  2. Migrate your logging configuration to the Log4j 2 XML format.
  3. Instead of log4jProperties, use the log4j2Config property and point it to the migrated configuration file.

If you encounter problems with WRM.I18n not being initialized or scripts executing in the wrong order, add <processI18nUsage>false</processI18nUsage> to your AMPS configuration. This is a new AMPS feature that controls the generation of *.i18n.properties files for JavaScript. Setting the property to false disables the feature.

CODE CHANGE

8My app uses Log4j 1.x APIs to assert on tests.This will not work with the bridge, it doesn’t allow accessing log4j 2 appenders. Log4j 2 API should be used if it’s required to assert on logs.

CODE CHANGE

9

My app relies on a custom Jira Appender and/or Layout classes (for example, JiraHomeAppender)

This won’t work as intended. Custom Appender and Layout classes were migrated to the Log4j 2 API. Code adjustment is required.

CODE CHANGE

10In my development environment, Jira does not create log files.

Ensure you don't set log4j.configuration system property at all, or point it to the existing file.
If the property is set to invalid value, log4j2 will use its default console logging configuration.
If it is pointing to the existing log4j 1 configuration file, it will be converted and used by log4j 2 instead of Jira configuration.

CODE CHANGE

最終更新日: 2022 年 10 月 19 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.