Enable mail debugging mode in Jira Data Center

Summary

To detail clearly how to enable debug mode for both the incoming and outgoing emails in Jira.

Solution

• Go to Administration (Gear next to profile) > System > Logging and Profiling page

  • This can also be accessed by pressing 'g+g' and typing Logging and Profiling in the pop-up.

• For Outgoing Mail,

  • Scroll down the page to the Outgoing Mail Section

  • Ensure that you have an Outgoing Mail configured and that Outgoing Mail log is enabled as without it, debugging cannot be enabled through the UI.

    ℹ️ If you are only using Jira Service Management email, you need to add the package com.atlassian.mail as DEBUG

  • Click the blue Enable link that appears in this section to enable outgoing mail debugging.

  • To persist the debug logging enabled, even after you restart Jira:

    • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j.properties file.

    • Locate the section:

      1 log4j.logger.com.atlassian.mail = INFO, outgoingmaillog

      and change INFO to DEBUG.

    • For Jira 9.5 and above the configuration file that will need to be updated is named log4j2.xml and the syntax for adding the debug logging has changed.

    • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j2.xml file

    • Add the content below just before the closing "<Loggers>" tag.

      1 2 3 <Logger name="com.atlassian.mail.outgoing" level="DEBUG" additivity="false"> <AppenderRef ref="outgoingmaillog"/> </Logger>

  • For batch notifications specifically, set the packagecom.atlassian.jira.plugins.inform.batching to DEBUG

• For Incoming Mail,

  • Scroll down the page to the Incoming Mail Section

  • Ensure that you have an Incoming Mail configured and that Incoming Mail log is enabled as without it, debugging cannot be enabled through the UI.

    ℹ️ If you are only using Jira Service Management email, you need to add the package com.atlassian.mail.incoming as DEBUG

  • Click the blue Enablelink that appears in this section to enable Incoming mail debugging.

  • To persist the debug logging enabled, even after you restart Jira:

    • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j.properties file.

    • Locate the section:

      1 log4j.logger.com.atlassian.mail.incoming = INFO, incomingmaillog

      and change INFO to DEBUG.

    • For Jira 9.5 and above the configuration file that will need to be updated is named log4j2.xml and the syntax for adding the debug logging has changed.

    • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j2.xml file

    • Add the content below just before the closing "<Loggers>" tag.

      1 2 3 <Logger name="com.atlassian.mail.incoming" level="DEBUG" additivity="false"> <AppenderRef ref="incomingmaillog"/> </Logger>

• To enable email logging for incoming and outgoing at the protocol level (more verbose), add -Dmail.debug=true to the Jira startup parameters.

For more information on the subject, please refer to Logging and Profiling.

ℹ️ Keep in mind that the primary goal of debug logging is troubleshooting. A good practice to avoid potential performance impact and logs with too many entries in the future is to disable the debug logging after the problem is solved.