Adds an arbitrary function as an output destination. Every logged event fans
out to each registered sink in registration order, so a custom sink runs
alongside the console and any file sinks. Use it to push events at a
database, a metrics collector, or an in-test collector of your own; for the
built-in file destinations see logtree_sink_file().
Arguments
- fn
A function of one argument, called with each emitted event. Its return value is ignored.
- threshold
Minimum leaf level this sink receives: one of
"debug","info","warn","error".NULL(the default) follows the globallogtree_threshold(), read afresh for each event. Step open/close lines are never gated, whatever the threshold.
Value
The sink's id, invisibly – pass it to logtree_sink_remove().
Details
fn is called with one argument, the event: a list whose kind is one of
"open", "close", "group", "group_close" or "leaf". Step-shaped
events (everything but "leaf") carry the step's record under entry, while
a leaf carries its own fields directly.
A sink that throws does not take the rest of the fanout down with it: the
error is caught, the remaining sinks still run, and a warning naming the sink
is raised once (per sink, until the next logtree_reset()). A logger should
witness failures, not become a source of them.
Examples
logtree_reset()
seen <- character(0)
h <- logtree_sink(function(event) seen <<- c(seen, event$kind))
f <- function() log_step("Step one")
invisible(f())
#> ▶ Step one
#> └─ ✔ Done 0.00s
seen
#> [1] "open" "close"
logtree_sink_remove(h)
# A sink that only ever hears about failures.
h <- logtree_sink(function(event) invisible(NULL), threshold = "error")
logtree_sink_remove(h)