Troubleshooting PUM

Owned by Vladyslav Zacharko (Unlicensed)
Last updated: Feb 15, 2024 by Finn Gale
3 min read

If you are encountering problems when using Project User Manager (PUM), it is recommended to follow the below steps in the order shown.

Check the documentation

Have a quick look through the pages on the PUM wiki (where you are viewing this page). While they are not currently that detailed, they may be able to help.

Create a new support ticket

If after searching you have not found an issue related to your problem, then you may wish to raise a support ticket with us. Please provide as much information as possible which you deem relevant to your problem, including Jira and PUM version numbers.

Providing us with debug log output (see next section) can be very beneficial in resolving issues where the cause is not obvious.

Provide debugging information for your problem

After getting in touch with us via our support platform, you may be asked to provide debugging output generated by PUM. Once logging is enabled, reproduce the problem that you are having. Then, attach the log file (pum.log) to your support issue. If you wish, sanitize any private information from the log.

Enabling temporary logging (Ouput to the existing Atlassian log file)

You can enable PUM logging temporarily. This means that after Jira is restarted, this configuration is lost (PUM output will no longer be logged).

  1. Go to Jira Administration > System > Logging and profiling

  2. Under Default Loggers, select configure logging level for another package

  3. For Package name enter com.thepluginpeople.jira.pum

  4. For Logging Level select DEBUG

  5. Press Add to save

  6. Now, when PUM generates logging output it will be stored in the file /log/atlassian-jira.log located in your Jira installation HOME directory.

Enabling persistent logging (Output to a dedicated log file)

With the following configuration, Jira will create a pum.log file in JIRA_HOME/log.  A Jira restart will be required to make the changes apply.

  1. Go to your JIRA_INSTALL_DIR/atlassian-jira/WEB-INF/classes/log4j.properties file

  2. Add the following lines to the bottom of the file:

    # --------------------- # PUM LOGGING STARTS log4j.appender.PUMFileLog=com.atlassian.jira.logging.JiraHomeAppender log4j.appender.PUMFileLog.File=pum.log log4j.appender.PUMFileLog.MaxFileSize=20480KB log4j.appender.PUMFileLog.MaxBackupIndex=5 log4j.appender.PUMFileLog.layout=org.apache.log4j.PatternLayout log4j.appender.PUMFileLog.layout.ConversionPattern=%d %t %p [%c{4}] %m%n log4j.appender.PUMFileLog.Threshold=DEBUG log4j.logger.com.thepluginpeople.jira.pum=DEBUG, PUMFileLog # PUM LOGGING ENDS # --------------------

  3. Save your changes and restart Jira

  4. Logs can be found in the JIRA_INSTALL_DIR/home/log/pum.log (do not confuse this with the JIRA_INSTALL_DIR/logs)

Jira 9.5.0 and above Log4j2 XML configuration

RESTART REQUIRED

Jira 9.5.0 has upgraded the Log4j runtime logging library to version 2. Log4j2 uses XML configuration file format. With the following configuration, Jira will create a pum.log file in JIRA_HOME/log.  A Jira restart will be required to make the changes apply.

  1. Go to your JIRA_INSTALL_DIR/atlassian-jira/WEB-INF/classes/log4j2.xml file

  2. Add the following lines above the closing Appenders tag </Appenders> (around line number 257) :

    <!-- #####################################################--> <!-- # PUM APPENDER STARTS --> <!-- #####################################################--> <JiraHomeAppender name="PUMFileLog" fileName="pum.log" filePattern="pum.log.%i"> <PatternLayout alwaysWriteExceptions="false"> <Pattern> %d %t %p [%c{4}] %m%n </Pattern> </PatternLayout> <Policies> <SizeBasedTriggeringPolicy size="20480KB"/> </Policies> <DefaultRolloverStrategy fileIndex="min" max="5"/> </JiraHomeAppender> <!-- #####################################################--> <!-- # PUM APPENDER ENDS --> <!-- #####################################################-->

  3. Add the following lines above the closing Loggers tag </Loggers> (at the bottom, around line number 839) :

    <!-- #####################################################--> <!-- # PUM LOGGER REF STARTS --> <!-- #####################################################--> <Logger name="com.thepluginpeople.jira.pum" level="DEBUG" additivity="false"> <AppenderRef ref="PUMFileLog"/> </Logger> <!-- #####################################################--> <!-- # PUM LOGGER REF ENDS --> <!-- #####################################################-->