AppenderBuffer: Log to a memory buffer

Description

An Appender that Buffers LogEvents in-memory and and redirects them to other Appenders once certain conditions are met.

Arguments

Usage

x <- AppenderBuffer$new(threshold = NA_integer_, layout = LayoutFormat$new(fmt
  = "%L [%t] %m", timestamp_fmt = "%H:%M:%S", colors =
  getOption("lgr.colors")), appenders = NULL, buffer_size = 1000,
  flush_threshold = "fatal", flush_on_exit = TRUE, flush_on_rotate = TRUE,
  should_flush = default_should_flush, filters = NULL)
x$add_appender(appender, name = NULL)
x$add_filter(filter, name = NULL)
x$append(event)
x$filter(event)
x$flush()
x$format(...)
x$format(color = FALSE, ...)
x$remove_appender(pos)
x$remove_filter(pos)
x$set_appenders(x)
x$set_buffer_size(x)
x$set_filters(filters)
x$set_flush_on_exit(x)
x$set_flush_on_rotate(x)
x$set_flush_threshold(level)
x$set_layout(layout)
x$set_should_flush(x)
x$set_threshold(level)
x$show(threshold = NA_integer_, n = 20L)
x$appenders
x$buffer_df
x$buffer_dt
x$buffer_events
x$buffer_size
x$data
x$destination
x$dt
x$filters
x$flush_on_exit
x$flush_on_rotate
x$flush_threshold
x$layout
x$should_flush
x$threshold

Creating a Buffer Appender

The Layout for this Appender is used only to format console output of its $show() method.

Fields

appenders, set_appenders(): Like for a Logger. Buffered events will be passed on to these Appenders once a flush is triggered
flush_on_exit, set_flush_on_exit(x): TRUE or FALSE: Whether the buffer should be flushed when the Appender is garbage collected (f.e when you close R)
flush_on_rotate, set_flush_on_rotate: TRUE or FALSE: Whether the buffer should be flushed when the Buffer is full (f.e when you close R). Setting this to off can have slightly negative performance impacts.

buffer_size, set_buffer_size(x): integer scalar >= 0 Number of LogEvents to buffer.

buffer_events, buffer_df, buffer_dt

The contents of the buffer as a list of LogEvents, a data.frame or a data.table.

flush_threshold, set_flush_threshold()

integer or character log level. Minimum event level that will trigger flushing of the buffer. This behaviour is implemented through should_flush(), and you can modify that function for different behaviour.

should_flush(event), set_should_flush(x)

A function with exactly one arguments: event. If the function returns TRUE, flushing of the buffer is triggered. Defaults to flushing if an event of level error or higher is registered.

dt: Get the log recorded by this Appender as a data.table with a maximum of buffer_size rows

data: Get the log recorded by this Appender as a data.frame

threshold, set_threshold(level): character or integer scalar. The minimum log level that triggers this logger. See log_levels
layout, set_layout(layout): a Layout that will be used for formatting the LogEvents passed to this Appender
destination: The output destination of the Appender in human-readable form (mainly for print output)

filters, set_filters(filters): a list that may contain functions or any R object with a filter() method. These functions must have exactly one argument: event which will get passed the LogEvent when the Filterable's filter() method is invoked. If all of these functions evaluate to TRUE the LogEvent is passed on. Since LogEvents have reference semantics, filters can also be abused to modify them before they are passed on. Look at the source code of with_log_level() or with_log_value() for examples.

Methods

flush(): Manually trigger flushing

add_appender(appender, name = NULL), remove_appender(pos)

Add or remove an Appender. Supplying a name is optional but recommended. After adding an Appender with appender$add_appender(AppenderConsole$new(), name = "console") you can refer to it via appender$appenders$console. remove_appender() can remove an Appender by position or name.

flush(): Manually trigger flushing of the buffer

show(n, threshold): Show the last n log entries with a log level bellow threshold. The log entries will be formatted for console output via this Appenders Layout

append(event): Tell the Appender to process a LogEvent event. This method is usually not called by the user, but invoked by a Logger

filter(event): Determine whether the LogEvent x should be passed on to Appenders (TRUE) or not (FALSE). See also the active binding filters
add_filter(filter, name = NULL), remove_filter(pos): Add or remove a filter. When adding a filter an optional name can be specified. remove_filter() can remove by position or name (if one was specified)

Comparison AppenderBuffer and AppenderDt

Both AppenderBuffer and AppenderDt do in memory buffering of events. AppenderBuffer retains a copies of the events it processes and has the ability to pass the buffered events on to other Appenders. AppenderDt converts the events to rows in a data.table and is a bit harder to configure. Used inside loops (several hundred iterations), AppenderDt has much less overhead than AppenderBuffer. For single logging calls and small loops, AppenderBuffer is more performant. This is related to how memory pre-allocation is handled by the appenders.

In short: Use AppenderDt if you want an in-memory log for interactive use, and AppenderBuffer if you actually want to buffer events