scala-logging

Scala Logging is a convenient and fast logging library wrapping SLF4J.

It's convenient, because you can simply call log methods, without checking whether the respective log level is enabled:

logger.debug(s"Some $expensive message!")

It's fast, because thanks to Scala macros the check-enabled-idiom is applied and the following code is generated:

if (logger.isDebugEnabled) logger.debug(s"Some $expensive message!")

Prerequisites

Java 6 or higher
Scala 2.11 or 2.12
Logging backend compatible with SLF4J

A compatible logging backend is Logback, add it to your sbt build definition:

libraryDependencies += "ch.qos.logback" % "logback-classic" % "1.2.3"

If you are looking for a version compatible with Scala 2.10, check out Scala Logging 2.x.

Getting Scala Logging

Scala Logging is published to Sonatype OSS and Maven Central:

Group id / organization: com.typesafe.scala-logging
Artifact id / name: scala-logging
Latest version is 3.9.0

Usage with SBT, adding a dependency to the latest version of Scala Logging to your sbt build definition file:

libraryDependencies += "com.typesafe.scala-logging" %% "scala-logging" % "3.9.0"

Using Scala Logging

The Logger class from the com.typesafe.scalalogging package wraps an underlying SLF4J logger. In order to create a Logger, you pass a name to the apply factory method defined in the Logger companion object:

val logger = Logger("name")

Or, you pass in a SLF4J logger instance:

val logger = Logger(LoggerFactory.getLogger("name"))

Or, you pass in a class:

val logger = Logger(classOf[MyClass])

Or, using the runtime class wrapped by the implicit class tag parameter:

val logger = Logger[MyClass]

The LazyLogging and StrictLogging traits from the com.typesafe.scalalogging package define the logger member as a lazy or strict value respectively. In both cases the underlying SLF4J logger is named according to the class into which these traits are mixed:

class MyClass extends LazyLogging {
  logger.debug("This is very convenient ;-)")
  
  logger.whenDebugEnabled {
    println("This would only execute when the debug level is enabled.")
    (1 to 10).foreach(x => println("Scala logging is great!"))
  }
}

LoggerTakingImplicit provides the same methods as Logger class, but with additional implicit parameter A. During creation of the LoggerTakingImplicit evidence CanLog[A] is required. It may be useful when contextual parameter (e.g. Correlation ID) is being passed around and you would like to include it in the log messages:

case class CorrelationId(value: String)
implicit case object CanLogCorrelationId extends CanLog[CorrelationId] {
  override def logMessage(originalMsg: String, a: CorrelationId): String = s"${a.value} $originalMsg"
}
 
implicit val correlationId = CorrelationId("ID") 
 
val logger = Logger.takingImplicit[CorrelationId]("test")
logger.info("Test") // takes implicit correlationId and logs "ID Test"

It's possible to use MDC through CanLog without any troubles with execution context.

case class CorrelationId(value: String)
implicit case object CanLogCorrelationId extends CanLog[CorrelationId] {
  override def logMessage(originalMsg: String, a: CorrelationId): String = {
    MDC.put("correlationId", a.value)
    originalMsg
  }
  
  override def afterLog(a: CorrelationId): Unit = {
    MDC.remove("correlationId")
  }
}
 
implicit val correlationId = CorrelationId("ID") 
 
val logger = Logger.takingImplicit[CorrelationId]("test")

def serviceMethod(implicit correlationId: CorrelationId): Future[Result] = {
  dbCall.map { value => 
    logger.trace(s"Received value $value from db") // takes implicit correlationId
    toResult(value)
  }
}

What's new?

3.9.0

Functions for on demand code execution added in Logger class

3.8.0

Added LoggerTakingImplicit, bugfixes.

3.7.2

Make logger to consume args of type Any with slf4 interpolator.

3.7.1

Remove @volatile from lazy logger, failing with strict compiler settings

3.7.0

Deconstruct Scala's string interpolation into SLF4J string interpolation.

3.6.0 - flawed release

3.5.0

More Logger factory methods, bugfixes and upgrades, published for Scala 2.12.0-M5, 2.12.0-RC1, 2.12.0-RC2 and 2.12.0.

3.4.0

Fixes #38 - Logger.info() cannot be used with primitive types.

3.3.0

Fixes #42 - Request: Add Logger(class). README changes.

3.2.0

SLF4J loggers and our Logger now survive serialization. By survive serialization, we mean that the deserialized logger instances are fully functional.

String Interpolation

It is idiomatic to use Scala's string interpolation logger.error(s"log $value") instead of SLF4J string interpolation logger.error("log {}", value). However there are some tools (such as Sentry) that use the log message format as grouping key. Therefore they do not work well with Scala's string interpolation.

Scala Logging replaces simple string interpolations with their SLF4J counterparts like this:

logger.error(s"my log message: $arg1 $arg2 $arg3")

logger.error("my log message: {} {} {}", arg1, arg2, arg3)

This has no effect on behavior and performace should be comparable (depends on the underlying logging library).

Limitations

Works only when string interpolation is directly used inside the logging statement. That is when the log message is static (available at compile time).
Works only for the logger.<level>(message) and logger.<level>(marker, message) logging methods. It does not work if you want to log an exception and use string interpolation too (this is a limitation of the SLF4J API).

Line numbers in log message?

Using the sourcecode library, it's possible to add line number information (especially useful for debugging):

def foo(arg: String)(implicit line: sourcecode.Line, file: sourcecode.File) = {
  ... do something with arg ...
  ... do something with file.value ...
}

foo("hello") // the implicit sourcecode.File is filled in automatically

Debugging Scala in IntelliJ

Check out scala-trace-debug to make multithreaded bug tracing and prevention easier than ever. Provides user-friendly prints, traces, assertions, container printing, and source code printing.

Logstash

Check out logstash-logback-encoder if you're using Logstash. Provides logback encoders, layouts, and appenders to log in JSON format.

Other noteworthy tooling

https://github.com/godaddy/godaddy-logger

Maintainer

The original author Heiko Seeberger stepped down Q1 2015, starting a new adventure at codecentric. Future maintenance is taken over by Mathias Bogaert.

Contribution policy

Contributions via GitHub pull requests are gladly accepted from their original author. Before we can accept pull requests, you will need to agree to the Typesafe Contributor License Agreement online, using your GitHub account.

License

This code is open source software licensed under the Apache 2.0 License.

zhaozhi189 / scala-logging Goto Github PK

scala-logging's Introduction