0
# Play Logback
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: play-logback
7
- **Package Type**: Maven
8
- **Artifact**: `com.typesafe.play:play-logback_2.11`
9
- **Language**: Scala (JVM 8+)
10
- **Installation**:
11

12
SBT:
13
```scala
14
libraryDependencies += "com.typesafe.play" %% "play-logback" % "2.7.9"
15
```
16

17
Maven:
18
```xml
19
<dependency>
20
  <groupId>com.typesafe.play</groupId>
21
  <artifactId>play-logback_2.11</artifactId>
22
  <version>2.7.9</version>
23
</dependency>
24
```
25

26
## Core Imports
27

28
```scala
29
import play.api.libs.logback.LogbackLoggerConfigurator
30
import play.api.libs.logback.ColoredLevel
31
import play.api.{Environment, Configuration, Mode}
32
```
33

34
## Basic Usage
35

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

38
```scala
39
// The LogbackLoggerConfigurator is automatically discovered and used
40
// by Play Framework during application startup via logger-configurator.properties
41

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

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

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

53
// Later, shutdown logging
54
configurator.shutdown()
55
```
56

57
## Architecture
58

59
Play Logback provides two main components:
60

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

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

66
## Capabilities
67

68
### Logger Configuration
69

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

72
```scala { .api }
73
class LogbackLoggerConfigurator extends LoggerConfigurator {
74
  def loggerFactory: org.slf4j.ILoggerFactory
75
  def init(rootPath: java.io.File, mode: play.api.Mode): Unit
76
  def configure(env: play.api.Environment): Unit
77
  def configure(env: play.api.Environment, configuration: play.api.Configuration, optionalProperties: Map[String, String]): Unit
78
  def configure(properties: Map[String, String], config: Option[java.net.URL]): Unit
79
  def shutdown(): Unit
80
}
81
```
82

83
**Key Methods:**
84

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

92
**Configuration Discovery:**
93

94
The configurator searches for configuration in this order:
95
1. System property `logger.resource` - classpath resource path
96
2. System property `logger.file` - file system path
97
3. System property `logger.url` - direct URL
98
4. Default Logback auto-configuration sequence:
99
   - `logback-test.xml` (Test mode only)
100
   - `logback.groovy`
101
   - `logback.xml`
102
   - `logback-play-dev.xml` (Dev mode) or `logback-play-default.xml` (other modes)
103

104
**Built-in Configuration Files:**
105

106
The module includes three pre-configured Logback configuration files:
107

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

112
**Thread Safety:**
113

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

116
### Colored Console Output
117

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

120
```scala { .api }
121
class ColoredLevel extends ch.qos.logback.classic.pattern.ClassicConverter {
122
  def convert(event: ch.qos.logback.classic.spi.ILoggingEvent): String
123
}
124
```
125

126
**Color Mapping:**
127
- TRACE → `[trace]` in blue
128
- DEBUG → `[debug]` in cyan  
129
- INFO → `[info]` in white
130
- WARN → `[warn]` in yellow
131
- ERROR → `[error]` in red
132

133
**Usage in Logback Configuration:**
134

135
```xml
136
<configuration>
137
  <conversionRule conversionWord="coloredLevel" converterClass="play.api.libs.logback.ColoredLevel" />
138
  
139
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
140
    <encoder>
141
      <pattern>%coloredLevel %logger{15} - %message%n%xException{10}</pattern>
142
    </encoder>
143
  </appender>
144
</configuration>
145
```
146

147
**SQL Logging Configuration:**
148

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

151
```xml
152
<configuration>
153
  <conversionRule conversionWord="coloredLevel" converterClass="play.api.libs.logback.ColoredLevel" />
154
  
155
  <!-- File logging -->
156
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
157
     <file>${application.home:-.}/logs/application.log</file>
158
     <encoder>
159
       <pattern>%date [%level] from %logger in %thread - %message%n%xException</pattern>
160
     </encoder>
161
  </appender>
162

163
  <!-- JDBC logging configuration -->
164
  <logger name="org.jdbcdslog.ConnectionLogger" level="OFF" />   <!-- Won't log connections -->
165
  <logger name="org.jdbcdslog.StatementLogger"  level="INFO" />  <!-- Will log all statements -->
166
  <logger name="org.jdbcdslog.ResultSetLogger"  level="OFF" />   <!-- Won't log result sets -->
167
</configuration>
168
```
169

170
### Integration Features
171

172
**JUL Bridge Configuration:**
173

174
The LogbackLoggerConfigurator automatically:
175
- Removes existing java.util.logging handlers
176
- Installs SLF4J bridge for JUL-to-SLF4J routing
177
- Configures LevelChangePropagator for performance optimization
178
- Adds Play framework packages to exclusion list for accurate logging location detection
179

180
**Property Management:**
181

182
Supports dynamic property injection:
183
- Automatic `application.home` property from environment root path
184
- Optional inclusion of all Play configuration properties via `play.logger.includeConfigProperties=true`
185
- Custom properties through the optionalProperties parameter
186

187
**Service Discovery:**
188

189
Registered via `logger-configurator.properties`:
190
```properties
191
play.logger.configurator=play.api.libs.logback.LogbackLoggerConfigurator
192
```
193

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

196
## Types
197

198
```scala { .api }
199
// From Play Framework Core (dependencies)
200
trait LoggerConfigurator {
201
  def init(rootPath: java.io.File, mode: Mode): Unit
202
  def configure(env: Environment): Unit
203
  def configure(env: Environment, configuration: Configuration, optionalProperties: Map[String, String]): Unit
204
  def configure(properties: Map[String, String], config: Option[java.net.URL]): Unit
205
  def loggerFactory: org.slf4j.ILoggerFactory
206
  def shutdown(): Unit
207
}
208

209
sealed trait Mode
210
object Mode {
211
  case object Dev extends Mode
212
  case object Prod extends Mode  
213
  case object Test extends Mode
214
}
215

216
case class Environment(
217
  rootPath: java.io.File,
218
  classLoader: ClassLoader,
219
  mode: Mode
220
)
221

222
case class Configuration(underlying: com.typesafe.config.Config)
223
```
224

225
## Error Handling
226

227
**Configuration Errors:**
228

229
If no Logback configuration is found, the configurator prints an error message to System.err but continues execution:
230
```
231
Could not detect a logback configuration file, not configuring logback
232
```
233

234
**Logback Status Messages:**
235

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

238
**Service Discovery Failures:**
239

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

242
## Dependencies
243

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