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(…​)}
Jira uses log4j 1x, if browsing the documentation be sure you are not looking at the documentation for log4j 2x.

Log levels

A log message will only be printed if the "level" is the same or higher than the configured level for that category. This is a longer explanation here.

The default log level for most categories is WARN. Thus if you want to use use log.debug, you must be set the category level to DEBUG or TRACE.

A simple way to change the level for a category is via a script, which you can run from the Script Console:

import org.apache.log4j.Level
import org.apache.log4j.Logger

def log = Logger.getLogger("com.acme.workflows")
log.setLevel(Level.DEBUG)

This will set the level until you change it back (replace Level.DEBUG with Level.WARN), or until the application instance is restarted.

You can change it permanently by adjusting the log4j.properties files - see the Jira documentation.

The final method of changing log levels is via the Logging and Profiling administration page, but you can only do that if there was already an entry for the category in log4j.properties.

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.

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". You can 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{{system-name}.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:

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:

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.

After doing this any logging that you use, and that is in the plugin itself, will be forwarded to your new "ScriptRunnerLoggerLogFile.log"

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.