Various vignette tweaks

R/logger.R

@@ -30,9 +30,7 @@
 #'   function), and a list of `handlers` with the `formatter`,
 #'   `layout` and `appender` functions.
 #' @export
-#' @references For more details, see the Anatomy of a Log Request
-#'   vignette at
-#'   <https://daroczig.github.io/logger/articles/anatomy.html>.
+#' @references For more details, see vignette("customize_logger")
 #' @note It's quite unlikely that you need to call this function
 #'   directly, but instead set the logger parameters and functions at
 #'   [log_threshold()], [log_formatter()], [log_layout()] and

README.Rmd

@@ -106,13 +106,12 @@ Welcome to the [Bazaar](https://en.wikipedia.org/wiki/The_Cathedral_and_the_Baza
 
 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)
+* Introduction to logger: `vignette("logger")`.
+* Customizing the Format and the Destination of a Log Record: `vignette("customize_logger")`
+* Writing Custom Logger Extensions: `vignette("write_custom_extensions")`
+* Migration Guide from other logging packages: `vignette("migration")`
+* Logging from R Packages: `vignette("r_packages")`
+* Simple Benchmarks on Performance: `vignette("performance")`
 
 :::
 

README.md

@@ -46,11 +46,11 @@ messages in ad-hoc and programmatic ways:
 library(logger)
 log_threshold(DEBUG)
 log_info("Script starting up...")
-#> INFO [2024-08-15 11:59:27] Script starting up...
+#> INFO [2024-08-23 12:48:18] Script starting up...
 
 pkgs <- available.packages()
 log_info("There are {nrow(pkgs)} R packages hosted on CRAN!")
-#> INFO [2024-08-15 11:59:28] There are 21131 R packages hosted on CRAN!
+#> INFO [2024-08-23 12:48:19] There are 21137 R packages hosted on CRAN!
 
 for (letter in letters) {
   lpkgs <- sum(grepl(letter, pkgs[, "Package"], ignore.case = TRUE))
@@ -59,23 +59,23 @@ for (letter in letters) {
     "{lpkgs} R packages including the {shQuote(letter)} letter"
   )
 }
-#> DEBUG [2024-08-15 11:59:28] 10193 R packages including the 'a' letter
-#> DEBUG [2024-08-15 11:59:28] 7016 R packages including the 'c' letter
-#> DEBUG [2024-08-15 11:59:28] 5751 R packages including the 'd' letter
-#> DEBUG [2024-08-15 11:59:28] 10907 R packages including the 'e' letter
-#> DEBUG [2024-08-15 11:59:28] 8825 R packages including the 'i' letter
-#> DEBUG [2024-08-15 11:59:28] 7059 R packages including the 'l' letter
-#> DEBUG [2024-08-15 11:59:28] 7045 R packages including the 'm' letter
-#> DEBUG [2024-08-15 11:59:28] 6665 R packages including the 'n' letter
-#> DEBUG [2024-08-15 11:59:28] 7863 R packages including the 'o' letter
-#> DEBUG [2024-08-15 11:59:28] 6581 R packages including the 'p' letter
-#> DEBUG [2024-08-15 11:59:28] 11229 R packages including the 'r' letter
-#> DEBUG [2024-08-15 11:59:28] 10296 R packages including the 's' letter
-#> DEBUG [2024-08-15 11:59:28] 9531 R packages including the 't' letter
+#> DEBUG [2024-08-23 12:48:19] 10185 R packages including the 'a' letter
+#> DEBUG [2024-08-23 12:48:19] 7016 R packages including the 'c' letter
+#> DEBUG [2024-08-23 12:48:19] 5757 R packages including the 'd' letter
+#> DEBUG [2024-08-23 12:48:19] 10907 R packages including the 'e' letter
+#> DEBUG [2024-08-23 12:48:19] 8832 R packages including the 'i' letter
+#> DEBUG [2024-08-23 12:48:19] 7065 R packages including the 'l' letter
+#> DEBUG [2024-08-23 12:48:19] 7061 R packages including the 'm' letter
+#> DEBUG [2024-08-23 12:48:19] 6673 R packages including the 'n' letter
+#> DEBUG [2024-08-23 12:48:19] 7867 R packages including the 'o' letter
+#> DEBUG [2024-08-23 12:48:19] 6582 R packages including the 'p' letter
+#> DEBUG [2024-08-23 12:48:19] 11229 R packages including the 'r' letter
+#> DEBUG [2024-08-23 12:48:19] 10296 R packages including the 's' letter
+#> DEBUG [2024-08-23 12:48:19] 9525 R packages including the 't' letter
 
 log_warn("There might be many, like {1:2} or more warnings!!!")
