-
Notifications
You must be signed in to change notification settings - Fork 44
/
README.Rmd
121 lines (88 loc) · 5.99 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# logger <a href="https://daroczig.github.io/logger/"><img src="man/figures/logo.png" align="right" height="138" alt="logger website" /></a>
<!-- badges: start -->
[](https://www.repostatus.org/#active) [](https://cran.r-project.org/package=logger) [](https://github.com/daroczig/logger/actions) [](https://app.codecov.io/gh/daroczig/logger) [](https://mikata.dev)
<!-- badges: end -->
A lightweight, modern and flexible logging utility for R -- heavily inspired by the `futile.logger` R package and `logging` Python module.
## Installation
[](https://cran.r-project.org/package=logger)
```{r}
#| eval: false
install.packages("logger")
```
The most recent, development version of `logger` can also be installed from GitHub:
```{r}
#| eval: false
# install.packages("pak")
pak::pak("daroczig/logger")
```
## Quick example
Setting the log level threshold to something low and logging various messages in ad-hoc and programmatic ways:
```{r}
#| include: false
library(logger)
log_appender(appender_stdout)
```
```{r}
library(logger)
log_threshold(DEBUG)
log_info("Script starting up...")
pkgs <- available.packages()
log_info("There are {nrow(pkgs)} 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"
)
}
log_warn("There might be many, like {1:2} or more warnings!!!")
```
You can even use a custom log layout to render the log records with colors, as you can see in `layout_glue_colors()`:
<img src="man/figures/colors.png" alt="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 `vignette("write_custom_extensions")`.
## Related work
There are many other logging packages available on CRAN:
- [`futile.logger`](https://cran.r-project.org/package=futile.logger): probably the most popular `log4j` variant (and I'm a big fan)
- [`logging`](https://cran.r-project.org/package=logging): just like Python's `logging` package
- [`lgr`](https://cran.r-project.org/package=lgr): built on top of R6.
- [`loggit`](https://cran.r-project.org/package=loggit): capture `message`, `warning` and `stop` function messages in a JSON file
- [`log4r`](https://cran.r-project.org/package=log4r): `log4j`-based, object-oriented logger
- [`rsyslog`](https://cran.r-project.org/package=rsyslog): logging to `syslog` on 'POSIX'-compatible operating systems
- [`lumberjack`](https://cran.r-project.org/package=lumberjack): provides a special operator to log changes in data
Why use logger? I decided to write the `n+1`th extensible `log4j` logger that fits my liking --- and hopefully yours as well --- with the aim to:
- Keep it close to `log4j`.
- Respect the modern 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()` (e.g. 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 (e.g. 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 `ERROR`s to DataDog and eg `INFO` messages to CloudWatch.
- Optionally colorize log message based on the log level.
- Make logging fun!
Welcome to the [Bazaar](https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar)! If you already use any of the above packages for logging, you might find `vignette("migration")` useful.
## Interested in more details?
::: .pkgdown-hide
Check out the main documentation site at <https://daroczig.github.io/logger/> or the vignettes on the below topics:
* [Introduction to logger](https://daroczig.github.io/logger/articles/Intro.html)
* [The Anatomy of a Log Request](https://daroczig.github.io/logger/articles/anatomy.html)
* [Customizing the Format and the Destination of a Log Record](https://daroczig.github.io/logger/articles/customize_logger.html)
* [Writing Custom Logger Extensions](https://daroczig.github.io/logger/articles/write_custom_extensions.html)
* [Migration Guide from other logging packages](https://daroczig.github.io/logger/articles/migration.html)
* [Logging from R Packages](https://daroczig.github.io/logger/articles/r_packages.html)
* [Simple Benchmarks on Performance](https://daroczig.github.io/logger/articles/performance.html)
:::
If you prefer visual content, you can watch the video recording of the "Getting things logged" talk at RStudio::conf(2020):
[](https://www.youtube.com/watch?v=_rUuBbml9dU)