## 3.1.2 Logging

### The Basics

Grails uses its common configuration mechanism to provide the settings for the underlying Log4j log system, so all you have to do is add a `log4j` setting to the file `grails-app/conf/Config.groovy`.

So what does this `log4j` setting look like? Here's a basic example:

    log4j = {
        error  'org.codehaus.groovy.grails.web.servlet',  //  controllers
               'org.codehaus.groovy.grails.web.pages' //  GSP    warn   'org.mortbay.log'
    }

This says that for the two 'org.codehaus.groovy.*' loggers, only messages logged at 'error' level and above will be shown. The 'org.mortbay.log' logger also shows messages at the 'warn' level. What does that mean? First of all, you have to understand how levels work.

#### Logging levels

The are several standard logging levels, which are listed here in order of descending priority:

1. off
2. fatal
3. error
4. warn
5. info
6. debug
7. trace
8. all

When you log a message, you implicitly give that message a level. For example, the method `log.error(msg)` will log a message at the 'error' level. Likewise, `log.debug(msg)` will log it at 'debug'. Each of the above levels apart from 'off' and 'all' have a corresponding log method of the same name.

The logging system uses that message level combined with the configuration for the logger (see next section) to determine whether the message gets written out. For example, if you have an 'org.example.domain' logger configured like so:

    warn 'org.example.domain'

then messages with a level of 'warn', 'error', or 'fatal' will be written out. Messages at other levels will be ignored.

Before we go on to loggers, a quick note about those 'off' and 'all' levels. These are special in that they can only be used in the configuration; you can't log messages at these levels. So if you configure a logger with a level of 'off', then no messages will be written out. A level of 'all' means that you will see all messages. Simple.

#### Loggers

Loggers are fundamental to the logging system, but they are a source of some confusion. For a start, what are they? Are they shared? How do you configure them?

A logger is the object you log messages to, so in the call `log.debug(msg)`, `log` is a logger instance (of type Log). These loggers are uniquely identified by name and if two separate classes use loggers with the same name, those loggers are effectively the same instance.

There are two main ways to get hold of a logger:

1. use the `log` instance injected into artifacts such as domain classes, controllers and services;
2. use the Commons Logging API directly.

If you use the dynamic `log` property, then the name of the logger is 'grails.app.<type>.<className>', where `type` is the type of the artifact, say 'controller' or 'service, and `className` is the fully qualified name of the artifact. For example, let's say you have this service:

    package org.exampleclass MyService {
        …
    }

then the name of the logger will be 'grails.app.service.org.example.MyService'.

For other classes, the typical approach is to store a logger based on the class name in a constant static field:

    package org.otherimport org.apache.commons.logging.LogFactoryclass MyClass {
        private static final log = LogFactory.getLog(this)
        …
    }

This will create a logger with the name 'org.other.MyClass' - note the lack of a 'grails.app.' prefix. You can also pass a name to the `getLog()` method, such as "myLogger", but this is less common because the logging system treats names with dots ('.') in a special way.

#### Configuring loggers

You have already seen how to configure a logger in Grails:

    log4j = {
        error  'org.codehaus.groovy.grails.web.servlet'
    }

This example configures a logger named 'org.codehaus.groovy.grails.web.servlet' to ignore any messages sent to it at a level of 'warn' or lower. But is there a logger with this name in the application? No. So why have a configuration for it? Because the above rule applies to any logger whose name begins with 'org.codehaus.groovy.grails.servlet.' as well. For example, the rule applies to both the `org.codehaus.groovy.grails.web.servlet.GrailsDispatcherServlet` class and the `org.codehaus.groovy.grails.web.servlet.mvc.GrailsWebRequest` one.

In other words, loggers are effectively hierarchical. This makes configuring them by package much, much simpler than it would otherwise be.

The most common things that you will want to capture log output from are your controllers, services, and other artifacts. To do that you'll need to use the convention mentioned earlier: grails.app.<artifactType>.<className> . In particular the class name must be fully qualifed, i.e. with the package if there is one:

    log4j = {
        // Set level for all application artifacts
        info "grails.app"    // Set for a specific controller
        debug "grails.app.controller.YourController"    // Set for a specific domain class
        debug "grails.app.domain.org.example.Book"    // Set for all taglibs
        info "grails.app.tagLib"
    }

The standard artifact names used in the logging configuration are:

- `bootstrap` - For bootstrap classes
- `dataSource` - For data sources
- `tagLib` - For tag libraries
- `service` - For service classes
- `controller` - For controllers
- `domain` - For domain entities

Grails itself generates plenty of logging information and it can sometimes be helpful to see that. Here are some useful loggers from Grails internals that you can use, especially when tracking down problems with your application:

