Log4j upgrade details for third-party app vendors
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.
Summary
Here’s a quick rundown of the changes we’ve made in Jira 9.5:
- We’ve removed the
log4j:log4jpackage fromjira-apiand replaced it withorg.apache.logging.log4j:log4j-1.2-apito 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-coreandorg.apache.logging.log4j:log4j-apiin 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-apiremains injira-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 | Migration steps | Action required | |
|---|---|---|---|
| 1 | My app depends on | Such apps (even if compiled with an older version of Jira) should work fine without changes. | TEST WITH EAP |
| 2 | My app depends on | If only the Log4j1 API (for example, | 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 The Log4j 1.x configuration API will not work correctly when using a | 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 | 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 | This class was removed. If required, you can use your own logging pattern. Default patterns used in Jira are available in | CODE CHANGE |
| 7 | My app uses the AMPS |
If you encounter problems with | CODE CHANGE |
| 8 | My 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 | This won’t work as intended. Custom | CODE CHANGE |
| 10 | In my development environment, Jira does not create log files. | Ensure you don't set | CODE CHANGE |