Overview

Logback is one of the most popular logger implementations for Java. It works very well with the SLF4J logging facade which is used by Spincast itself.

A challenge with a regular installation of Logback is to configure it differently on each environment. For example to specify a DEBUG level for logs during development but a WARN level in production. Logback does provide a way to do some kind of conditional processing of configuration files but this involves an untyped syntax using a third-party library and requires passing extra command line arguments or setting extra environment variables.

This plugin provides an easy way to configure Logback, fully integrated with Spincast: you use Java code, with dependency injection support, and you can:

• Specify the path to the configuration file Logback should use. For example "logback-dev.xml", "logback-acc.xml" or "logback-prod.xml", depending on some logic.
• Tweak the content of the XML configuration file, for example by replacing some placeholders before Logback is configured.

Finally, if required, this plugin also allows you to dynamically generate the configurations to be used by Logback, without even requiring a configuration file at all!

Usage

Default behavior

When you add this plugin to your application, the default behavior is similar to including Logback as a regular dependency: a logback.xml file will be looked for on the classpath and its content will be used as is.

Logback Configurer

To get control over how Logback is configured, you need to bind a custom implementation of SpincastLogbackConfigurerConfig. You can extends SpincastLogbackConfigurerConfigDefault as a base for your implementation.

In this implementation, you can specify:

• ResourceInfo getResourceInfo()

  The path to the XML Logback configuration file to use.

  You can use any logic you need to pick the correct file. For example, you may choose a logback-dev.xml file during development and a logback-prod.xml file otherwise:

  @Override
  public ResourceInfo getResourceInfo() {
      String path = getAppConfig().isDevelopmentMode() ? "/config/logback-dev.xml" : 
                                                         "/config/logback-prod.xml";
      return new ResourceInfo(path, true);
  }
  

  By returning an instance of ResourceInfo, you specify if the path you provide refers to a file on the classpath or on the file system.

  Note that you can also return null here! By doing so, you are responsible to provide the full XML configuration, as a String, in the tweakContent(...) method.

• String tweakContent(String logbackContent)

  This method allows you to modify the content of the configurations as loaded using the getResourceInfo() method.

  If you return null from getResourceInfo(), you will receive an empty String and you are responsible to build the entire XML configurations for Logback.

  A common usage of this method is to replace some placeholders in the base XML content. For example, let's say the content of the file is:

  <?xml version="1.0" encoding="UTF-8"?>
  <configuration>
      <appender name="stdout" class="ch.qos.logback.core.ConsoleAppender">
          <encoder>
              <charset>UTF-8</charset>
              <pattern>%d{yyyy-MM-dd HH:mm:ss} [%level] %msg ~ %caller{1}</pattern>
          </encoder>
      </appender>
      <root level="{{LEVEL}}">
          <appender-ref ref="stdout"/>
      </root>
  </configuration>

  You could use tweakContent(...) to replace the {{LEVEL}} placeholder using logic such as:

  @Override
  public String tweakContent(String logbackContent) {
      String level = getAppConfig().isDevelopmentMode() ? "debug" : "warn";
      return logbackContent.replace("{{LEVEL}}", level);
  }

  Note that you could also use the Templating Engine here to replace such placeholders!

Your SpincastLogbackConfigurerConfig implementation will be automatically used by the SpincastLogbackConfigurer component that the plugin will bind using asEagerSingleton(). Because of this, Logback is going to be configured very early during the application startup.

Installation

1. Add this Maven artifact to your project:

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-logback-utils</artifactId>
    <version>2.2.0</version>
</dependency>

2. Add an instance of the SpincastLogbackUtilsPlugin plugin to your Spincast Bootstrapper:

Spincast.configure()
        .plugin(new SpincastLogbackUtilsPlugin())
        // ...