Troubleshooting Synchronizers

Structure synchronizers work in background and can lead to changes in the structures or issue data that might be hard to trace. Complex configuration rules don't make things better, so it's important for JIRA admin to be able to track which synchronizers are doing what and what has caused a particular change a user is complaining about.

Structure Audit Log

Starting with Structure 3, all standard synchronizers record all actions they have taken in the database and allow the administrator to undo the changes. Navigate to Administration | Structure | Support | Synchronizer Audit Log to query history or apply undo.

Log Files

To get detailed reports about what's going on, you can reconfigure your JIRA logging so that structure synchronizers can produce more verbose messages. Also, you might want to direct messages from the synchronizers into separate log files.

The appearance of detailed synchronizer messages is governed by the log level: the lower the log level, the more detailed messages can appear. By default, log level for structure synchronizers is WARN, and you can set it to lower levels, like DEBUG (the lowest one.) You can set the logging level either temporarily (until the next JIRA restart) or permanently.

To see the list of possible log levels and other general information regarding logging in JIRA, please refer to JIRA logging documentation.

Temporarily change log level for structure synchronizers

If you set log level in this way, it will not persist after you restart JIRA. This is a relatively simpler way than setting the log level permanently.

Log in as a user with the JIRA System Administrators global permission.
Select Administration | System | Troubleshooting and Support | Logging & Profiling (tab). The 'Logging' page will be displayed, which lists all defined log4j categories (as package names) and their current logging levels.
Locate and click the link that reads "Configure logging level for another package", and a dialog will be displayed. For troubleshooting bundled synchronizers, specify package name com.almworks.jira.structure.ext; choose the appropriate logging level, e.g. DEBUG.

Permanently change log level for structure synchronizers or set up separate log files for synchronizers

This way, you need to modify the log4j.properties file, which is located in the JIRA installation directory.

The package name that all bundled synchronizers log under is com.almworks.jira.structure. You can add the following lines to have debug messages from synchronizers show on the console and/or in the log file (depending on their respective log levels):

log4j.logger.com.almworks.jira.structure = DEBUG, console, filelog
log4j.additivity.com.almworks.jira.structure = false

Or, you can set up a separate log file for synchronizer actions:

log4j.appender.structure-sync=com.atlassian.jira.logging.JiraHomeAppender
log4j.appender.structure-sync.File=structure-sync.log
log4j.appender.structure-sync.Threshold=TRACE
log4j.appender.structure-sync.MaxFileSize=20480KB
log4j.appender.structure-sync.MaxBackupIndex=1
log4j.appender.structure-sync.layout=org.apache.log4j.PatternLayout
log4j.appender.structure-sync.layout.ConversionPattern=%d %t %p %X{jira.username} [%c{4}] %m%n

log4j.logger.com.almworks.jira.structure = DEBUG, structure-sync, console
log4j.additivity.com.almworks.jira.structure = false