- `org.codehaus.groovy.grails.commons` - Core artifact information such as class loading etc.
- `org.codehaus.groovy.grails.web` - Grails web request processing
- `org.codehaus.groovy.grails.web.mapping` - URL mapping debugging
- `org.codehaus.groovy.grails.plugins` - Log plugin activity
- `grails.spring` - See what Spring beans Grails and plugins are defining
- `org.springframework` - See what Spring is doing
- `org.hibernate` - See what Hibernate is doing

So far, we've only looked at explicit configuration of loggers. But what about all those loggers that don't have an explicit configuration? Are they simply ignored? The answer lies with the root logger.

#### The Root Logger

All logger objects inherit their configuration from the root logger, so if no explicit configuration is provided for a given logger, then any messages that go to that logger are subject to the rules defined for the root logger. In other words, the root logger provides the default configuration for the logging system.

Grails automatically configures the root logger to only handle messages at 'error' level and above, and all the messages are directed to the console (stdout for those with a C background). You can customise this behaviour by specifying a 'root' section in your logging configuration like so:

    log4j = {
        root {
            info()
        }
        …
    }

The above example configures the root logger to log messages at 'info' level and above to the default console appender. You can also configure the root logger to log to one or more named appenders (which we'll talk more about shortly):

    log4j = {
        appenders {
            file name:'file', file:'/var/logs/mylog.log'
        }
        root {
            debug 'stdout', 'file'
        }
    }

In the above example, the root logger will log to two appenders - the default 'stdout' (console) appender and a custom 'file' appender.

For power users there is an alternative syntax for configuring the root logger: the root `org.apache.log4j.Logger` instance is passed as an argument to the log4j closure. This allows you to work with the logger directly:

    log4j = { root ->
        root.level = org.apache.log4j.Level.DEBUG
        …
    }

For more information on what you can do with this `Logger` instance, refer to the Log4j API documentation.

Those are the basics of logging pretty well covered and they are sufficient if you're happy to only send log messages to the console. But what if you want to send them to a file? How do you make sure that messages from a particular logger go to a file but not the console? These questions and more will be answered as we look into appenders.

### Appenders

Loggers are a useful mechanism for filtering messages, but they don't physically write the messages anywhere. That's the job of the appender, of which there are various types. For example, there is the default one that writes messages to the console, another that writes them to a file, and several others. You can even create your own appender implementations!

This diagram shows how they fit into the logging pipeline:

As you can see, a single logger may have several appenders attached to it. In a standard Grails configuration, the console appender named 'stdout' is attached to all loggers through the default root logger configuration. But that's the only one. Adding more appenders can be done within an 'appenders' block:

    log4j = {
        appenders {
            rollingFile name: "myAppender", maxFileSize: 1024, file: "/tmp/logs/myApp.log"
        }
    }

The following appenders are available by default:

Name | Class | Description
--- | --- | ---
jdbc | JDBCAppender | Logs to a JDBC connection.
console | ConsoleAppender | Logs to the console.
file | FileAppender | Logs to a single file.
rollingFile | RollingFileAppender | Logs to rolling files, for example a new file each day.

Each named argument passed to an appender maps to a property of the underlying Appender implementation. So the previous example sets the `name`, `maxFileSize` and `file` properties of the `RollingFileAppender` instance.

You can have as many appenders as you like - just make sure that they all have unique names. You can even have multiple instances of the same appender type, for example several file appenders that log to different files.

If you prefer to create the appender programmatically or if you want to use an appender implementation that's not available via the above syntax, then you can simply declare an `appender` entry with an instance of the appender you want:

    import org.apache.log4j.*log4j = {
        appenders {
            appender new RollingFileAppender(name: "myAppender", maxFileSize: 1024, file: "/tmp/logs/myApp.log")
        }
    }

This approach can be used to configure `JMSAppender`, `SocketAppender`, `SMTPAppender`, and more.

Once you have declared your extra appenders, you can attach them to specific loggers by passing the name as a key to one of the log level methods from the previous section:

    error myAppender: "grails.app.controller.BookController"

This will ensure that the 'org.codehaus.groovy.grails.commons' logger and its children send log messages to 'myAppender' as well as any appenders configured for the root logger. If you want to add more than one appender to the logger, then add them to the same level declaration:

    error myAppender:      "grails.app.controller.BookController",
          myFileAppender:  ["grails.app.controller.BookController", "grails.app.service.BookService"],
          rollingFile:     "grails.app.controller.BookController"

The above example also shows how you can configure more than one logger at a time for a given appender (`myFileAppender`) by using a list.

Be aware that you can only configure a single level for a logger, so if you tried this code:

    error myAppender:      "grails.app.controller.BookController"
    debug myFileAppender:  "grails.app.controller.BookController"
    fatal rollingFile:     "grails.app.controller.BookController"

you'd find that only 'fatal' level messages get logged for 'grails.app.controller.BookController'. That's because the last level declared for a given logger wins. What you probably want to do is limit what level of messages an appender writes.

Let's say an appender is attached to a logger configured with the 'all' level. That will give us a lot of logging information that may be fine in a file, but makes working at the console difficult. So, we configure the console appender to only write out messages at 'info' level or above:

    log4j = {
        appenders {
            console name: "stdout", threshold: org.apache.log4j.Level.INFO
        }
    }

The key here is the `threshold` argument which determines the cut-off for log messages. This argument is available for all appenders, but do note that you currently have to specify a `Level` instance - a string such as "info" will not work.

### Custom Layouts

By default the Log4j DSL assumes that you want to use a PatternLayout. However, there are other layouts available including:

- `xml` - Create an XML log file
- `html` - Creates an HTML log file
- `simple` - A simple textual log
- `pattern` - A Pattern layout

You can specify custom patterns to an appender using the `layout` setting:

    log4j = {
        appenders {
            console name: "customAppender", layout: pattern(conversionPattern: "%c{2} %m%n")
        }
    }

This also works for the built-in appender "stdout", which logs to the console:

    log4j = {
        appenders {
            console name: "stdout", layout: pattern(conversionPattern: "%c{2} %m%n")
        }
    }

### Environment-specific configuration

Since the logging configuration is inside `Config.groovy`, you can of course put it inside an environment-specific block. However, there is a problem with this approach: you have to provide the full logging configuration each time you define the `log4j` setting. In other words, you cannot selectively override parts of the configuration - it's all or nothing.

To get round this, the logging DSL provides its own environment blocks that you can put anywhere in the configuration:

    log4j = {
        appenders {
            console name: "stdout", layout: pattern(conversionPattern: "%c{2} %m%n")        environments {
                production {
                    rollingFile name: "myAppender", maxFileSize: 1024, file: "/tmp/logs/myApp.log"
                }
            }
        }    root {
            //…
        }    // other shared config
        info "grails.app.controller"    environments {
            production {
                // Override previous setting for 'grails.app.controller'
                error "grails.app.controller"
            }
        }
    }

The one place you can't put an environment block is inside the `root` definition, but you can put the `root` definition inside an environment block.

### Full stacktraces

When exceptions occur, there can be an awful lot of noise in the stacktrace from Java and Groovy internals. Grails filters these typically irrelevant details and restricts traces to non-core Grails/Groovy class packages.

When this happens, the full trace is always logged to the `StackTrace` logger, which by default writes its output to a file called `stacktrace.log`. As with other loggers though, you can change its behaviour in the configuration. For example if you prefer full stack traces to go to the console, add this entry:

    error stdout: "StackTrace"

This won't stop Grails from attempting to create the stacktrace.log file - it just redirects where stack traces are written to. An alternative approach is to change the location of the 'stacktrace' appender's file:

    log4j = {
        appenders {
            rollingFile name: "stacktrace", maxFileSize: 1024, file: "/var/tmp/logs/myApp-stacktrace.log"
        }
    }

or, if you don't want to the 'stacktrace' appender at all, configure it as a 'null' appender:

    log4j = {
        appenders {
            'null' name: "stacktrace"
        }
    }

You can of course combine this with attaching the 'stdout' appender to the 'StackTrace' logger if you want all the output in the console.

Finally, you can completely disable stacktrace filtering by setting the `grails.full.stacktrace` VM property to `true`:

    grails -Dgrails.full.stacktrace=true run-app

### Logger inheritance

Earlier, we mentioned that all loggers inherit from the root logger and that loggers are hierarchical based on '.'-separated terms. What this means is that unless you override a parent setting, a logger retains the level and the appenders configured for that parent. So with this configuration:

    log4j = {
        appenders {
            file name:'file', file:'/var/logs/mylog.log'
        }
        root {
            debug 'stdout', 'file'
        }
    }

all loggers in the application will have a level of 'debug' and will log to both the 'stdout' and 'file' appenders. What if you only want to log to 'stdout' for a particular logger? In that case, you need to change the 'additivity' for a logger.

Additivity simply determines whether a logger inherits the configuration from its parent. If additivity is false, then its not inherited. The default for all loggers is true, i.e. they inherit the configuration. So how do you change this setting? Here's an example:

    log4j = {
        appenders {
            …
        }
        root {
            …
        }    info additivity: false
             stdout: ["grails.app.controller.BookController", "grails.app.service.BookService"]
    }

So when you specify a log level, add an 'additivity' named argument. Note that you when you specify the additivity, you must configure the loggers for a named appender. The following syntax will not work:

    info additivity: false, "grails.app.controller.BookController", "grails.app.service.BookService"