logger v0.1

0

Monthly downloads

0th

Percentile

A Lightweight, Modern and Flexible Logging Utility

Inspired by the the 'futile.logger' R package and 'logging' Python module, this utility provides a flexible and extensible way of formatting and delivering log messages with low overhead.

Readme

logger

Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. CRAN Build Status Code Coverage

A lightweight, modern and flexibly logging utility for R -- heavily inspired by the futile.logger R package and logging Python module.

Installation

logger is not on CRAN yet, please install from GitHub:

remotes::install_github('daroczig/logger')

Quick example

Setting the log level threshold to something low and logging various messages in ad-hoc and programmatic ways:

library(logger)
log_threshold(DEBUG)
log_info('Script starting up...')
#> INFO [2018-20-11 22:49:36] Script starting up...

pkgs <- available.packages()
log_info('There are {nrow(pkgs)} R packages hosted on CRAN!')
#> INFO [2018-20-11 22:49:37] There are 13433 R packages hosted on CRAN!

for (letter in letters) {
    lpkgs <- sum(grepl(letter, pkgs[, 'Package'], ignore.case = TRUE))
    log_level(if (lpkgs < 5000) TRACE else DEBUG,
              '{lpkgs} R packages including the {shQuote(letter)} letter')
}
#> DEBUG [2018-20-11 22:49:38] 6300 R packages including the 'a' letter
#> DEBUG [2018-20-11 22:49:38] 6772 R packages including the 'e' letter
#> DEBUG [2018-20-11 22:49:38] 5412 R packages including the 'i' letter
#> DEBUG [2018-20-11 22:49:38] 7014 R packages including the 'r' letter
#> DEBUG [2018-20-11 22:49:38] 6402 R packages including the 's' letter
#> DEBUG [2018-20-11 22:49:38] 5864 R packages including the 't' letter

log_warn('There might be many, like {1:2} or more warnings!!!')
#> WARN [2018-20-11 22:49:39] There might be many, like 1 or more warnings!!!
#> WARN [2018-20-11 22:49:39] There might be many, like 2 or more warnings!!!

Setting a custom log layout to render the log records with colors:

library(logger)
log_layout(layout_glue_colors)
log_threshold(TRACE)
log_info('Starting the script...')
log_debug('This is the second log line')
log_trace('Note that the 2nd line is being placed right after the 1st one.')
log_success('Doing pretty well so far!')
log_warn('But beware, as some errors might come :/')
log_error('This is a problem')
log_debug('Note that getting an error is usually bad')
log_error('This is another problem')
log_fatal('The last problem')

Or simply run the related demo:

demo(colors, package = 'logger', echo = FALSE)

colored log output

But you could set up any custom colors and layout, eg using custom colors only for the log levels, make it grayscale, include the calling function or R package namespace with specific colors etc. For more details, see the related vignettes.

Why yet another logging R package?

Although there are multiple pretty good options already hosted on CRAN when it comes to logging in R, such as

  • futile.logger: probably the most popular log4j variant (and I'm a big fan)
  • logging: just like Python's logging package
  • loggit: capture message, warning and stop function messages in a JSON file
  • log4r: log4j-based, object-oriented logger
  • rsyslog: logging to syslog on 'POSIX'-compatible operating systems
  • lumberjack: provides a special operator to log changes in data

Also many more work-in-progress R packages hosted on eg GitHub, such as

But some/most of these packages are

  • not actively maintained any more, and/or maintainers are not being open for new features / patches
  • not being modular enough for extensions
  • prone to scoping issues
  • using strange syntax elements, eg dots in function names or object-oriented approaches not being very familiar to most R users
  • requires a lot of typing and code repetitions

So based on all the above subjective opinions, I decided to write the n+1th extensible log4j logger that fits my liking -- and hopefully yours as well -- with the focus being on:

  • keep it close to log4j
  • respect the most recent function / variable naming conventions and general R coding style
  • by default, rely on glue when it comes to formatting / rendering log messages, but keep it flexible if others prefer sprintf (eg for performance reasons) or other functions
  • support vectorization (eg passing a vector to be logged on multiple lines)
  • make it easy to extend with new features (eg custom layouts, message formats and output)
  • prepare for writing to various services, streams etc
  • provide support for namespaces, preferably automatically finding and creating a custom namespace for all R packages writing log messages, each with optionally configurable log level threshold, message and output formats
  • allow stacking loggers to implement logger hierarchy -- even within a namespace, so that the very same log call can write all the TRACE log messages to the console, while only pushing ERRORs to DataDog and eg INFO messages to CloudWatch
  • optionally colorize log message based on the log level
  • make logging fun

Welcome to the Bazaar, and if you have happened to already use any of the above mentioned R packages for logging, you might find useful the Migration Guide.

Interested in more details?

Check out the main documentation site at https://daroczig.github.io/logger or the vignettes on the below topics:

Functions in logger

Name Description
formatter_glue Apply glue to convert R objects into a character vector
appender_console Append log record to stdout
formatter_glue_or_sprintf Apply glue and sprintf
formatter_logging Mimic the default formatter used in the logging package
appender_file Append log messages to a file
formatter_sprintf Apply sprintf to convert R objects into a character vector
log_appender Get or set log record appender function
formatter_paste Concatenate R objects into a character vector via paste
get_logger_definitions Find the logger definition(s) specified for the current namespace with a fallback to the global namespace
log_eval Evaluate an expression and log results
log_level Log a message with given log level
colorize_by_log_level Colorize string by the related log level
appender_tee Append log messages to a file and stdout as well
FATAL Log levels
appender_pushbullet Send log messages to Pushbullet
appender_slack Send log messages to a Slack channel
layout_glue_generator Generate log layout function using common variables available via glue syntax
log_threshold Get or set log level threshold
layout_json Generate log layout function rendering JSON
layout_glue Format a log message with glue
layout_glue_colors Format a log message with glue and ANSI escape codes to add colors
logger Generate logging utility
skip_formatter Adds the skip_formatter attribute to an object so that logger will skip calling the formatter function on the object(s) to be logged
log_formatter Get or set log message formatter
log_layout Get or set log record layout
top_env_name Returns the name of the top level environment from which the logger was called
fail_on_missing_package Check if R package can be loaded and fails loudly otherwise
fallback_namespace Checks if provided namespace exists and falls back to global if not
get_logger_meta_variables Collect useful information about the logging environment to be used in log messages
grayscale_by_log_level Render a string with light/dark gray based on the related log level
layout_logging Format a log record as the logging package does by default
layout_simple Format a log record by concatenating the log level, timestamp and message
with_log_threshold Evaluate R expression with a temporarily updated log level threshold
No Results!

Vignettes of logger

Name
Intro.Rmd
anatomy.Rmd
customize_logger.Rmd
logger_structure.svg
migration.Rmd
performance.Rmd
r_packages.Rmd
write_custom_extensions.Rmd
No Results!

Last month downloads

Details

Type Package
Date 2018-12-20
URL https://github.com/daroczig/logger
Encoding UTF-8
RoxygenNote 6.1.0
License AGPL-3
VignetteBuilder knitr
NeedsCompilation no
Packaged 2019-01-02 14:50:01 UTC; daroczig
Repository CRAN
Date/Publication 2019-01-02 15:30:03 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/logger)](http://www.rdocumentation.org/packages/logger)