rlogging (version 1.1)

rlogging: Simple logging in R

Description

Provides a wrapper around R's base functions message, warning, and stop to provide a simple, but effective, logging facility: output log messages with timestamps, direct output to the console and/or to a text file of your choosing, and control the level of logging.

Usage

SetLogFile(base.file="rlogging.log", folder=getwd(), split.files=FALSE) GetLogFile(level)
SetLogLevel(level="INFO") GetLogLevel()
SetTimeStampFormat(ts.format="[%Y-%m-%d %H:%M:%S]") GetTimeStampFormat()
SetFilenameSuffixes(file.name.suffixes=list(INFO="message", WARN="warning", STOP="stop")) GetFilenameSuffixes()
message(..., domain=NULL, appendLF=TRUE) warning(..., call.=TRUE, immediate.=FALSE, domain=NULL) stop(..., call.=TRUE, domain=NULL)

Arguments

base.file
Base name of the log file(s) as a string (default is ‘rlogging.log’). Set to NULL if no file output is desired.
folder
Root folder where the log file should be written to (default is the current working directory).
split.files
Boolean indicating whether messages, warnings, and errors should be split into several files. If set to FALSE, all logging output will be written into the file provided by the base.file parameter. The prefixes ‘INFO’, ‘WARN’, and ‘STOP’ will be used to differentiate the different logging levels in the log. If set to TRUE, each level will be logged into its own log file using respective suffixes for the log filenames. The suffixes are settable through the SetFilenameSuffixes function.
level
Logging level (default is ‘INFO’, others are ‘WARN’ and ‘STOP’).
ts.format
A string providing the format used for timestamps in log files. See base::strptime for a documentation of formatting options.
file.name.suffixes
Named list of filename suffixes to be used when split.files is set to TRUE. The list must contain the three elements ‘INFO’, ‘WARN’, and ‘STOP’.
...
R objects to be converted into a log message. Passed on to base::message(), base::warning(), and base::stop().
domain
Passed on to base::message(), base::warning(), and base::stop().
appendLF
Passed on to base::message().
call.
Passed on to base::warning() and base::stop().
immediate.
Passed on to base::warning().

Value

GetLogFile returns a string with the full path to the log file, possibly specified through the level parameter.GetLogLevel returns a string with the current log level.GetTimeStampFormat returns a string containing the timestamp format.GetFilenameSuffixesReturns the named list of filename suffixes.

Details

This package provides simple logging functionality on top of R's message(), warning(), and stop() functions. These functions are matched to the three logging levels ‘INFO’, ‘WARN’, and ‘STOP’ respectively. When loading the package, the level is set to ‘INFO’ and messages will be printed to the console as well as a text file ‘rlogging.log’ in the working directory. The name and location of the log file can be changed with SetLogFile. If you do not want to write to a file, do SetLogFile(NULL). If the file already exists, then new messages will be appended to the existing messages. If you wish to split messages, warnings, and errors accross multiple files, you can do so by setting the split.files parameter to the SetLogFile function to TRUE.

Log messages start with a timestamp (i.e. the result of format(Sys.time())) surrounded by square brackets, followed by the logging level, also surrounded in square brackets, and finally the message itself. For example, message("Hello world!") will print

[2013-09-12 17:14:46] [INFO] Hello world!
to the console and append the same message to the log file if this one is not set to NULL. If split.files is set to TRUE, the logging level is not printed to file, but is still printed to console. The format of the timestamp can be changed through the function SetTimeStampFormat.

If the log level is set to ‘INFO’, then all three functions will print a message. If set to ‘WARN’ then only warning() and stop() will print log messages. Finally, if set to ‘STOP’, then a log message is only printed in case of an error. Note that in case of warning() and stop() the message is always forwarded to the base function to retain their usual behaviour (i.e. saving warning messages until later and stopping the execution of a program after an error has occurred).

See Also

See the functions message, warning, and stop in R's base package for their usage.