loggr - Logging for R

The aim of loggr is to provide a simple mechanism for logging events in R, without the need to wrap expressions in e.g. withCallingHandlers or similar and while keeping the possibility of having several active log outputs (files and/or console) possibly listening for different events.

Features:

• Multiple log outputs (files, console)
• Capture classic events signalled with message, warning and stop.
• Additional event levels, DEBUG, INFO, WARN, ERROR, CRITICAL.

Installation:

devtools::install_github("smbache/loggr")

Usage:

In your R script/program, activate logging by specifying a log file:

log_file("path/to/logfile.log")

Then, whenever a log event (by default, simpleMessages, simpleWarnings, and simpleErrors are considered log events) is signalled, it will be logged to the specified file.

To listen for log events to show in the console, use of

log_file("console") # or
log_file("stdout")

To signal a log event, use one of the following

log_debug(message)     # DEBUG
log_info(message)      # INFO
log_warn(message)      # WARN
log_error(message)     # ERROR  (will not break code execution)
log_critical(message)  # CRITICAL   (breaks code execution)

Specifying which events to log

It is possible to log only certain events when they are raised when specifying the log file:

log_file("/path/to/file.log", WARN, .message = FALSE, .error = FALSE)

This will only listen for WARN events, and has disabled the classic conditions simpleError and simpleMessage, which are logged by default.

NB: the current enabling/disbling of classic events may be changed to align them with the other log events.

Formatting the log entries.

By default, the entries are formatted as e.g.

2015-04-12 15:10:44.601 - WARN - Something bad happened. 

You can change the formatter by specifying it for the log file:

log_file("/path/to/file.log", .formatter = my_formatter)

Where my_formatter should accept a log_event object as argument, and return a character representation.

How it works

loggr adds a hook to warning, stop and signalCondition, so whenever these functions are executed, loggr will be notified (Note that message uses signalCondition internally and does not need its own hook). The event is sent to any log outputs that subscribe to the type of event.

This means that there is very little code needed in the functions where signalling of log events are desired, and the "consumer" only needs to specify a log_file.

Bug reports / suggestions

The package is still young and under development, so if you experience any issues or have suggestions, please file an issue.