---
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)
```