Logging (Scala)

How to Log

Create a LoggingAdapter and use the error, warning, info, or debug methods, as illustrated in this example:

import akka.event.Logging

class MyActor extends Actor {
  val log = Logging(context.system, this)
  override def preStart() = {
    log.debug("Starting")
  }
  override def preRestart(reason: Throwable, message: Option[Any]) {
    log.error(reason, "Restarting due to [{}] when processing [{}]",
      reason.getMessage, message.getOrElse(""))
  }
  def receive = {
    case "test" ⇒ log.info("Received test")
    case x      ⇒ log.warning("Received unknown message: {}", x)
  }
}

For convenience you can mixin the log member into actors, instead of defining it as above.

class MyActor extends Actor with akka.actor.ActorLogging {
  ...
}

The second parameter to the Logging is the source of this logging channel. The source object is translated to a String according to the following rules:

• if it is an Actor or ActorRef, its path is used
• in case of a String it is used as is
• in case of a class an approximation of its simpleName
• and in all other cases a compile error occurs unless and implicit LogSource[T] is in scope for the type in question.

The log message may contain argument placeholders {}, which will be substituted if the log level is enabled. Giving more arguments as there are placeholders results in a warning being appended to the log statement (i.e. on the same line with the same severity). You may pass a Java array as the only substitution argument to have its elements be treated individually:

val args = Array("The", "brown", "fox", "jumps", 42)
system.log.debug("five parameters: {}, {}, {}, {}, {}", args)

The Java Class of the log source is also included in the generated LogEvent. In case of a simple string this is replaced with a “marker” class akka.event.DummyClassForStringSources in order to allow special treatment of this case, e.g. in the SLF4J event listener which will then use the string instead of the class’ name for looking up the logger instance to use.

akka {
  loglevel = DEBUG
}

akka {
  # Log the complete configuration at INFO level when the actor system is started.
  # This is useful when you are uncertain of what configuration is used.
  log-config-on-start = on
}

akka {
  actor {
    debug {
      # enable function of LoggingReceive, which is to log any received message at
      # DEBUG level
      receive = on
    }
  }
}

akka {
  actor {
    debug {
      # enable DEBUG logging of all AutoReceiveMessages (Kill, PoisonPill and the like)
      autoreceive = on
    }
  }
}

akka {
  actor {
    debug {
      # enable DEBUG logging of actor lifecycle changes
      lifecycle = on
    }
  }
}

akka {
  actor {
    debug {
      # enable DEBUG logging of all LoggingFSMs for events, transitions and timers
      fsm = on
    }
  }
}

akka {
  actor {
    debug {
      # enable DEBUG logging of subscription changes on the eventStream
      event-stream = on
    }
  }
}

akka {
  remote {
    # If this is "on", Akka will log all outbound messages at DEBUG level, if off then they are not logged
    log-sent-messages = on
  }
}

akka {
  remote {
    # If this is "on", Akka will log all inbound messages at DEBUG level, if off then they are not logged
    log-received-messages = on
  }
}

import akka.event.LogSource
import akka.actor.ActorSystem

object MyType {
  implicit val logSource: LogSource[AnyRef] = new LogSource[AnyRef] {
    def genString(o: AnyRef): String = o.getClass.getName
    override def getClazz(o: AnyRef): Class[_] = o.getClass
  }
}

class MyType(system: ActorSystem) {
  import MyType._
  import akka.event.Logging

  val log = Logging(system, this)
}

Event Handler

Logging is performed asynchronously through an event bus. You can configure which event handlers that should subscribe to the logging events. That is done using the event-handlers element in the Configuration. Here you can also define the log level.

akka {
  # Event handlers to register at boot time (Logging$DefaultLogger logs to STDOUT)
  event-handlers = ["akka.event.Logging$DefaultLogger"]
  # Options: ERROR, WARNING, INFO, DEBUG
  loglevel = "DEBUG"
}

The default one logs to STDOUT and is registered by default. It is not intended to be used for production. There is also an SLF4J event handler available in the 'akka-slf4j' module.

Example of creating a listener:

import akka.event.Logging.InitializeLogger
import akka.event.Logging.LoggerInitialized
import akka.event.Logging.Error
import akka.event.Logging.Warning
import akka.event.Logging.Info
import akka.event.Logging.Debug

class MyEventListener extends Actor {
  def receive = {
    case InitializeLogger(_)                        ⇒ sender ! LoggerInitialized
    case Error(cause, logSource, logClass, message) ⇒ // ...
    case Warning(logSource, logClass, message)      ⇒ // ...
    case Info(logSource, logClass, message)         ⇒ // ...
    case Debug(logSource, logClass, message)        ⇒ // ...
  }
}

SLF4J

Akka provides an event handler for SL4FJ. This module is available in the 'akka-slf4j.jar'. It has one single dependency; the slf4j-api jar. In runtime you also need a SLF4J backend, we recommend Logback:

lazy val logback = "ch.qos.logback" % "logback-classic" % "1.0.0" % "runtime"

You need to enable the Slf4jEventHandler in the 'event-handlers' element in the Configuration. Here you can also define the log level of the event bus. More fine grained log levels can be defined in the configuration of the SLF4J backend (e.g. logback.xml).

akka {
  event-handlers = ["akka.event.slf4j.Slf4jEventHandler"]
  loglevel = "DEBUG"
}

The SLF4J logger selected for each log event is chosen based on the Class[_] of the log source specified when creating the LoggingAdapter, unless that was given directly as a string in which case that string is used (i.e. LoggerFactory.getLogger(c: Class[_]) is used in the first case and LoggerFactory.getLogger(s: String) in the second).

val log = Logging(system.eventStream, "my.nice.string")

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%date{ISO8601} %-5level %logger{36} %X{sourceThread} - %msg%n</pattern>
  </encoder>
</appender>

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n</pattern>
  </encoder>
</appender>