-#> WARN [2024-08-15 11:59:28] There might be many, like 1 or more warnings!!!
-#> WARN [2024-08-15 11:59:28] There might be many, like 2 or more warnings!!!
+#> WARN [2024-08-23 12:48:19] There might be many, like 1 or more warnings!!!
+#> WARN [2024-08-23 12:48:19] There might be many, like 2 or more warnings!!!
 ```
 
 You can even use a custom log layout to render the log records with
@@ -144,20 +144,14 @@ 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)
+- Introduction to logger: `vignette("logger")`.
+- Customizing the Format and the Destination of a Log Record:
+  `vignette("customize_logger")`
+- Writing Custom Logger Extensions:
+  `vignette("write_custom_extensions")`
+- Migration Guide from other logging packages: `vignette("migration")`
+- Logging from R Packages: `vignette("r_packages")`
+- Simple Benchmarks on Performance: `vignette("performance")`
 
 </div>
 

_pkgdown.yml

@@ -6,7 +6,7 @@ template:
 authors:
   System1:
     href: https://system1.com
-    html: <img src="https://cdn.system1.com/s1c/dist/img/system1-logo.svg" height="14" width="70"/>
+    html: <img src="https://cdn.system1.com/s1c/dist/img/system1-logo.svg" alt="System1" height="14" width="70"/>
 toc:
   depth: 3
 
@@ -73,3 +73,16 @@ reference:
   - get_logger_meta_variables
   - log_namespaces
   - log_indices
+
+articles:
+- title: For users
+  navbar: ~
+  contents:
+  - customize_logger
+  - migration
+  - performance
+- title: For developers
+  navbar: For developers
+  contents:
+  - r_packages
+  - write_custom_extensions

vignettes/customize_logger.Rmd

@@ -27,7 +27,77 @@ library(logger)
 log_appender(appender_stdout)
 ```
 
