2 Usage
2.1 Structure of the Logging System
If you want custom logging configurations, you have to understand the structure of the logging process.
- A Logger collects information and dispatches it to its Appenders, and also the Appenders of its Parent Loggers (also see the section on hierarchical logging)
- An Appender writes the log message to destination (the console, a file, a database, etc…).
- A Layout is used by an Appender to format LogRecords. For example,
AppenderFileusesLayoutFormatby default to write human readable log events to a text file, but can also useLayoutJsonproduce machine readable JSON lines logfiles. - LogEvents are produced by the Logger and dispatched to Appenders. They contain all the information that is beeing logged (think of it as a row in table). LogEvents usually contain the log level, a timestamp, a message, the name of the calling function, and a reference to the Logger that created it. In addition, a LogEvent can contain any number of custom fields, but not all Appenders/Layouts support custom fields. For example if you use
AppenderFormatwithLayoutFormatyou can only use the standard fields in your log message, whileLayoutJsonsupports custom fields in a quite natural manner. See examples 1 & 2
2.2 Log Levels
Yog supports the standard log4j Log Levels outlined bellow. The Log Level of an event represents its severity. Log levels have numeric and character representations. Creation of custom log levels ist not yet supported by yog (but planned for the future).
| Level | Name | Description |
|---|---|---|
| 0 | off | A log level of 0/off tells a Logger or Appender to suspend all logging |
| 100 | fatal | Critical error that leads to program abort. Should always indicate a stop() or similar |
| 200 | error | A severe error that does not trigger program abort |
| 300 | warn | A potentially harmful situation, like warning() |
| 400 | info | An informatinal message on the progress of the application |
| 500 | debug | Finer grained informational messages that are mostly useful for debugging |
| 600 | trace | An even finer grained message than debug |
| NA | all | A log level of NA/all tells a Logger or Appender to process all log events |
2.3 Simple Logging With the Root Logger
Yog comes with a pre-configured Root Logger. If you do not care about using multiple loggers, and do not want to deal with R6 classes you still use yog as a performant and easy to use logging solution.
FATAL("This is an important message about %s going wrong", "something")
#> FATAL [14:10:21.693] This is an important message about something going wrong
ERROR("A less severe error")
#> ERROR [14:10:21.695] A less severe error
WARN("something likely went wrong")
#> WARN [14:10:21.697] something likely went wrong
INFO("Everything is ok")
#> INFO [14:10:21.699] Everything is ok
DEBUG("Debug messages are hidden by default")
console_threshold("debug") # you must use lower case names here
DEBUG("unless we lower the threshold")
#> DEBUG [14:10:21.702] unless we lower the threshold
TRACE("Trace is even lower than debug")You can also directly use Logger R6 objects to log. This package comes with a default root logger named like the package ("yog"). This method of referring to the logger is more explicit (and therefore arguably better). The examples in this vignette will moslty use the notation below.
yog$fatal("This is an important message about %s going wrong", "->something<-")
#> FATAL [14:10:21.710] This is an important message about ->something<- going wrong
yog$trace("Trace messages are still hidden")
yog$appenders$console$set_threshold("trace")
yog$trace("Unless we lower the threshold")
#> TRACE [14:10:21.714] Unless we lower the threshold2.4 Thresholds: Controlling Output Detail
(wip)
2.5 Appenders: Managing Log Destinations
The root logger only logs to the console by default. If you want to redirect the output to a file you can just add a file appender to yog.
tf <- tempfile()
# Add a new appender to a logger. We don't have to supply a name, but that
# makes it easier to remove later.
yog$add_appender(AppenderFile$new(file = tf), name = "file")
# configure yog so that it logs everything to the file, but only info and above
# to the console
yog$set_threshold(NA)
yog$appenders$console$set_threshold("info")
yog$appenders$file$set_threshold(NA)
yog$info("Another informational message")
#> INFO [14:10:21.751] Another informational message
yog$debug("A debug message not shown by the console appender")
readLines(tf)
#> [1] "INFO [2018-12-21 14:10:21.751] Another informational message"
#> [2] "DEBUG [2018-12-21 14:10:21.753] A debug message not shown by the console appender"
# Remove the appender again
yog$remove_appender("file")2.6 Inheritance: Hierarchical Loggers
Each newly created Logger is child to a parent Logger. If no parent Logger is specified manually during a Logger’s creation, its parent is the Root Logger. A logger dispatches the LogRecords it creates not only to its own Appenders, but also to the Appenders of all its ancestral Appenders (ignoring the threshold and Filters of the ancestral Loggers, but not of the ancestral Appenders).
