BaseLogger

Embodies the main interface into timber. Instances of this class are very simple objects that are essentially entry factories. They are used to create entries and pass them to a dispatcher for handling, after gathering some additional contextual information. Every BaseLogger has its associated dispatcher established at construction-time. This dispatcher dispatches all of the entries that this logger creates throughout its lifetime, since the dispatcher can not be changed after construction.

Instances of this class are lightweight, immutable and thread-safe. You should not go to great lengths to avoid creating loggers.

In addition to gathering contextual information, BaseLoggers can be given attributes and tags that will be applied to all the entries they create. Given that they are lightweight, this gives you a way to associated some shared statically-scoped attributes with certain entries across threads, where the thread executing the code is not as important as the static attributes. This can be particularly useful when using scala Futures or a similar technology where threads become more fungible. Here is an example where the thread context (which is normally how you would associate the same data with several log calls) becomes meaningless.

import scala.util._
import scala.concurrent.Future
import org.scalawag.timber.api._
import scala.concurrent.ExecutionContext.Implicits.global

def handleRequest(clientIp:String) {
  val logger = new Logger(Map("clientIp" -> clientIp))
  logger.debug("about to start handling request")
  Future {
    logger.debug("handling request")
  } onComplete {
    case Success(_) =>
      logger.debug("request handled")
    case Failure(ex) =>
      logger.debug(s"failed to handle request: $$ex")
  }
}

You could also pass the static context (clientIp) to each log call individually, but the style shown here is a little cleaner and less error-prone.

BaseLoggers don't support the isEnabled type methods provided by some other logging systems. That's because the logger doesn't make any decisions regarding if (or where) the entries it creates are actually processed in any way. You don't need to protect against message generation overhead because messages are lazily built (unless you specify the ImmediateMessage tag). Anything else that you would do in application code that depends on the status of the logging system is probably a bad idea.

Linear Supertypes

AnyRef, Any

Known Subclasses

Logger, Logger, Logger, Logger, Logger

Instance Constructors

new BaseLogger(attributes: (String, Any)*)(implicit dispatcher: Dispatcher)
new BaseLogger(attributes: Map[String, Any] = Map.empty, tags: Set[Tag] = Set.empty)(implicit dispatcher: Dispatcher)

attributes
the logger attributes that this logger associates with the entries it creates
tags
the tags that this logger associates with the entries it creates
dispatcher
the dispatcher that is used to dispatch the entries that this logger creates

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def asInstanceOf[T0]: T0

Definition Classes
Any
val attributes: Map[String, Any]

the logger attributes that this logger associates with the entries it creates
def buildEntry(level: Option[Level], message: Option[Message], location: Option[LogCallLocation], entryTags: TraversableOnce[Tag]): Entry

Attributes
protected
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
def log(implicit location: LogCallLocation): Unit

Submits an entry without a level, a Message or tags to the logging system.
Submits an entry without a level, a Message or tags to the logging system. This essentially creates an entry with nothing but automatically-collected call metadata.
location
the source location of the method call (usually automatically fulfilled by LogCallLocation.capture())
def log(message: Message)(implicit location: LogCallLocation): Unit

Submits an entry with a Message but no level or tags to the logging system.
Submits an entry with a Message but no level or tags to the logging system.
message
the message to include with the entry
location
the source location of the method call (usually automatically fulfilled by LogCallLocation.capture())
def log(level: Level)(message: Message)(implicit location: LogCallLocation): Unit

Submits an entry with a Message and level but no tags to the logging system.
Submits an entry with a Message and level but no tags to the logging system.
The message argument appears in an argument list by itself because this allows us to use a thunk or a tuple as the source of the implicit Message conversion. When it appears with other arguments, the appearance of the calling syntax goes downhill fast (e.g., having to wrap the thunk in parentheses or having to include extra parentheses around tuples). Similarly, tags is not a varargs parameter because the compiler prefers to perceive multiple arguments as possible Tags (and failing) rather than look for an implicit conversion from the tuple.
level
the level to use for the entry created
message
the message to include with the entry
location
the source location of the method call (usually automatically fulfilled by LogCallLocation.capture())
def log(tags: TraversableOnce[Tag])(message: Message)(implicit location: LogCallLocation): Unit

Submits an entry with a Message and tags but no level to the logging system.
Submits an entry with a Message and tags but no level to the logging system.
The message argument appears in an argument list by itself because this allows us to use a thunk or a tuple as the source of the implicit Message conversion. When it appears with other arguments, the appearance of the calling syntax goes downhill fast (e.g., having to wrap the thunk in parentheses or having to include extra parentheses around tuples). Similarly, tags is not a varargs parameter because the compiler prefers to perceive multiple arguments as possible Tags (and failing) rather than look for an implicit conversion from the tuple.
tags
additional tags to include with the entry
message
the message to include with the entry
location
the source location of the method call (usually automatically fulfilled by LogCallLocation.capture())
def log(level: Level, tags: TraversableOnce[Tag] = Iterable.empty)(message: Message)(implicit location: LogCallLocation): Unit

Submits an entry with a level, a message and maybe tags to the logging system.
Submits an entry with a level, a message and maybe tags to the logging system.
The message argument appears in an argument list by itself because this allows us to use a thunk or a tuple as the source of the implicit Message conversion. When it appears with other arguments, the appearance of the calling syntax goes downhill fast (e.g., having to wrap the thunk in parentheses or having to include extra parentheses around tuples). Similarly, tags is not a varargs parameter because the compiler prefers to perceive multiple arguments as possible Tags (and failing) rather than look for an implicit conversion from the tuple.
level
the level to use for the entry created
tags
additional tags to include with the entry
message
the message to include with the entry
location
the source location of the method call (usually automatically fulfilled by LogCallLocation.capture())
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
val tags: Set[Tag]

the tags that this logger associates with the entries it creates
def toString(): String

Definition Classes
AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )

Related Docs: object BaseLogger | package api

class BaseLogger extends AnyRef

Instance Constructors

new BaseLogger(attributes: (String, Any)*)(implicit dispatcher: Dispatcher)

new BaseLogger(attributes: Map[String, Any] = Map.empty, tags: Set[Tag] = Set.empty)(implicit dispatcher: Dispatcher)

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: Any): Boolean

final def asInstanceOf[T0]: T0

val attributes: Map[String, Any]

def buildEntry(level: Option[Level], message: Option[Message], location: Option[LogCallLocation], entryTags: TraversableOnce[Tag]): Entry

def clone(): AnyRef

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

final def getClass(): Class[_]

def hashCode(): Int

final def isInstanceOf[T0]: Boolean

def log(implicit location: LogCallLocation): Unit

def log(message: Message)(implicit location: LogCallLocation): Unit

def log(level: Level)(message: Message)(implicit location: LogCallLocation): Unit

def log(tags: TraversableOnce[Tag])(message: Message)(implicit location: LogCallLocation): Unit

def log(level: Level, tags: TraversableOnce[Tag] = Iterable.empty)(message: Message)(implicit location: LogCallLocation): Unit

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

final def synchronized[T0](arg0: ⇒ T0): T0

val tags: Set[Tag]

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from AnyRef

Inherited from Any

Ungrouped