Report a digest of notable events

Prints a compact end-of-run digest of everything worth attention that happened since the last logtree_reset(): every warning and error leaf line, plus any step that closed with a warning, error, or interrupted status. Each entry shows the status glyph, the breadcrumb path to where it happened, and the message (for leaf lines) or an outcome word (for steps).

Usage

logtree_summary(
  filter = NULL,
  depth = NULL,
  gap = NULL,
  rule = NULL,
  trace = NULL
)

Arguments

filter

Optional character vector of statuses to include, e.g. "error" or c("warning", "interrupted"). Only entries whose status matches are printed and returned; recognised statuses are "error", "warning", "interrupted", and the pinned leaf statuses "info", "success", "debug". NULL (the default) reports every entry.

depth

Optional positive integer limiting how many trailing (deepest) breadcrumb nodes are printed. The message counts as the terminal node, so depth = 1 prints just the message (or, for a step entry, its innermost step), depth = 2 the message plus its immediate parent, and so on. NULL (the default) prints the full breadcrumb. Affects printing only; the returned entries always carry the full path.

gap

Number of blank lines printed between the last log line and the digest; 0 prints the digest flush against the tree. NULL (the default) takes the active theme's summary$gap (1 in every built-in preset).

rule

Divider drawn above the digest. TRUE draws a cli::rule() labelled with the digest header, so the counts become the rule's title instead of a separate line; FALSE draws no rule and keeps the plain header line; a character string draws the rule with that title and prints the header line below it. NULL (the default) takes the active theme's summary$rule (TRUE in every built-in preset).

trace

Pins the digest's call-site column for this call, overriding the theme's trace$show. Takes the same values: FALSE for no call sites, TRUE for all of them, "problems", or a vector of statuses such as "error" – see logtree_theme(). NULL (the default) follows the theme, so the digest agrees with the tree. Useful when the tree was quiet and the digest is where you want the locations, or the reverse. Note this can only narrow or reshape what was captured: capture is decided while the run happens, so with the theme's slot off for the run there is nothing for trace = TRUE here to print. To get the quiet-tree-annotated-digest combination, ask for capture during the run and print nothing: logtree_theme(list(trace = list(show = FALSE, capture = TRUE))), then logtree_summary(trace = TRUE).

Value

The recorded entries, invisibly: a list of records, each a list with kind, status, msg, path (character vector), elapsed, and trace (the call site: a list of fn, file and line, or NULL when the trace theme slot was off and nothing was captured).

Details

Unlike scrolling the live tree, the digest surfaces breakage even when no with_logging() handler was installed – interrupted steps are picked up from their close lines. Ordinary info / success lines are excluded unless logged with summary = TRUE; a warning or error can be excluded with summary = FALSE.

The digest's appearance comes from the active theme, so it is customised through logtree_theme() like everything else: the crumb slot sets the breadcrumb separator and the emphasis on the path nodes, the summary slot the divider (gap, rule, line). gap, rule and trace below override the theme for a single call.

See also

with_logging(), logtree_reset()

Examples

logtree_reset()
f <- function() {
  log_step("Load data")
  log_warn("coerced 3 rows")
}
f()
#> ▶ Load data
#> ├─ ⚠ coerced 3 rows
#> └─ ⚠ Done  0.01s
logtree_summary()
#> 
#> ── Summary: 1 warning ──────────────────────────────────────────────────────────
#> ⚠ Load data › coerced 3 rows

# Flush against the tree, with a titled divider.
logtree_summary(gap = 0, rule = "Run report")
#> ── Run report ──────────────────────────────────────────────────────────────────
#> Summary: 1 warning
#> ⚠ Load data › coerced 3 rows

# Call sites in the digest only: the tree above stays as it was rendered.
logtree_theme(list(trace = list(show = TRUE)))
f()
#> ▶ Load data  f()
#> ├─ ⚠ coerced 3 rows  f()
#> └─ ⚠ Done  0.00s
logtree_summary(trace = "error")
#> 
#> ── Summary: 2 warnings ─────────────────────────────────────────────────────────
#> ⚠ Load data › coerced 3 rows
#> ⚠ Load data › coerced 3 rows
logtree_theme("unicode")

# Set the layout and the breadcrumb symbol once, on the theme.
logtree_theme(list(
  summary = list(gap = 2, rule = FALSE),
  crumb   = list(glyph = " / ")
))
logtree_summary()
#> 
#> 
#> Summary: 2 warnings
#> ⚠ Load data / coerced 3 rows
#> ⚠ Load data / coerced 3 rows
logtree_theme("unicode")