Skip to contents

Getting Started

Source: vignettes/loggit2.Rmd
loggit2.Rmd

loggit2 is an easy-to-use, yet powerful, ndjson logger. It is very fast, has zero external dependencies, and can be as straightforward or as integral as you want to make it.

Preparation

No preparations are needed to use loggit2. However, it is recommended to explicitly set a log file using loggit2::set_logfile("path/to/your/file"), as loggit2 defaults to creating a file in your temporary directory.1

In order to use the full potential of loggit2, it is advisable to take a look at the further configurations after reading this vignette.

Logging

There are three ways to populate the log in loggit2. First, through wrapper functions of the base R condition handler, second, via the loggit() log function, and third, by logging (external) expressions using with_loggit().

Each function of these three methods has the parameter echo, which determines whether the log entries should also be echoed to stdout.

Condition Log Handling

loggit2 provides a set of wrappings for base R’s message(), warning(), stop() and stopifnot() functions that maintain identical functionality2, except the additional logging. Thus, it is sufficient to import the loggit2 namespace, for example by using library("loggit2"), or by prefixing loggit2:: at the desired locations.

base::message("This is another message")
#> This is another message
loggit2::message("This is a message")
#> {"timestamp": "2024-07-25T16:49:54+0000", "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-07-25T16:49:54+0000", "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-07-25T16:49:54+0000", "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-07-25T16:49:54+0000", "log_lvl": "ERROR", "log_msg": "This is another condition"}
#> Error: This is another condition

Besides the echo parameter, the functions have an additional parameter .loggit, which allows to deactivate the logging such that the function behaves exactly like the base R equivalents.

loggit2::warning("This is a alternative warning", echo = FALSE)
#> Warning: This is a alternative warning

loggit2::warning("This is not part of the log", .loggit = FALSE)
#> Warning: This is not part of the log
Click here to see the generated log 
#>                  timestamp log_lvl                       log_msg
#> 1 2024-07-25T16:49:54+0000    INFO           This is a message\n
#> 2 2024-07-25T16:49:54+0000    WARN             This is a warning
#> 3 2024-07-25T16:49:54+0000   ERROR              This is an error
#> 4 2024-07-25T16:49:54+0000   ERROR     This is another condition
#> 5 2024-07-25T16:49:54+0000    WARN This is a alternative warning

Explicit Log Function

loggit2 allows direct access to the core logging function loggit(). This enables setting the log level directly during the call and creating arbitrary fields in the log.

This function does not trigger any conditions; it only populates the log.

loggit2::loggit("INFO", "This is a message", ID = 1L, boole = TRUE)
#> {"timestamp": "2024-07-25T16:49:54+0000", "log_lvl": "INFO", "log_msg": "This is a message", "ID": "1", "boole": "TRUE"}

loggit2::loggit("WARN", "This is a alternative warning", echo = FALSE)

loggit2::loggit("DEBUG", "This is a message", Why = "Because", echo = FALSE)

To allow log levels other than “DEBUG”, “INFO”, “WARN” or “ERROR” the custom_log_lvl parameter must be set.

loggit2::loggit("CRITICAL", "Critical error")
#> Error in loggit2::loggit("CRITICAL", "Critical error"): Nonstandard log_lvl ('CRITICAL').
#> Should be one of DEBUG, INFO, WARN, or ERROR. Please check if you made a typo.
#> If you insist on passing a custom level, please set 'custom_log_lvl = TRUE' in the call to 'loggit()'.

loggit2::loggit("CRITICAL", "Critical error 2", custom_log_lvl = TRUE)
#> {"timestamp": "2024-07-25T16:49:54+0000", "log_lvl": "CRITICAL", "log_msg": "Critical error 2"}
Click here to see the generated log 
#>                  timestamp  log_lvl                       log_msg   ID boole     Why
#> 1 2024-07-25T16:49:54+0000     INFO             This is a message    1  TRUE    <NA>
#> 2 2024-07-25T16:49:54+0000     WARN This is a alternative warning <NA>  <NA>    <NA>
#> 3 2024-07-25T16:49:54+0000    DEBUG             This is a message <NA>  <NA> Because
#> 4 2024-07-25T16:49:54+0000 CRITICAL              Critical error 2 <NA>  <NA>    <NA>

Log Expressions

One will repeatedly encounter situations where conditions need to be logged from code without wanting to or being able to modify it (e.g., when dealing with functions from external packages). In this case, with_loggit() comes into play. This function allows logging conditions from arbitrary expressions without restricting functionality3 or needing to modify the code.

fun_a <- function(x) {
  base::warning("This is a warning")
  base::message("This is a message")
  base::stopifnot("This is true" = 3L == 1L + 2L, "This is not TRUE" = FALSE)
}

fun_b <- function(x) {
  base::warning("This is a second warning")
  5L + 5L
}
x <- loggit2::with_loggit(fun_b())
#> {"timestamp": "2024-07-25T16:49:54+0000", "log_lvl": "WARN", "log_msg": "This is a second warning"}
#> Warning in fun_b(): This is a second warning
print(x)
#> [1] 10
loggit2::with_loggit({
  x <- fun_b()
  fun_a()
}, echo = FALSE)
#> Warning in fun_b(): This is a second warning
#> Warning in fun_a(): This is a warning
#> This is a message
#> Error in fun_a(): This is not TRUE

Additionally, with_loggit() allows alternative settings (logfile, echo, etc.) to be used for a specific section of code.

Click here to see the generated log 
#>                  timestamp log_lvl                  log_msg
#> 1 2024-07-25T16:49:54+0000    WARN This is a second warning
#> 2 2024-07-25T16:49:54+0000    WARN This is a second warning
#> 3 2024-07-25T16:49:54+0000    WARN        This is a warning
#> 4 2024-07-25T16:49:54+0000    INFO      This is a message\n
#> 5 2024-07-25T16:49:54+0000   ERROR         This is not TRUE

Post-Processing

A log is of little use without the ability to access and modify it. Here are a few possibilities.

Accessing the Log

As seen above, the log can be queried as a data.frame using read_logs().

loggit2::read_logs()
#>                  timestamp log_lvl                  log_msg
#> 1 2024-07-25T16:49:54+0000    WARN This is a second warning
#> 2 2024-07-25T16:49:54+0000    WARN This is a second warning
#> 3 2024-07-25T16:49:54+0000    WARN        This is a warning
#> 4 2024-07-25T16:49:54+0000    INFO      This is a message\n
#> 5 2024-07-25T16:49:54+0000   ERROR         This is not TRUE

Alternatively, the log can also be saved as a CSV file using convert_to_csv().

loggit2::convert_to_csv("path/to/your/file.csv")

Rotating the Log

To maintain a clear log even in long-running sessions (e.g., in a Shiny app hosted on a server), the log can be restricted to the last n entries using rotate_logs(n).

loggit2::rotate_logs(2L)
Click here to see the generated log 
#>                  timestamp log_lvl             log_msg
#> 1 2024-07-25T16:49:54+0000    INFO This is a message\n
#> 2 2024-07-25T16:49:54+0000   ERROR    This is not TRUE
loggit2::rotate_logs(0L)
Click here to see the generated log 
#> [1] timestamp log_lvl   log_msg  
#> <0 rows> (or 0-length row.names)