0
# Akka SLF4J
1
2
Akka SLF4J provides seamless integration between Akka's actor-based logging system and the Simple Logging Facade for Java (SLF4J) framework. It enables Akka applications to leverage SLF4J's flexible logging architecture while maintaining compatibility with Akka's built-in logging mechanisms.
3
4
## Package Information
5
6
- **Package Name**: akka-slf4j_2.10
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to your SBT build:
10
```scala
11
libraryDependencies += "com.typesafe.akka" %% "akka-slf4j" % "2.3.16"
12
```
13
- **Maven Coordinate**: `com.typesafe.akka:akka-slf4j_2.10:2.3.16`
14
15
## Core Imports
16
17
```scala
18
import akka.event.slf4j._
19
```
20
21
For specific components:
22
23
```scala
24
import akka.event.slf4j.{SLF4JLogging, Logger, Slf4jLogger}
25
```
26
27
## Basic Usage
28
29
```scala
30
import akka.actor.{ActorSystem, ActorLogging, Actor, Props}
31
import akka.event.slf4j.{SLF4JLogging, Slf4jLogger}
32
import com.typesafe.config.ConfigFactory
33
34
// Configure Akka to use SLF4J logger
35
val system = ActorSystem("MySystem", ConfigFactory.parseString("""
36
akka {
37
loggers = ["akka.event.slf4j.Slf4jLogger"]
38
loglevel = "INFO"
39
}
40
"""))
41
42
// Use SLF4JLogging trait in your classes
43
class MyService extends SLF4JLogging {
44
def process(data: String): Unit = {
45
log.info("Processing data: {}", data)
46
log.debug("Debug information")
47
}
48
}
49
50
// Use in actors with ActorLogging
51
class MyActor extends Actor with ActorLogging {
52
def receive = {
53
case msg =>
54
log.info("Received message: {}", msg)
55
}
56
}
57
58
val myActor = system.actorOf(Props[MyActor], "myActor")
59
```
60
61
## Architecture
62
63
Akka SLF4J provides three key components for logging integration:
64
65
- **SLF4JLogging Trait**: Provides convenient logging access to any class
66
- **Logger Object**: Factory for creating SLF4J logger instances
67
- **Slf4jLogger Actor**: Core logging actor that handles log events and manages MDC context
68
69
The integration automatically populates SLF4J's Mapped Diagnostic Context (MDC) with valuable debugging information including source thread names, Akka source identifiers, and timestamps.
70
71
## Capabilities
72
73
### SLF4JLogging Trait
74
75
Base trait for classes that want to use the SLF4J logging infrastructure.
76
77
```scala { .api }
78
trait SLF4JLogging {
79
/** Lazy-initialized logger for the class name */
80
@transient
81
lazy val log: org.slf4j.Logger
82
}
83
```
84
85
**Usage Example:**
86
87
```scala
88
import akka.event.slf4j.SLF4JLogging
89
90
class UserService extends SLF4JLogging {
91
def createUser(name: String): User = {
92
log.info("Creating user: {}", name)
93
// ... business logic
94
log.debug("User created successfully")
95
user
96
}
97
}
98
```
99
100
### Logger Factory
101
102
Factory object for obtaining SLF4J logger instances.
103
104
```scala { .api }
105
object Logger {
106
/**
107
* Creates a logger for the given logger name
108
* @param logger Logger name as string
109
* @return SLF4J Logger instance
110
*/
111
def apply(logger: String): org.slf4j.Logger
112
113
/**
114
* Creates a logger for the specified class and source
115
* @param logClass The class to log for
116
* @param logSource The textual representation of the source
117
* @return SLF4J Logger instance
118
*/
119
def apply(logClass: Class[_], logSource: String): org.slf4j.Logger
120
121
/**
122
* Returns the SLF4J Root Logger
123
* @return Root logger instance
124
*/
125
def root: org.slf4j.Logger
126
}
127
```
128
129
**Usage Examples:**
130
131
```scala
132
import akka.event.slf4j.Logger
133
134
// Logger by name
135
val namedLogger = Logger("com.mycompany.MyClass")
136
137
// Logger by class
138
val classLogger = Logger(classOf[MyService], "MyService")
139
140
// Root logger
141
val rootLogger = Logger.root
142
```
143
144
### Slf4jLogger Actor
145
146
Core logging actor that handles Akka log events and manages SLF4J MDC context.
147
148
```scala { .api }
149
class Slf4jLogger extends Actor with SLF4JLogging {
150
/** MDC attribute name for source thread */
151
val mdcThreadAttributeName: String = "sourceThread"
152
153
/** MDC attribute name for Akka source */
154
val mdcAkkaSourceAttributeName: String = "akkaSource"
155
156
/** MDC attribute name for Akka timestamp */
157
val mdcAkkaTimestamp: String = "akkaTimestamp"
158
159
/** Actor receive method handling log events */
160
def receive: Receive
161
162
/**
163
* Sets MDC context for logging operations (inline final method)
164
* @param logSource The source of the log event
165
* @param logEvent The log event containing metadata
166
* @param logStatement The logging statement to execute (call-by-name)
167
*/
168
@inline
169
final def withMdc(logSource: String, logEvent: LogEvent)(logStatement: => Unit): Unit
170
171
/**
172
* Formats timestamp to UTC string (overridable)
173
* @param timestamp Timestamp in milliseconds
174
* @return Formatted UTC timestamp string
175
*/
176
protected def formatTimestamp(timestamp: Long): String
177
}
178
```
179
180
### Log Event Handling
181
182
The Slf4jLogger actor handles these Akka log event types:
183
184
```scala { .api }
185
// Error events with optional exception
186
case class Error(cause: Throwable, logSource: String, logClass: Class[_], message: Any)
187
188
// Warning events
189
case class Warning(logSource: String, logClass: Class[_], message: Any)
190
191
// Info events
192
case class Info(logSource: String, logClass: Class[_], message: Any)
193
194
// Debug events
195
case class Debug(logSource: String, logClass: Class[_], message: Any)
196
197
// Logger initialization (responds with LoggerInitialized)
198
case class InitializeLogger(bus: LoggingBus)
199
200
// Response to logger initialization
201
case object LoggerInitialized
202
```
203
204
## Configuration
205
206
Configure Akka to use the SLF4J logger in your `application.conf`:
207
208
```hocon
209
akka {
210
# Use SLF4J logger
211
loggers = ["akka.event.slf4j.Slf4jLogger"]
212
213
# Set log level
214
loglevel = "INFO"
215
216
# Optional: Set startup timeout
217
logger-startup-timeout = 30s
218
}
219
```
220
221
## MDC Context
222
223
The logger automatically populates SLF4J's Mapped Diagnostic Context with:
224
225
- **sourceThread**: Name of the thread performing the logging
226
- **akkaSource**: Akka source identifier (actor path, etc.)
227
- **akkaTimestamp**: UTC timestamp of the log event
228
- **Custom MDC values**: Any additional context from the log event
229
230
**Example MDC usage with custom values:**
231
232
```scala
233
import akka.actor.{Actor, DiagnosticActorLogging}
234
import akka.event.Logging.MDC
235
236
class OrderProcessor extends Actor with DiagnosticActorLogging {
237
def receive = {
238
case ProcessOrder(orderId, customerId) =>
239
// Set custom MDC values
240
log.mdc(Map(
241
"orderId" -> orderId,
242
"customerId" -> customerId
243
))
244
245
log.info("Processing order")
246
247
// Clear MDC when done
248
log.clearMDC()
249
}
250
}
251
```
252
253
## Error Handling
254
255
The logger handles exceptions in log events by:
256
257
- Logging the exception message and stack trace for errors with causes
258
- Logging just the message for errors without causes (Error.NoCause or null)
259
- Preserving the original exception information in SLF4J format
260
261
**Example error logging:**
262
263
```scala
264
import akka.actor.{Actor, ActorLogging}
265
266
class DataProcessor extends Actor with ActorLogging {
267
def receive = {
268
case ProcessData(data) =>
269
try {
270
// ... process data
271
} catch {
272
case ex: ValidationException =>
273
log.error(ex, "Data validation failed for: {}", data.id)
274
case ex: Exception =>
275
log.error(ex, "Unexpected error processing data")
276
}
277
}
278
}
279
```
280
281
## Types
282
283
```scala { .api }
284
// Re-exported from org.slf4j
285
type Logger = org.slf4j.Logger
286
287
// Akka logging system types (from akka.event)
288
trait LoggingBus
289
290
// Akka logging event types (from akka.event.Logging)
291
sealed trait LogEvent {
292
def logSource: String
293
def logClass: Class[_]
294
def message: Any
295
def timestamp: Long
296
def thread: Thread
297
def mdc: Map[String, Any]
298
}
299
300
case class Error(
301
cause: Throwable,
302
logSource: String,
303
logClass: Class[_],
304
message: Any
305
) extends LogEvent
306
307
case class Warning(
308
logSource: String,
309
logClass: Class[_],
310
message: Any
311
) extends LogEvent
312
313
case class Info(
314
logSource: String,
315
logClass: Class[_],
316
message: Any
317
) extends LogEvent
318
319
case class Debug(
320
logSource: String,
321
logClass: Class[_],
322
message: Any
323
) extends LogEvent
324
```