https://github.com/r-lib/log4r
A fast & lightweight approach to logging in R based on the widely-emulated Apache Log4j project.
https://github.com/r-lib/log4r
logging r
Last synced: 8 months ago
JSON representation
A fast & lightweight approach to logging in R based on the widely-emulated Apache Log4j project.
- Host: GitHub
- URL: https://github.com/r-lib/log4r
- Owner: r-lib
- Created: 2010-08-25T01:56:42.000Z (about 15 years ago)
- Default Branch: main
- Last Pushed: 2024-10-18T17:08:28.000Z (about 1 year ago)
- Last Synced: 2025-03-31T15:25:36.787Z (8 months ago)
- Topics: logging, r
- Language: R
- Homepage: https://log4r.r-lib.org
- Size: 1.44 MB
- Stars: 95
- Watchers: 7
- Forks: 22
- Open Issues: 11
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
Awesome Lists containing this project
- jimsghstars - r-lib/log4r - A fast & lightweight approach to logging in R based on the widely-emulated Apache Log4j project. (R)
README
---
output: github_document
---
```{r setup, include = FALSE, warning = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(log4r)
```
# log4r
[](https://cran.r-project.org/package=log4r)
[](https://github.com/johnmyleswhite/log4r/actions/workflows/R-CMD-check.yaml)
**log4r** is a fast, lightweight, object-oriented approach to logging in R based
on the widely-emulated [Apache Log4j](https://logging.apache.org/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:
```r
install.packages("log4r")
```
If you want to use the development version, you can install the package from
GitHub as follows:
```r
# 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:
```{r basic-example}
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:
```{r file-example, echo = 1:7}
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:
```{r layout-example}
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:
```{r sl-example}
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:
```{r old-api, echo = 1:12}
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.