---

output: github_document

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(log4r)

log4r

log4r is a fast, lightweight, object-oriented approach to logging in R based
on the widely-emulated Apache Log4j project.

log4r differs from other R logging packages in its focus on performance and
simplicity. As such, it has fewer features – although it is still quite
extensible, as seen below – but is much faster. See
vignette("performance", package = "log4r") for details.

Unlike other R logging packages, log4r also has first-class support for
structured logging. See vignette("structured-logging", package = "log4r") for
details.

Installation

The package is available from CRAN:

install.packages("log4r")

If you want to use the development version, you can install the package from
GitHub as follows:

# install.packages("remotes")
remotes::install_github("johnmyleswhite/log4r")

Usage

Logging is configured by passing around logger objects created by logger().
By default, this will log to the console and suppress messages below the
"INFO" level:

logger <- logger()

log_info(logger, "Located nearest gas station.")
log_warn(logger, "Ez-Gas sensor network is not available.")
log_debug(logger, "Debug messages are suppressed by default.")

Logging destinations are controlled by Appenders, a few of which are
provided by the package. For instance, if we want to debug-level messages to a
file:

log_file <- tempfile()
logger <- logger("DEBUG", appenders = file_appender(log_file))

log_info(logger, "Messages are now written to the file instead.")
log_debug(logger, "Debug messages are now visible.")

readLines(log_file)
unlink(log_file)

The appenders parameter takes a list, so you can log to multiple destinations
transparently.

For local development or simple batch R scripts run manually, writing log
messages to a file for later inspection is convenient. However, for deployed R
applications or automated scripts it is more likely you will need to send logs
to a central location; see
vignette("logging-beyond-local-files", package = "log4r").

To control the format of the messages you can change the Layout used by
each appender. Layouts are functions; you can write your own quite easily:

my_layout <- function(level, ...) {
  paste0(format(Sys.time()), " [", level, "] ", ..., collapse = "")
}

logger <- logger(appenders = console_appender(my_layout))
log_info(logger, "Messages should now look a little different.")

With an appropriate layout, you can also use structured logging, enriching log
messages with contextual fields:

logger <- logger(appenders = console_appender(logfmt_log_layout()))
log_info(
  logger, message = "processed entries", file = "catpics_01.csv",
  entries = 4124, elapsed = 2.311
)

Older APIs

The 0.2 API is still supported, but will issue deprecation warnings when used:

logger <- create.logger()

logfile(logger) <- log_file
level(logger) <- "INFO"

debug(logger, 'A Debugging Message')
info(logger, 'An Info Message')
warn(logger, 'A Warning Message')
error(logger, 'An Error Message')
fatal(logger, 'A Fatal Error Message')

readLines(log_file)
unlink(log_file)

License

The package is available under the terms of the Artistic License 2.0.