# Easy-to-use, dependencyless Logger for R `loggit2` is an easy-to-use [`ndJSON`](https://github.com/ndjson/ndjson-spec) logging library for R, with *zero* external dependencies. Please see below for some quick examples, and read the [vignettes](https://cran.r-project.org/web/packages/loggit2/vignettes/) for more. ## Why use `loggit2`? `loggit2` takes a minimalistic but powerful approach to logging in R: - Easy integration, even into existing code - Flexible logs with automatic field creation - Logs immediately available as `data.frame` object, ndJSON and CSV file - Simple external logging (e.g., in containers) via ndJSON echo to stdout - *Zero* external dependencies Additionally, the boilerplate to get going with `loggit2` is minimal at worst. ## Usage `loggit2` provides, among other functions, a set of wrappings for base R’s [`message()`](https://r-loggit.org/reference/message.md), [`warning()`](https://r-loggit.org/reference/warning.md), [`stop()`](https://r-loggit.org/reference/stop.md) and [`stopifnot()`](https://r-loggit.org/reference/stopifnot.md) functions that maintain identical functionality, except the additional logging. Thus, it is sufficient to import the `loggit2` namespace, for example by using [`library("loggit2")`](https://github.com/MEO265/loggit2), or by prefixing `loggit2::` at the desired locations. ``` r base::message("This is another message") #> This is another message loggit2::message("This is a message") #> {"timestamp": "2024-05-26T16:39:20+0200", "log_lvl": "INFO", "log_msg": "This is a message\n"} #> This is a message base::warning("This is another warning") #> Warning: This is another warning loggit2::warning("This is a warning") #> {"timestamp": "2024-05-26T16:39:20+0200", "log_lvl": "WARN", "log_msg": "This is a warning"} #> Warning: This is a warning base::stop("This is another error") #> Error in eval(expr, envir, enclos): This is another error loggit2::stop("This is an error") #> {"timestamp": "2024-05-26T16:39:20+0200", "log_lvl": "ERROR", "log_msg": "This is an error"} #> Error in eval(expr, envir, enclos): This is an error base::stopifnot("This is another condition" = FALSE) #> Error: This is another condition loggit2::stopifnot("This is another condition" = FALSE) #> {"timestamp": "2024-05-26T16:39:20+0200", "log_lvl": "ERROR", "log_msg": "This is another condition"} #> Error: This is another condition ``` You can suppress the additional console output by using `echo = FALSE` and you won’t notice any difference to the base functions (except that the log will be filled in the background). You can also directly use the logging function [`loggit()`](https://r-loggit.org/reference/loggit.md) to compose much more custom logs, e.g. to include custom fields or to prevent throwing actual conditions. ``` r loggit2::loggit("ERROR", "This will log an error", anything_else = "you want to include") #> {"timestamp": "2024-05-26T16:39:20+0200", "log_lvl": "ERROR", "log_msg": "This will log an error", "anything_else": "you want to include"} # Read log file into data frame to implement logic based on entries loggit2::read_logs() #> timestamp log_lvl log_msg anything_else #> 1 2024-05-26T16:39:20+0200 INFO This is a message\n #> 2 2024-05-26T16:39:20+0200 WARN This is a warning #> 3 2024-05-26T16:39:20+0200 ERROR This is an error #> 4 2024-05-26T16:39:20+0200 ERROR This is another condition #> 5 2024-05-26T16:39:20+0200 ERROR This will log an error you want to include ``` No further configurations are necessary for this: just throw nearly whatever you want at it, and it’ll become a structured log. Check out the [vignettes](https://cran.r-project.org/web/packages/loggit2/vignettes/) for more details and features. ## Installation You can install the latest CRAN release of `loggit2` via ``` R install.packages("loggit2") ``` or, get the latest development version from GitHub via ``` R devtools::install_github("MEO265/loggit2") ``` ## Acknowledgments This package is based on the [“loggit” package by Ryan Price](https://github.com/ryapric/loggit), specifically version 2.1.1. # Package index ## Condition log handlers - [`message()`](https://r-loggit.org/reference/message.md) : Message Log Handler - [`warning()`](https://r-loggit.org/reference/warning.md) : Warning Log Handler - [`stop()`](https://r-loggit.org/reference/stop.md) : Stop Log Handler - [`stopifnot()`](https://r-loggit.org/reference/stopifnot.md) : Conditional Stop Log Handler ## Non-base log handlers - [`debuginfo()`](https://r-loggit.org/reference/debuginfo.md) : Debug Log Handler ## Log functions - [`loggit()`](https://r-loggit.org/reference/loggit.md) : Log messages and R objects - [`with_loggit()`](https://r-loggit.org/reference/with_loggit.md) : Log any expressions ## Utility functions - [`read_logs()`](https://r-loggit.org/reference/read_logs.md) : Get log as `data.frame` - [`rotate_logs()`](https://r-loggit.org/reference/rotate_logs.md) : Rotate log file - [`convert_to_csv()`](https://r-loggit.org/reference/convert_to_csv.md) : Write log to csv file ## Configuration - [`set_call_options()`](https://r-loggit.org/reference/set_call_options.md) : Set Call Options - [`set_echo()`](https://r-loggit.org/reference/set_echo.md) : Set echo - [`set_log_level()`](https://r-loggit.org/reference/set_log_level.md) : Set Log Level - [`set_logfile()`](https://r-loggit.org/reference/set_logfile.md) : Set Log File - [`set_timestamp_format()`](https://r-loggit.org/reference/set_timestamp_format.md) : Set Timestamp Format - [`get_call_options()`](https://r-loggit.org/reference/get_call_options.md) : Get Call Options - [`get_echo()`](https://r-loggit.org/reference/get_echo.md) : Get echo - [`get_log_level()`](https://r-loggit.org/reference/get_log_level.md) : Get Log Level - [`get_logfile()`](https://r-loggit.org/reference/get_logfile.md) : Get Log File - [`get_timestamp_format()`](https://r-loggit.org/reference/get_timestamp_format.md) : Get Timestamp Format # Articles ### All vignettes - [Why the Fork?](https://r-loggit.org/articles/fork.md): What does `loggit2` offer that `loggit` doesn’t? And why was a fork necessary? - [Further Configurations](https://r-loggit.org/articles/further_configurations.md): An overview of the configuration options of loggit2. - [Getting Started](https://r-loggit.org/articles/loggit2.md): An introduction to the basic functionality of `loggit2`.