NotificationsYou must be signed in to change notification settings
Fork24
Star99

A fast & lightweight approach to logging in R based on the widely-emulated Apache Log4j project.

99 stars 24 forks Branches Tags Activity

You must be signed in to change notification settings

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 202 Commits
.github		.github
R		R
man		man
src		src
tests		tests
vignettes		vignettes
.Rbuildignore		.Rbuildignore
.gitignore		.gitignore
DESCRIPTION		DESCRIPTION
NAMESPACE		NAMESPACE
NEWS.md		NEWS.md
README.Rmd		README.Rmd
README.md		README.md
_pkgdown.yml		_pkgdown.yml
cran-comments.md		cran-comments.md
log4r.Rproj		log4r.Rproj

Repository files navigation

log4r

log4r is a fast, lightweight, object-oriented approach to logging inR based on the widely-emulatedApacheLog4j project.

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

Unlike other R logging packages,log4r also has first-class supportfor structured logging. Seevignette("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 packagefrom GitHub as follows:

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

Usage

Logging is configured by passing aroundlogger objects created bylogger(). By default, this will log to the console and suppressmessages below the"INFO" level:

logger<- logger()log_info(logger,"Located nearest gas station.")#> INFO  [2019-09-04 16:31:04] Located nearest gas station.log_warn(logger,"Ez-Gas sensor network is not available.")#> WARN  [2019-09-04 16:31:04] Ez-Gas sensor network is not available.log_debug(logger,"Debug messages are suppressed by default.")

Logging destinations are controlled byAppenders, a few of which areprovided by the package. For instance, if we want to debug-levelmessages 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)#> [1] "INFO  [2019-09-04 16:31:04] Messages are now written to the file instead."#> [2] "DEBUG [2019-09-04 16:31:04] Debug messages are now visible."

Theappenders parameter takes a list, so you can log to multipledestinations transparently.

For local development or simple batch R scripts run manually, writinglog messages to a file for later inspection is convenient. However, fordeployed R applications or automated scripts it is more likely you willneed to send logs to a central location; seevignette("logging-beyond-local-files", package = "log4r").

To control the format of the messages you can change theLayout usedby each appender. Layouts are functions; you can write your own quiteeasily:

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.")#> 2019-09-04 16:31:04 [INFO] Messages should now look a little different.

With an appropriate layout, you can also usestructured 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)#> level=INFO ts=2021-10-22T20:19:21Z 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 whenused:

logger<- create.logger()logfile(logger)<-log_filelevel(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)#> [1] "INFO  [2019-09-04 16:31:05] An Info Message"#> [2] "WARN  [2019-09-04 16:31:05] A Warning Message"#> [3] "ERROR [2019-09-04 16:31:05] An Error Message"#> [4] "FATAL [2019-09-04 16:31:05] A Fatal Error Message"