rlogging: Simple logging in R
In mjkallen/rlogging: Simple logging in R

Description Usage Arguments Details Value Note Author(s) See Also

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.

    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)

`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()`.

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

1	[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).

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.

The behaviour of the stopifnot() command in R's base package is not changed, therefore no log messages will be printed or written to the log file.

Maarten-Jan Kallen sayhi@maartenjan.org

Felix Jung felix@jung.fm

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

mjkallen/rlogging documentation built on May 23, 2019, 1:04 a.m.