api

Type Members

class BaseLogger extends AnyRef

Embodies the main interface into timber.
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.
trait Dispatcher extends AnyRef

Dispatches entries to their appropriate destination(s).
case class Entry(level: Option[Level] = None, message: Option[Message] = None, sourceLocation: Option[SourceLocation] = None, loggingClass: Option[String] = None, loggingMethod: Option[String] = None, tags: Set[Tag] = Set.empty, timestamp: Long = System.currentTimeMillis, threadName: String = Thread.currentThread.getName, loggerAttributes: Map[String, Any] = Map.empty, threadAttributes: Map[String, List[String]] = Map.empty) extends Product with Serializable

Represents a log-worthy event in the timber logging system.
Represents a log-worthy event in the timber logging system.
Depending on the origin of the entry, different fields may be present or absent. For example, information about the entry's origin (sourceLocation, loggingClass, loggingMethod) will normally be present when the entry is created using the timber API but may be absent for entries bridged from other logging systems' APIs.
level
the optional level at which this entry was logged
message
the optional text content of this entry, which may contain multiple lines
sourceLocation
the optional source code location from which this entry was logged
loggingClass
the optional name of the class from which this entry was logged
loggingMethod
the optional name of the method from which this entry was logged
tags
the set of tags that have been associated with this entry
timestamp
the timestamp at which this entry was created, milliseconds since Java epoch UTC
threadName
the name of the thread which created this entry
loggerAttributes
the attributes associated with the logger that created this entry
threadAttributes
the attributes associated with the thread that created this entry
case class Level(intValue: Int, name: Option[String] = None) extends Ordered[Level] with Product with Serializable

Represents a log level of an Entry (sometimes known in other systems as "severity").
Represents a log level of an Entry (sometimes known in other systems as "severity"). Levels are always treated as their integer values internally. The only components that care about the names are the eventual entry destinations, which could be log files or sockets, etc.
The names provided by the API are simply hints which the destination may choose use to format the entry. The destinations may also choose to ignore the names and only use the numeric value or even translate the integers to its own labels.
intValue
the numeric value of the level, used for comparison with other levels internally
name
a suggested name to use when ultimately writing entries logged at this level
class Logger extends BaseLogger with Trace with Debug with Info with Warn with Error

Provides a BaseLogger that can be used out-of-the-box with a default set of level-specific log methods.
class Message extends AnyRef

Represents the textual content of an entry.
Represents the textual content of an entry. You normally won't create a message object explicitly but will use one of the implicit conversions in the companion object (see the magnet pattern). You don't normally need to create instances of this class directly but can use the implicits defined in the Logging object.
trait Tag extends AnyRef

Marks classes that can be used as tags in timber.
Marks classes that can be used as tags in timber. While you could technically use anything as a tag, this makes it so that the Logger API is a little nicer, since the type is particular to timber.

Value Members

object BaseLogger
object Dispatcher
object Entry extends Serializable
object ImmediateMessage extends Tag

Tells the BaseLogger to evaluate the message immediately.
Tells the BaseLogger to evaluate the message immediately. This may be useful if you're referring to vars whose values could change between the time that the message is created and the time that it is ultimately evaluated. This could be once it asynchronously reaches its final destination.
If you want your BaseLogger to always evaluate its messages immediately, you can add this tag to the logger when it is constructed.
object Level extends Serializable

Defines some common log levels that encompass most of the log levels used by legacy logging systems.
Defines some common log levels that encompass most of the log levels used by legacy logging systems. This object also provides implicit conversions for levels to and from integers.
object Message

Contains some useful implicit conversions to Message.
Contains some useful implicit conversions to Message. These are all that make using the timber API bearable. They should be in scope by virtue of being members of the companion object of the target class.
object ThreadAttributes

Provides a convenient mechanism for associating thread-specific attributes with your log entries.
Provides a convenient mechanism for associating thread-specific attributes with your log entries. Loggers will copy the thread-specific attributes available through this object (ThreadAttributes.get()) into the threadAttributes field of every entry they create.
Thread attribute values are stacked, making it possible to push an attribute value for a specific code block and then pop the value from the attribute stack, leaving the thread attributes in the state that was present before the block was executed. This is directly implemented in the during() method calls. It can also be managed explicitly by the calling code (e.g., when the push and pop operations need to span method bodies) using the push and pop methods.
package impl
package level

Contains composable traits that can be used to add many common level-specific log methods to your custom loggers.
Contains composable traits that can be used to add many common level-specific log methods to your custom loggers. They are inspired by various legacy logging technologies.
Each trait defines several methods for logging and level val that can be overridden to control the level at which those methods log entries. See Logger for an example.
Another example that mixes in a ridiculous set of level methods:
```
import org.scalawag.timber.api
import org.scalawag.timber.api.Dispatcher
import org.scalawag.timber.api.level._

class Logger(override val attributes:Map[String,Any] = Map.empty, override val tags:Set[Tag] = Set.empty)(implicit dispatcher: Dispatcher)
  extends BaseLogger(attributes, tags)(dispatcher) with Emergency with Finest with Warning with Warn
```
package style

package api

Type Members

class BaseLogger extends AnyRef

trait Dispatcher extends AnyRef

case class Level(intValue: Int, name: Option[String] = None) extends Ordered[Level] with Product with Serializable

class Logger extends BaseLogger with Trace with Debug with Info with Warn with Error

class Message extends AnyRef

trait Tag extends AnyRef

Value Members

object BaseLogger

object Dispatcher

object Entry extends Serializable

object ImmediateMessage extends Tag

object Level extends Serializable

object Message

object ThreadAttributes

package impl

package level

package style

Ungrouped