-In this vignette I suppose that you are already familiar with [The Anatomy of a Log Request](https://daroczig.github.io/logger/articles/anatomy.html) vignette.
+## Anatomy of a request
+
+```{r loggerStructureImage, echo=FALSE, out.extra='style="width: 100%;" title="The structure of a logger and the flow of a log record request" alt="The structure of a logger and the flow of a log record request"'}
+knitr::include_graphics("logger_structure.svg")
+```
+
+To make a successful log record, `logger` requires the below components:
+
+- a **log request**, eg
+
+    ```r
+    log_error('Oops')
+    ```
+
+    - including the log level (importance) of the record, which will be later used to decide if the log record is to be delivered or not: `ERROR` in this case
+    - R objects to be logged: a simple string in this case, although it could be a character vector or any R object(s) that can be converted into a character vector by the `formatter` function
+
+- the **environment** and meta-information of the log request, eg actual timestamp, hostname of the computer, the name of the user running the R script, the pid of the R process, calling function and the actual call etc.
+
+
+    ```{r}
+f <- function() get_logger_meta_variables(log_level = INFO)
+f()
+    ```
+
+- a **logger definition** to process the log request, including
+
+      - log level `threshold`, eg `INFO`, which defines the minimum log level required for actual logging -- all log requests with lower log level will be thrown away
+
+      ```{r}
+      log_threshold()
+      ERROR <= INFO
+      log_error("Oops")
+      ```
+
+      - `formatter` function, which takes R objects and converts those into actual log message(s) to be then passed to the `layout` function for the log record rendering -- such as `paste`, `sprintf`, `glue` or eg the below custom example:
+
+
+      ```{r}
+      formatter <- function(...) paste(..., collapse = " ", sep = " ")
+      formatter(1:3, c("foo", "bar"))
+      ```
+
+     - `layout` function, which takes log message(s) and further information on the log request (such as timestamp, hostname, username, calling function etc) to render the actual log records eg human-readable text, JSON etc
+
+      ```r
+      library(jsonlite)
+      layout <- function(level, msg) toJSON(level = level, timestamp = time, hostname = node, message = msg)
+      layout(INFO, 'Happy Thursday!')
+      #> {'level': 'INFO', 'timestamp': '1970-01-01 00:00:00', 'hostname': 'foobar', 'message': 'Happy Thursday!'}
+      ```
+
+      - `appender` function, which takes fully-rendered log record(s) and delivers to somewhere, eg `stdout`, a file or a streaming service, eg
+
+      ```{r}
+      appender <- function(line) cat(line, "\n")
+      appender("INFO [now] I am a log message")
+      ```
+
+Putting all these together (by explicitly setting the default config in the `global` namespace):
+
+```{r}
+log_threshold(INFO)
+log_formatter(formatter_glue)
+log_layout(layout_simple)
+log_appender(appender_stdout)
+log_debug("I am a low level log message that will not be printed with a high log level threshold")
+log_warn("I am a higher level log message that is very likely to be printed")
+```
+
+Note, that all `logger` definitions and requests are tied to a logging namespace, and one log request might trigger multiple `logger` definitions as well (stacking). Find more information on these in the `vignette("customize_logger")`.
 
 ## What gets logged?
 
@@ -114,7 +184,7 @@ log_info("There are {nrow(mtcars)} cars in the mtcars dataset")
 log_info("2 + 2 = {2+2}")
 ```
 
-If you don't like this syntax, or want to save a dependency, you can use other formatter functions as well, such as `?formatter_sprintf` (being the default in eg the [`logging` and `futile.logger` packages](https://daroczig.github.io/logger/articles/migration.html)) or `?formatter_paste`, or [write your own formatter function](https://daroczig.github.io/logger/articles/write_custom_extensions.html) converting R objects into string.
+If you don't like this syntax, or want to save a dependency, you can use other formatter functions as well, such as `formatter_sprintf()` (the default in eg the `logging` and `futile.logger` packages, which you can learn more about in `vignette("migration.html")`)  or `formatter_paste()`, or you can write your own, as described in `vignette("write_custom_extensions.html")`.
 
 ## Log message layouts
 
@@ -222,7 +292,7 @@ mclapply(split(runif(100), 1:10), f, mc.cores = 5)
 log_layout()
 ```
 
-For more details on this, see the [Writing custom logger extensions](https://daroczig.github.io/logger/articles/write_custom_extensions.html) vignette.
+For more details on this, see `vignette("write_custom_extensions.html")`.
 
 ```{r}
 ## reset layout
@@ -271,7 +341,7 @@ You may find `?appender_tee` also useful, that writes the log messages to both `
 log_appender(appender_stdout)
 ```
 
-And the are many other appender functions bundled with `logger` as well, eg some writing to Syslog, Telegram, Pushbullet, a database table or an Amazon Kinesis stream -- even doing that asynchronously via `appender_async` -- see [Simple Benchmarks on Performance](https://daroczig.github.io/logger/articles/performance.html) for more details.
+And the are many other appender functions bundled with `logger` as well, eg some writing to Syslog, Telegram, Pushbullet, a database table or an Amazon Kinesis stream -- even doing that asynchronously via `appender_async` -- see `vignette("performance")` for more details.
 
 ## Stacking loggers
 

vignettes/Intro.Rmd → vignettes/logger.Rmd

@@ -86,7 +86,7 @@ pander::panderOptions("knitr.auto.asis", ppo1)
 pander::panderOptions("table.style", ppo2)
 ```
 
-For more details, check the [function reference in the manual](https://daroczig.github.io/logger/reference/index.html), or start with the [The Anatomy of a Log Request](https://daroczig.github.io/logger/articles/anatomy.html) and [Customizing the Format and the Destination of a Log Record](https://daroczig.github.io/logger/articles/customize_logger.html) vignettes.
+For more details, check the [function reference in the manual](https://daroczig.github.io/logger/reference/index.html) or `vignette("customize_logger")`.
 
 ```{r cleanup, include = FALSE}
 logger:::namespaces_reset()

vignettes/migration.Rmd

@@ -42,7 +42,7 @@ library(logger)
 log_appender(appender_stdout)
 ```
 
-In this vignette I suppose that you are already familiar with at least one of the [similar logging R packages](https://daroczig.github.io/logger/index.html#why-another-logging-r-package) and you are looking for suggestions on how to switch to `logger`. Before moving forward, please make sure that you have read the [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) and [Customizing the Format and the Destination of a Log Record](https://daroczig.github.io/logger/articles/customize_logger.html) vignettes for a decent background on `logger`, and use this vignette as a quick-reference sheet to help you migrate from another package.
+This vignette provides a quick reference guide to switching to logger from the futile.logger, logging, log4r, and loggit packages. I assume that you're already familiar with the basics of logger by reading `vignette("logger")` and `vignette("customize_logger")`.
 
 ## futile.logger
 
@@ -168,7 +168,7 @@ log_appender(appender_stdout)
 
 ### Hierarchical logging and performance
 
-Both packages support using different logging namespaces and stacking loggers within the same namespace. Performance-wise, there's `logger` seems to be faster than `futile.logger`, but for more details, check the [Simple Benchmarks on Performance](https://daroczig.github.io/logger/articles/performance.html) vignette.
+Both packages support using different logging namespaces and stacking loggers within the same namespace. Performance-wise, there's `logger` seems to be faster than `futile.logger`, but for more details, check `vignette("performance")`.
 
 ### Using `logger` as a drop-in-replacement of `futile.logger`
 
@@ -255,7 +255,7 @@ str(levels[order(-as.numeric(levels))], give.attr = FALSE)
 
 ### Performance
 
-Performance-wise, there's no big difference between the two packages, but for more details, check the [Simple Benchmarks on Performance](https://daroczig.github.io/logger/articles/performance.html) vignette.
+Performance-wise, there's no big difference between the two packages, but for more details, check `vignette("performance")`.
 
 ### Log record layout
 
@@ -272,7 +272,7 @@ log_layout()
 ```
 </div>
 
-`logger` provides multiple configurable layouts to fit the user's need, eg easily show the calling function of the lof request, the `pid` of the R process, name of the machine etc. or colorized outputs. See [Customizing the Format and the Destination of a Log Record](https://daroczig.github.io/logger/articles/customize_logger.html) vignette for more details.
+`logger` provides multiple configurable layouts to fit the user's need, eg easily show the calling function of the lof request, the `pid` of the R process, name of the machine etc. or colorized outputs. See `vignette("customize_logger")`for more details.
 
 ### Log message formatting