Child pages
  • Troubleshooting Synchronizers

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

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.

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.

Anchor
temporary-level-change
temporary-level-change

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.

  1. Log in as a user with the JIRA System Administrators global permission.
  2. 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.
  3. 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.

Anchor
permanent-level-change
permanent-level-change

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):

Code Block
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:

Code Block
log4j.appender.structure-sync=com.atlassian.jira.logging.MultiTenantJiraHomeAppender
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

Synchronization Undo Files

Structure keeps synchronization undo files for possible script processing in case massive changes are erroneously effected on issue data. The undo files contain actions that should be taken, in reverse order, to bring issue database to the original / previous state. However, undo files do not contain changes for the structures - only for the issue data.

See Structure Files Location for information about where syncundo files are located.

In some cases undo files may be preferred to the logs as they more clearly indicate the changes.