Add a file sink

Registers an additional output destination. Every logged event fans out to the console sink and every registered file sink, so console, text-file, and NDJSON outputs can all run simultaneously (design doc section 6).

Usage

logtree_sink_file(
  path,
  format = c("text", "json"),
  trace = NULL,
  timestamp = NULL,
  threshold = NULL
)

Arguments

path

File path to append rendered log lines to.

format

"text" for a plain ASCII tree (no ANSI, independent of the active console theme) or "json" for one NDJSON object per event.

trace

Whether this sink prints the call-site column (see the trace slot in logtree_theme()). NULL (the default) follows the active console theme, read afresh for each event, so switching trace on reaches the file too; FALSE, TRUE or "problems" pins this sink independently of the console. Text sinks only: a "json" sink always carries the fn, file and line fields, null when there is no call site to report.

timestamp

Whether this sink prints the wall-clock column (see the timestamp slot in logtree_theme()). NULL (the default) follows the active console theme, read afresh for each event; FALSE pins it off; TRUE turns it on with a date-and-time format suited to a file that outlives the session ("%Y-%m-%d %H:%M:%S"); a strftime format string pins that format. Text sinks only: a "json" sink always carries ts.

threshold

Minimum leaf level this file records: one of "debug", "info", "warn", "error". NULL (the default) follows the global logtree_threshold(). This is per sink, so a "debug" file can record everything while the console stays at "info" – or an "error" file can keep only what went wrong. Step open/close lines are never gated.

Value

The sink's id, invisibly – pass it to logtree_sink_remove() to stop writing to this file.

Details

A "json" sink writes one NDJSON object per event, with these fields:

Field	What it holds
ts	when the event was emitted, ISO-8601 to the millisecond with UTC offset
run_id	identifies the run, so one run's lines can be picked out of a shared file
level	event kind: "open", "close", "group", "group_close", "leaf"
id, parent_id, depth	the node's identity and place in the tree
label	a step's label, a group's name, or a leaf's message
elapsed	seconds, on close lines only; null elsewhere
status	a leaf's status, "step"/"group" on an opening line, or the resolved status on a close
fn, file, line	the call site, when the trace theme slot recorded one; null otherwise

See also

logtree_sink() for a sink of your own, logtree_sinks() and logtree_sink_remove() for the registry.

Examples

logtree_reset()
logtree_sink_file(tempfile(), format = "text")
with_logging({
  log_step("Step one")
})
#> ▶ Step one
#> ✔ Run complete in 0.00s
#> └─ ◌ Done  0.00s

# A file that records call sites even with the console column off.
logtree_sink_file(tempfile(), format = "text", trace = TRUE)

# A debug-level record on disk while the console stays at "info".
logtree_sink_file(tempfile(), format = "json", threshold = "debug")

# A file that stamps every line with the date and time.
logtree_sink_file(tempfile(), format = "text", timestamp = TRUE)