Play Logback

Play Logback is a Logback integration module for the Play Framework that provides seamless logging configuration and colored console output. It implements Play's LoggerConfigurator interface to bridge the gap between Play applications and Logback's powerful logging infrastructure.

Package Information

• Package Name: play-logback
• Package Type: Maven
• Artifact: com.typesafe.play:play-logback_2.11
• Language: Scala (JVM 8+)
• Installation:

SBT:

libraryDependencies += "com.typesafe.play" %% "play-logback" % "2.7.9"

Maven:

<dependency>
  <groupId>com.typesafe.play</groupId>
  <artifactId>play-logback_2.11</artifactId>
  <version>2.7.9</version>
</dependency>

Core Imports

import play.api.libs.logback.LogbackLoggerConfigurator
import play.api.libs.logback.ColoredLevel
import play.api.{Environment, Configuration, Mode}

Basic Usage

Play Logback is typically used automatically by the Play Framework through its service discovery mechanism. It requires no direct instantiation by application developers:

// The LogbackLoggerConfigurator is automatically discovered and used
// by Play Framework during application startup via logger-configurator.properties

// However, if manual configuration is needed:
import play.api.libs.logback.LogbackLoggerConfigurator
import play.api.{Environment, Configuration, Mode}
import java.io.File

val configurator = new LogbackLoggerConfigurator()
val env = Environment(new File("."), getClass.getClassLoader, Mode.Dev)

// Initialize logging
configurator.configure(env, Configuration.empty, Map.empty)

// Later, shutdown logging
configurator.shutdown()

Architecture

Play Logback provides two main components:

1. LogbackLoggerConfigurator: The main integration class that implements Play's LoggerConfigurator interface, handling initialization, configuration, and shutdown of Logback logging
2. ColoredLevel: A Logback converter that provides colored console output for different log levels

The module integrates with Play's application lifecycle and supports multiple configuration discovery mechanisms, making it flexible for different deployment scenarios.

Capabilities

Logger Configuration

The LogbackLoggerConfigurator class provides comprehensive Logback integration for Play Framework applications.

class LogbackLoggerConfigurator extends LoggerConfigurator {
  def loggerFactory: org.slf4j.ILoggerFactory
  def init(rootPath: java.io.File, mode: play.api.Mode): Unit
  def configure(env: play.api.Environment): Unit
  def configure(env: play.api.Environment, configuration: play.api.Configuration, optionalProperties: Map[String, String]): Unit
  def configure(properties: Map[String, String], config: Option[java.net.URL]): Unit
  def shutdown(): Unit
}

Key Methods:

