| Title: | A Logging Utility for R |
|---|---|
| Description: | Provides a simple yet powerful logging utility. Based loosely on log4j, futile.logger takes advantage of R idioms to make logging a convenient and easy to use replacement for cat and print statements. |
| Authors: | Brian Lee Yung Rowe |
| Maintainer: | Brian Lee Yung Rowe <[email protected]> |
| License: | LGPL-3 |
| Version: | 1.4.3 |
| Built: | 2024-10-26 06:19:11 UTC |
| Source: | CRAN |
This package implements a logging system inspired by log4j. The basic idea of layouts, appenders, and loggers is faithful to log4j, while the implementation and idiom is all R. This means that support for hierarchical loggers, custom appenders, custom layouts is coupled with a simple and intuitive functional syntax.
| Package: | futile.logger |
| Type: | Package |
| Version: | 1.4.3 |
| Date: | 2016-07-10 |
| License: | LGPL-3 |
| LazyLoad: | yes |
The latest version of futile.logger introduces zero-configuration semantics out of the box. This means that you can use the default configuration as is. It is also easy to interactively change the configuration of the ROOT logger, as well as create new loggers. Since loggers form a hierarchy based on their name, the ROOT logger is the starting point of the hierarchy and always exists. By default the ROOT logger is defined with a simple layout, printing to the console, with an INFO threshold. This means that writing to any logger with a threshold of INFO or higher will write to the console.
All of the logging functions take a format string so it is easy to add arbitrary values to log messages.
> flog.info("This song is just %s words %s", 7, "long")
Thresholds range from most verbose to least verbose: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. You can easily change the threshold of the ROOT logger by calling > flog.threshold(TRACE) which changes will print all log messages from every package. To suppress most logging by default but turn on all debugging for a logger 'my.logger', you would execute
> flog.threshold(ERROR)
> flog.threshold(TRACE, name='my.logger')
Any arbitrary logger can be defined simply by specifying it in any futile.logger write operation (futile.threshold, futile.appender, futile.layout). If the logger hasn't been defined, then it will be defined dynamically. Any unspecified options will be copied from the parent logger.
When writing log messages, futile.logger will search the hierarchy based on the logger name. In our example, if 'my.logger' hasn't been defined then futile.logger will look for a logger named 'my' and finally the ROOT logger.
Functions calling futile.logger from a package are automatically assigned a logger that has the name of the package. Suppose we have log messages in a package called 'my.package'. Then any function that calls futile.logger from within the package will automatically be assigned a default logger of 'my.package' instead of ROOT. This means that it is easy to change the log setting of any package that uses futile.logger for logging by just updating the logger for the given package. For instance suppose you want to output log message for my.package to a file instead.
> flog.appender(appender.file('my.package.log'), name='my.package')
Now all log statements in the package my.package will be written to a file instead of the console. All other log messages will continue to be written to the console.
Appenders do the actual work of writing log messages to a writeable target, whether that is a console, a file, a URL, database, etc. When creating an appender, the implementation-specific options are passed to the appender at instantiation. The package defines two appender generator functions:
Write to a file
Write to the console
Each of these functions returns the actual appender function, so be sure to actually call the function!
Layouts are responsible for formatting messages. This operation usually consists of adding the log level, a timestamp, plus some pretty-printing to make the log messages easy on the eyes. The package supplies several layouts:
Writes messages with a default format
Generates messages in a JSON format
Define your own format
Print a variable name along with its value
Brian Lee Yung Rowe <[email protected]>
flog.logger, flog.threshold,
flog.layout, flog.appender
flog.debug("This %s print", "won't") flog.warn("This %s print", "will") flog.info("This inherits from the ROOT logger", name='logger.a') flog.threshold(DEBUG, name='logger.a') flog.debug("logger.a has now been set to DEBUG", name='logger.a') flog.debug("But the ROOT logger is still at INFO (so this won't print)") ## Not run: flog.appender(appender.file("other.log"), name='logger.b') flog.info("This writes to a %s", "file", name='logger.b') ## End(Not run)flog.debug("This %s print", "won't") flog.warn("This %s print", "will") flog.info("This inherits from the ROOT logger", name='logger.a') flog.threshold(DEBUG, name='logger.a') flog.debug("logger.a has now been set to DEBUG", name='logger.a') flog.debug("But the ROOT logger is still at INFO (so this won't print)") ## Not run: flog.appender(appender.file("other.log"), name='logger.b') flog.info("This writes to a %s", "file", name='logger.b') ## End(Not run)
Provides functions for adding and removing appenders.
... |
Used internally by lambda.r |
# Get the appender for the given logger
flog.appender(name) %::% character : Function
flog.appender(name='ROOT')
# Set the appender for the given logger
flog.appender(fn, name='ROOT')
# Print log messages to the console
appender.console()
# Write log messages to a file
appender.file(file)
# Write log messages to console and a file
appender.tee(file)
Appenders do the actual work of writing log messages to some target.
To use an appender in a logger, you must register it to a given logger.
Use flog.appender to both access and set appenders.
The ROOT logger by default uses appender.console.
appender.console is a function that writes to the console.
No additional arguments are necessary when registering the appender
via flog.appender.
appender.file writes to a file, so you must pass an additional file
argument to the function. To change the file name, just call
flog.appender(appender.file(file)) again with a new file name.
To use your own appender create a function that takes a single argument,
which represents the log message. You need to pass a function reference to
flog.appender.
appender.tee writes to both the console and file.
When getting the appender, flog.appender returns the appender
function. When setting an appender, flog.appender has no
return value.
Brian Lee Yung Rowe
## Not run: flog.appender(appender.console(), name='my.logger') # Set an appender to the logger named 'my.package'. Any log operations from # this package will now use this appender. flog.appender(appender.file('my.package.out'), 'my.package') ## End(Not run)## Not run: flog.appender(appender.console(), name='my.logger') # Set an appender to the logger named 'my.package'. Any log operations from # this package will now use this appender. flog.appender(appender.file('my.package.out'), 'my.package') ## End(Not run)
Indicate whether the logger will always return the log message despite the threshold.
carp |
logical Whether to carp output or not |
name |
character The name of the logger |
This is a special option to allow the return value of the flog.* logging functions to return the generated log message even if the log level does not exceed the threshold. Note that this minorly impacts performance when enabled. This functionality is separate from the appender, which is still bound to the value of the logger threshold.
# Indicate whether the given logger should carp
flog.carp(name=ROOT)
# Set whether the given logger should carp
flog.carp(carp, name=ROOT)
Brian Lee Yung Rowe
flog.carp(TRUE) x <- flog.debug("Returns this message but won't print") flog.carp(FALSE) y <- flog.debug("Returns nothing and prints nothing")flog.carp(TRUE) x <- flog.debug("Returns this message but won't print") flog.carp(FALSE) y <- flog.debug("Returns nothing and prints nothing")
Provides functions for managing layouts. Typically 'flog.layout' is only used when manually creating a logging configuration.
... |
Used internally by lambda.r |
# Get the layout function for the given logger
flog.layout(name) %::% character : Function
flog.layout(name='ROOT')
# Set the layout function for the given logger
flog.layout(fn, name='ROOT')
# Decorate log messages with a standard format
layout.simple(level, msg, ...)
# Generate log messages as JSON
layout.json(level, msg, ...)
# Decorate log messages using a custom format
layout.format(format, datetime.fmt="
# Show the value of a single variable layout.tracearg(level, msg, ...)
Layouts are responsible for formatting messages so they are human-readable.
Similar to an appender, a layout is assigned to a logger by calling
flog.layout. The flog.layout function is used internally
to get the registered layout function. It is kept visible so
user-level introspection is possible.
layout.simple is a pre-defined layout function that
prints messages in the following format:
LEVEL [timestamp] message
This is the default layout for the ROOT logger.
layout.format allows you to specify the format string to use
in printing a message. The following tokens are available.
Log level
Timestamp
Namespace
The calling function
The message
layout.json converts the message and any additional objects provided
to a JSON structure. E.g.:
flog.info("Hello, world", cat='asdf')
yields something like
{"level":"INFO","timestamp":"2015-03-06 19:16:02 EST","message":"Hello, world","func":"(shell)","cat":["asdf"]}
layout.tracearg is a special layout that takes a variable
and prints its name and contents.
Brian Lee Yung Rowe
# Set the layout for 'my.package' flog.layout(layout.simple, name='my.package') # Update the ROOT logger to use a custom layout layout <- layout.format('[~l] [~t] [~n.~f] ~m') flog.layout(layout) # Create a custom logger to trace variables flog.layout(layout.tracearg, name='tracer') x <- 5 flog.info(x, name='tracer')# Set the layout for 'my.package' flog.layout(layout.simple, name='my.package') # Update the ROOT logger to use a custom layout layout <- layout.format('[~l] [~t] [~n.~f] ~m') flog.layout(layout) # Create a custom logger to trace variables flog.layout(layout.tracearg, name='tracer') x <- 5 flog.info(x, name='tracer')
Provides functions for writing log messages and managing loggers. Typically only the flog.[trace|debug|info|warn|error|fatal] functions need to be used in conjunction with flog.threshold to interactively change the log level.
msg |
The message to log |
name |
The logger name to use |
capture |
Capture print output of variables instead of interpolate |
... |
Optional arguments to populate the format string |
expr |
An expression to evaluate |
finally |
An optional expression to evaluate at the end |
# Conditionally print a log statement at TRACE log level
flog.trace(msg, ..., name=flog.namespace(), capture=FALSE)
# Conditionally print a log statement at DEBUG log level
flog.debug(msg, ..., name=flog.namespace(), capture=FALSE)
# Conditionally print a log statement at INFO log level
flog.info(msg, ..., name=flog.namespace(), capture=FALSE)
# Conditionally print a log statement at WARN log level
flog.warn(msg, ..., name=flog.namespace(), capture=FALSE)
# Conditionally print a log statement at ERROR log level
flog.error(msg, ..., name=flog.namespace(), capture=FALSE)
# Print a log statement at FATAL log level
flog.fatal(msg, ..., name=flog.namespace(), capture=FALSE)
# Execute an expression and capture any warnings or errors ftry(expr, error=stop, finally=NULL)
These functions generally do not need to be called by an end user.
# Get the ROOT logger
flog.logger()
# Get the logger with the specified name
flog.logger(name)
# Set options for the given logger
flog.logger(name, threshold=NULL, appender=NULL, layout=NULL, carp=NULL)
These functions represent the high level interface to futile.logger.
The primary use case for futile.logger is to write out log messages. There are log writers associated with all the predefined log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. Log messages will only be written if the log level is equal to or more urgent than the current threshold. By default the ROOT logger is set to INFO.
> flog.debug("This won't print")
> flog.info("But this %s", 'will')
> flog.warn("As will %s", 'this')
Typically, the built in log level constants are used in the call, which conform to the log4j levels (from least severe to most severe): TRACE, DEBUG, INFO, WARN, ERROR, FATAL. It is not a strict requirement to use these constants (any numeric value will work), though most users should find this level of granularity sufficient.
Loggers are hierarchical in the sense that any requested logger that is undefined will fall back to its most immediate defined parent logger. The absolute parent is ROOT, which is guaranteed to be defined for the system and cannot be deleted. This means that you can specify a new logger directly.
> flog.info("This will fall back to 'my', then 'ROOT'", name='my.logger')
You can also change the threshold or any other setting associated with a logger. This will create an explicit logger where any unspecified options are copied from the parent logger.
> flog.appender(appender.file("foo.log"), name='my')
> flog.threshold(ERROR, name='my.logger')
> flog.info("This won't print", name='my.logger')
> flog.error("This
If you define a logger that you later want to remove, use flog.remove.
The option 'capture' allows you to print out more complicated data structures without a lot of ceremony. This variant doesn't accept format strings and instead appends the value to the next line of output. Consider
> m <- matrix(rnorm(12), nrow=3)
> flog.info("Matrix:",m, capture=TRUE)
which preserves the formatting, whereas using capture=FALSE will have a cluttered output due to recycling.
Brian Lee Yung Rowe
flog.threshold flog.remove
flog.carp flog.appender flog.layout
flog.threshold(DEBUG) flog.debug("This debug message will print") flog.threshold(WARN) flog.debug("This one won't") m <- matrix(rnorm(12), nrow=3) flog.info("Matrix:",m, capture=TRUE) ftry(log(-1)) ## Not run: s <- c('FCX','AAPL','JPM','AMZN') p <- TawnyPortfolio(s) flog.threshold(TRACE,'tawny') ws <- optimizePortfolio(p, RandomMatrixDenoiser()) z <- getIndexComposition() flog.threshold(WARN,'tawny') ws <- optimizePortfolio(p, RandomMatrixDenoiser()) z <- getIndexComposition() ## End(Not run)flog.threshold(DEBUG) flog.debug("This debug message will print") flog.threshold(WARN) flog.debug("This one won't") m <- matrix(rnorm(12), nrow=3) flog.info("Matrix:",m, capture=TRUE) ftry(log(-1)) ## Not run: s <- c('FCX','AAPL','JPM','AMZN') p <- TawnyPortfolio(s) flog.threshold(TRACE,'tawny') ws <- optimizePortfolio(p, RandomMatrixDenoiser()) z <- getIndexComposition() flog.threshold(WARN,'tawny') ws <- optimizePortfolio(p, RandomMatrixDenoiser()) z <- getIndexComposition() ## End(Not run)
In the event that you no longer wish to have a logger registered, use this function to remove it. Then any references to this logger will inherit the next available logger in the hierarchy.
name |
The logger name to use |
# Remove a logger
flog.remove(name)
Brian Lee Yung Rowe
flog.threshold(ERROR, name='my.logger') flog.info("Won't print", name='my.logger') flog.remove('my.logger') flog.info("Will print", name='my.logger')flog.threshold(ERROR, name='my.logger') flog.info("Won't print", name='my.logger') flog.remove('my.logger') flog.info("Will print", name='my.logger')
The threshold affects the visibility of a given logger. When a log
statement is called, e.g. flog.debug('foo'), futile.logger
compares the threshold of the logger with the level implied in the
log command (in this case DEBUG). If the log level is at or higher
in priority than the logger threshold, a message will print.
Otherwise the command will silently return.
threshold |
integer The new threshold for the given logger |
name |
character The name of the logger |
# Get the threshold for the given logger
flog.threshold(name) %::% character : character
flog.threshold(name=ROOT)
# Set the threshold for the given logger
flog.threshold(threshold, name=ROOT)
Brian Lee Yung Rowe
flog.threshold(ERROR) flog.info("Won't print") flog.threshold(INFO) flog.info("Will print")flog.threshold(ERROR) flog.info("Won't print") flog.threshold(INFO) flog.info("Will print")
This function integrates futile.logger with the error and warning system so problems can be caught both in the standard R warning system, while also being emitted via futile.logger.
ftry(expr, error = stop, finally = NULL)ftry(expr, error = stop, finally = NULL)
expr |
The expression to evaluate in a try block |
error |
An error handler |
finally |
Pass-through to tryCatch finally |
Brian Lee Yung Rowe
ftry(log(-1))ftry(log(-1))
Log level constants and the logger options.
logger.options(..., simplify = FALSE, update = list())logger.options(..., simplify = FALSE, update = list())
... |
TODO |
simplify |
TODO |
update |
TODO |
The logging configuration is managed by 'logger.options', a function generated by OptionsManager within 'futile.options'.
Brian Lee Yung Rowe
futile.options
A replacement for cat that has built-in sprintf formatting
scat(format, ..., use.newline = TRUE)scat(format, ..., use.newline = TRUE)
format |
A format string passed to sprintf |
use.newline |
Whether to append a new line at the end |
... |
Arguments to pass to sprintf for dereferencing |
Like cat but you can use format strings.
A formatted string printed to the console
Brian Lee Yung Rowe
apply(array(2:5),1, function(x) scat('This has happened %s times', x) )apply(array(2:5),1, function(x) scat('This has happened %s times', x) )