Chapter 13. Logging

The log is the main 'UI' of a build tool. If it is too verbose, real warnings and problems are easily hidden by this. On the other hand you need the relevant information for figuring out if things have gone wrong. Gradle defines 6 log levels, as shown in Table 13.1, “Log levels”. There are two Gradle-specific log levels, in addition to the ones you might normally see. Those levels are QUIET and LIFECYCLE. The latter is the default, and is used to report build progress.

Table 13.1. Log levels

Level	Used for
ERROR	Error messages
QUIET	Important information messages
WARNING	Warning messages
LIFECYCLE	Progress information messages
INFO	Information messages
DEBUG	Debug messages

13.1. Choosing a log level

You can use the command line switches shown in Table 13.2, “Log level command-line options” to choose different log levels. In Table 13.3, “Stacktrace command-line options” you find the command line switches which affect stacktrace logging.

Table 13.2. Log level command-line options

Option	Outputs Log Levels
no logging options	LIFECYCLE and higher
`-q`	QUIET and higher
`-i`	INFO and higher
`-d`	DEBUG and higher (that is, all log messages)

Table 13.3. Stacktrace command-line options

Option	Meaning
No stacktrace options	No stacktraces are printed to the console in case of a build error (e.g. a compile error). Only in case of internal exceptions will stacktraces be printed. If the loglevel option `-d` is chosen, truncated stacktraces are always printed.
`-s`	Truncated stacktraces are printed. We recommend this over full stacktraces. Groovy full stacktraces are extremely verbose (Due to the underlying dynamic invocation mechanisms. Yet they usually do not contain relevant information for what has gone wrong in your code.)
`-f`	The full stacktraces are printed out.

13.2. External tools and standard output

Internally, Gradle uses Ant and Ivy. Both have their own logging system. Gradle injects an adapter into the Ant and Ivy logging systems to redirect their logging output into the Gradle logging system. There is a 1:1 mapping from the Ant/Ivy log levels to the Gradle log levels, except the Ant/Ivy TRACE level, which is mapped to Gradle DEBUG. This means the default Gradle log level does not show any Ant/Ivy output unless it is an error or a warning.

There are many tools out there which still use standard output for logging. Gradle redirects by default standard out to the QUIET level and standard err to the ERROR level. This behavior is configurable. Gradle provides a couple of switches for this. To change the log level, standard out is redirected to, when your build script gets evaluated, the project object offers a method called Project.captureStandardOutput() . To change the log level for standard out during task execution, tasks offer a method also with the name Task.captureStandardOutput() . Tasks and projects also offer a method disableStandardOutputCapture which causes the standard out to be send to the default standard out. If you need more fine grained control on how standard out is redirected you can use the class StandardOutputLogging .

13.3. Sending your own log messages

Gradle provides a logger property to a build script, which is an instance of a slf4j logger. Here is the code of the logging integration test, which shows you how to use the logger, as well as working with standard out redirection.

Example 13.1. Sending your own log message

build.gradle

logger.info(Logging.QUIET, prefix + "quietLog")
logger.info(Logging.LIFECYCLE, prefix + "lifecycleLog")
logger.info(prefix + "infoLog")
logger.debug(prefix + "debugLog")
logger.warn(prefix + "warnLog")
logger.error(prefix + "errorLog")
println(prefix + 'quietOut')
captureStandardOutput(LogLevel.INFO)
println(prefix + 'infoOut')

task logLifecycle << {
    println(prefix + 'lifecycleTaskOut')
}
logLifecycle.captureStandardOutput(LogLevel.LIFECYCLE)

task logInfo << {
    println(prefix + 'infoTaskOut')
}
logInfo.captureStandardOutput(LogLevel.INFO)

task log(dependsOn: [logInfo, logLifecycle]) << {
    println(prefix + 'quietTaskOut')
}

Strictly speaking, QUIET and LIFECYCLE are not log levels, but they are markers. But logically Gradle treats them as log levels. In a future version of Gradle we want to provide a logger which provides additional log methods quiet and lifecycle.

You can also hook into Gradle's logging system from within other classes (classes from the buildSrc directory for example). Simply use a slf4j logger.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;    

public class MyClass {
    private static Logger logger = LoggerFactory.getLogger(MyClass.class);
    ...

You can use this logger the same way as you use the provided logger in the build script.