• loggerFactory: Returns the underlying SLF4J logger factory instance (Logback's LoggerContext)
• init: Initialize logging when no application ClassLoader is available, using simple file path and mode
• configure (simple): Configure with environment only, using empty configuration and no optional properties
• configure (full): Configure with complete application context including environment, configuration, and optional properties
• configure (low-level): Configure with pre-assembled properties map and optional configuration URL
• shutdown: Properly shutdown the logging infrastructure, including SLF4J bridge cleanup

Configuration Discovery:

The configurator searches for configuration in this order:

1. System property logger.resource - classpath resource path
2. System property logger.file - file system path
3. System property logger.url - direct URL
4. Default Logback auto-configuration sequence:
   • logback-test.xml (Test mode only)
   • logback.groovy
   • logback.xml
   • logback-play-dev.xml (Dev mode) or logback-play-default.xml (other modes)

Built-in Configuration Files:

The module includes three pre-configured Logback configuration files:

• logback-play-dev.xml: Development mode configuration with colored console output
• logback-play-default.xml: Production mode configuration with async console appender and shutdown hook
• logback-play-logSql.xml: SQL logging configuration with file and console appenders, specifically configured for JDBC logging with org.jdbcdslog loggers

Thread Safety:

All configuration operations are synchronized on the logger factory instance to prevent concurrent modification issues during application testing.

Colored Console Output

The ColoredLevel converter provides colored log level output for improved readability during development.

class ColoredLevel extends ch.qos.logback.classic.pattern.ClassicConverter {
  def convert(event: ch.qos.logback.classic.spi.ILoggingEvent): String
}

Color Mapping:

• TRACE → [trace] in blue
• DEBUG → [debug] in cyan
• INFO → [info] in white
• WARN → [warn] in yellow
• ERROR → [error] in red

Usage in Logback Configuration:

<configuration>
  <conversionRule conversionWord="coloredLevel" converterClass="play.api.libs.logback.ColoredLevel" />
  
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%coloredLevel %logger{15} - %message%n%xException{10}</pattern>
    </encoder>
  </appender>
</configuration>

SQL Logging Configuration:

The logback-play-logSql.xml configuration provides specialized SQL logging support with both file and console output:

<configuration>
  <conversionRule conversionWord="coloredLevel" converterClass="play.api.libs.logback.ColoredLevel" />
  
  <!-- File logging -->
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
     <file>${application.home:-.}/logs/application.log</file>
     <encoder>
       <pattern>%date [%level] from %logger in %thread - %message%n%xException</pattern>
     </encoder>
  </appender>

  <!-- JDBC logging configuration -->
  <logger name="org.jdbcdslog.ConnectionLogger" level="OFF" />   <!-- Won't log connections -->
  <logger name="org.jdbcdslog.StatementLogger"  level="INFO" />  <!-- Will log all statements -->
  <logger name="org.jdbcdslog.ResultSetLogger"  level="OFF" />   <!-- Won't log result sets -->
</configuration>

Integration Features

JUL Bridge Configuration:

The LogbackLoggerConfigurator automatically:

• Removes existing java.util.logging handlers
• Installs SLF4J bridge for JUL-to-SLF4J routing
• Configures LevelChangePropagator for performance optimization
• Adds Play framework packages to exclusion list for accurate logging location detection

Property Management:

Supports dynamic property injection:

• Automatic application.home property from environment root path
• Optional inclusion of all Play configuration properties via play.logger.includeConfigProperties=true
• Custom properties through the optionalProperties parameter

Service Discovery:

Registered via logger-configurator.properties:

play.logger.configurator=play.api.libs.logback.LogbackLoggerConfigurator

This enables automatic discovery by Play Framework's LoggerConfigurator.apply() method during application startup.

Types

// From Play Framework Core (dependencies)
trait LoggerConfigurator {
  def init(rootPath: java.io.File, mode: Mode): Unit
  def configure(env: Environment): Unit
  def configure(env: Environment, configuration: Configuration, optionalProperties: Map[String, String]): Unit
  def configure(properties: Map[String, String], config: Option[java.net.URL]): Unit
  def loggerFactory: org.slf4j.ILoggerFactory
  def shutdown(): Unit
}

sealed trait Mode
object Mode {
  case object Dev extends Mode
  case object Prod extends Mode  
  case object Test extends Mode
}

case class Environment(
  rootPath: java.io.File,
  classLoader: ClassLoader,
  mode: Mode
)

case class Configuration(underlying: com.typesafe.config.Config)

Error Handling

Configuration Errors:

If no Logback configuration is found, the configurator prints an error message to System.err but continues execution:

Could not detect a logback configuration file, not configuring logback

Logback Status Messages:

Configuration errors and warnings are automatically printed via ch.qos.logback.core.util.StatusPrinter.printIfErrorsOccured().

Service Discovery Failures:

If the LogbackLoggerConfigurator class cannot be loaded, Play Framework falls back to no-op logging configuration with appropriate error messages.

Dependencies

• Logback Classic (ch.qos.logback:logback-classic:1.2.3) - Core logging implementation
• SLF4J API (org.slf4j:slf4j-api) - Logging facade interface
• Play Framework Core (com.typesafe.play:play) - LoggerConfigurator interface, utilities, and Colors utility for ColoredLevel converter