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.
Arguments
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
Usage
# 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)
Additional Usage
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)
Details
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.
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.