Advanced Logging

Note: Log4j 1 and Log4j 2

In Jira 9.5, Atlassian upgraded the Log4j runtime logging library to version 2. If you have Jira 9.4 or sooner, you should use the Log4j 1. If you have Jira 9.5 or later, you should use the Log4j 2. Read more about this change in Atlassian's documentation on Migrating custom logging configurations to Log4j 2.

What is the variable 'log'?

The log variable is injected into every ScriptRunner inline script, and its value is equivalent to:

def log = Logger.getLogger("com.onresolve.scriptrunner.runner.ScriptRunnerImpl")

log is an instance of a Logger.

Using your own logger

It might be preferable to use your own logger so that you can adjust logging levels separately from ScriptRunner as a whole.

In an inline script, or file, you can do this using the following code:

import org.apache.log4j.Logger

def log = Logger.getLogger("com.acme.workflows")
log.warn("Workflow function running...")

If you use classes, the simplest way to get a logger is to use the @Log4j annotation:

package com.acme.workflows

import groovy.util.logging.Log4j

@Log4j
class Foo {

    void utilityMethod() {
        log.warn "Foo.utilityMethod"
    }
}

In the above example, the log instance is automatically created and will have the category com.acme.workflows.Foo that is, the fully qualified class name.

This is the best way of logging, as it will automatically wrap calls to the logger in the relevant guarding function, e.g., if (log.isDebugEnabled()) {log.debug(…)}

Log Levels

A log message is printed if the logging level is the same or higher than the configured level for that category.

Tip: For detailed information on logging levels, see log4j Logging Levels.

The default log level for most categories is WARN. Take a note of the default log level before making any changes. Therefore, if you want to use log.debug, the category level must be set to DEBUG or TRACE.

Tip: Take a note of the default log level before making any changes.

Temporarily enable ScriptRunner logging under System → Logging and Profiling in the Administration menu. Set the com.onresolve package to DEBUG under Default Loggers.

Note: This sets the logging level until the instance is restarted or the logging level is changed manually (to the default WARN for example).

You can change the logging level permanently by adjusting the log4j.properties (log4j) or log4j2.xml (log4j2) files—see the Atlassian Jira Logging Levels documentation.

Note: Unless you have changed your default output log file, ScriptRunner logs to the atlassian-jira.log file under <JiraHome>/log/ for more information see the Atlassian Logging and Profiling documentation.

Using another file for logging

By default, all log entries go to "atlassian-jira.log". However, you might want to have your scripts, or ScriptRunner itself, log to another file.

This can help you remove noise and debug your scripts more efficiently.

Log4J 1

Now let's break down creating your own appender and then forwarding the ScriptRunner logs to the appender.

Step 1: Create your own appender

The logger is configured in your log4j.properties file. This file can be found by default at WEB-INF/classes path within your JIRA_HOME directory.

Log4J uses its own structure to output to different log files. First of all you need to create your own appender.

This is the entity that dispatches the messages from the plugin to the correct file. Our appender will be called "ScriptRunnerLogger".

Insert the following code anywhere within your log4j.properties file:

#ScriptRunner logger
log4j.appender.ScriptRunnerLogger=com.atlassian.jira.logging.JiraHomeAppender
#Here you define the log file name
log4j.appender.ScriptRunnerLogger.File=ScriptRunnerLogFile.log
log4j.appender.ScriptRunnerLogger.MaxFileSize=20480KB
log4j.appender.ScriptRunnerLogger.MaxBackupIndex=5
log4j.appender.ScriptRunnerLogger.layout=com.atlassian.logging.log4j.NewLineIndentingFilteringPatternLayout
log4j.appender.ScriptRunnerLogger.layout.ConversionPattern=%d %t %p %X{jira.username} [%c{4}] %m%n

You can modify various settings here. For instance, to change the layout, see the documentation on PatternLayout.

Step 2: Forward the ScriptRunner logs to the appender

Once we have the appender, we need to tell your package to use it.

If you wanted to simply move the ScriptRunner logs to another file, you would, after the code above, add the following snippet:
1
2
log4j.logger.com.onresolve = WARN, console, ScriptRunnerLogger log4j.additivity.com.onresolve = false
If you have followed the advice above and used your own category, you could instead (or as well) add:
1
2
log4j.logger.com.acme = DEBUG, console, ScriptRunnerLogger log4j.additivity.com.acme = false
This sets the logging threshold to DEBUG … you may wish to set it to INFO or WARN.
Once this is done, it is important that you restart your Jira instance.
If you don't, the changes will not be picked up.

Any logging that you use, that is in the plugin itself, will be forwarded to your new "ScriptRunnerLoggerLogFile.log"

Log4J 2

Step 1: Create your own appender

The logger is configured in your log4j2.xml file. This file can be found by default at WEB-INF/classes path within your JIRA_HOME directory.

Log4J uses its own structure to output to different log files. First of all you need to create your own appender.

This is the entity that dispatches the messages from the plugin to the correct file. Our appender will be called ScriptRunnerLogger.

You can insert the following code into your log4j.xml file:

<Appenders>
  <JiraHomeAppender name="ScriptRunnerLogger"
                  fileName="ScriptRunnerLogFile.log"
                  filePattern="ScriptRunnerLogFile.log.%i">
    <PatternLayout alwaysWriteExceptions="false">
      <Pattern>
        %d %t %p %X{jira.username} [%c{2}] %m%n
      </Pattern>
    </PatternLayout>
    <Policies>
      <SizeBasedTriggeringPolicy size="20480 KB"/>
    </Policies>
    <DefaultRolloverStrategy fileIndex="min" max="5"/>
  </JiraHomeAppender>
</Appenders>

You can modify various settings here. For instance, to change the layout see the documentation on PatternLayout.

Step 2: Forward the ScriptRunner logs to the appender

Once we have the appender, we need to tell your package to use it.

If you wanted to simply move the ScriptRunner logs to another file, you would add the following snippet under the appenders defined above:
1
2
3
4
5
<Loggers> <Logger name="com.onresolve" level="WARN" additivity="false"> <AppenderRef ref="ScriptRunnerLogger"/> </Logger> </Loggers>
If you have followed the advice above and used your own category, you could instead (or as well) add:
1
2
3
4
5
<Loggers> <Logger name="com.acme" level="DEBUG" additivity="false"> <AppenderRef ref="ScriptRunnerLogger"/> </Logger> </Loggers>
This sets the logging threshold to DEBUG … you may wish to set it to INFO or WARN.
Once this is done, it is important that you restart your Jira instance.
If you don't, the changes will not be picked up.

Any logging that you use, that is in the plugin itself, will be forwarded to your new "ScriptRunnerLoggerLogFile.log"