--- title: "Logging calls" output: litedown::html_format vignette: > %\VignetteIndexEntry{Logging calls} %\VignetteEngine{litedown::vignette} %\VignetteEncoding{UTF-8} --- ```{r setup} library(fnware) library(S7) ``` `log_call()` logs when a call starts, and when it finishes or fails. Each message holds the function's name, its arguments and, once the call is over, the time it took. ```{r basic} add := log_call() %@% function(a, b) a + b add(1, b = 2) ``` Arguments are named by the formals they matched, so `add(b = 2, a = 1)` logs the same as above. Long values are cut. A failure is logged and then signalled again unchanged: ```{r failure, error = TRUE} boom := log_call() %@% function(x) stop("boom") boom(1) ``` ## Levels Each event has a level. By default the start and the finish are `info` and a failure is `error`. Change them with `log_levels()`: ```{r levels} quiet := log_call( logger = logger_message(), level = log_levels(start = "debug", finish = "debug", error = "warn") ) %@% function(x) stop("boom") try(quiet(1), silent = TRUE) ``` The start and finish are `debug` here, below the loggers' default `threshold` of `"info"`, so only the failure is written. Set `elapsed = FALSE` to leave the time out of the finish message. ## Traces When a call fails, the calls from the decorated function down to the failure are logged as a separate `trace` event straight after the error. The built-in loggers only write events at or above their `threshold`, which is `"info"` by default, so the trace stays hidden until you lower it: ```{r trace} inner <- function(x) stop("boom") outer := log_call(logger = logger_message(threshold = "trace")) %@% function(x) inner(x) try(outer(1), silent = TRUE) ``` ## Loggers A logger decides where a message goes. `logger_base()`, the default, prints `LEVEL [timestamp]: message`. `logger_message()` writes the same line with `message()` instead, so `suppressMessages()` silences it. Both take a `threshold`, one of `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"` or `"fatal"`, and leave out anything below it. ```{r message} hello := log_call(logger = logger_message()) %@% function() "hi" hello() ``` ## Using a logging package To log with another package, inherit from `logger_base` and add a method for `logger_fn()`. The package then owns thresholds, layouts and appenders. The method receives the level label (`"INFO"`, `"DEBUG"` and so on) and the message, and decides for itself whether to show it, so `threshold` is not used. For the logger package: ```{r logger, eval = FALSE} library(logger) logger_logger := new_class(parent = logger_base) method(logger_fn, logger_logger) <- function(class, level, msg, ...) { log_level(level, skip_formatter(msg)) } f := log_call(logger = logger_logger()) %@% function(x) x f(1) ``` `skip_formatter()` stops the logger package treating braces in the message as a glue template. Some packages need a logger object passed in. Give it to the logger through the `logger` property and read it back as `class@logger`. For log4r: ```{r log4r, eval = FALSE} library(log4r) logger_log4r := new_class(parent = logger_base) method(logger_fn, logger_log4r) <- function(class, level, msg, ...) { log_at(class@logger, level, msg) } f := log_call(logger = logger_log4r(logger = logger("INFO"))) %@% function(x) x f(1) ``` If a package names its levels differently, override the defaults of the `trace`, `debug`, `info`, `warn`, `error` and `fatal` properties. A label can be any object, for example a number. ```{r labels} logger_num := new_class( parent = logger_base, properties = list( info = new_property(class_any, default = 20L), debug = new_property(class_any, default = 10L) ) ) method(logger_fn, logger_num) <- function(class, level, msg, ...) { cat(level, msg, "\n") } f := log_call(logger = logger_num()) %@% function() 1 f() ``` ## Promises `log_call()` logs the finish as soon as the function returns, which for a function that returns a promise is before the work is done. Use `async_log_call()` instead. It logs the start when the function is called, and the finish or the failure when the promise settles. A rejection is logged then passed on unchanged. It logs no `trace` event, because the calls that led to a rejection are gone by the time it settles. ```{r async, eval = FALSE} f := async_log_call(logger = logger_message()) %@% function(x) promises::promise_resolve(x) promises::then(f(1), print) ```