This vignette describes how to use the luzlogr package, which provides flexible but lightweight logging facilities for R scripts.
To install this package, use R’s install.packages() function, or the “Packages” pane in RStudio. To install the latest, developmental version of this package from GitHub:
devtools package installed from CRAN and loaded.install_github("bpbond/luzlogr")Three functions - openlog(), printlog(), closelog() - provide logging of script output. They’re simple to use:
library(luzlogr)
openlog("test.log")
printlog("message")
closelog()The resulting log file test.log looks like this (not including the initial ## characters):
## Thu Feb 25 11:52:58 2016 Opening test.log
## Thu Feb 25 11:52:58 2016 message
## Thu Feb 25 11:52:58 2016 Closing test.log flags = 0
## -------
## R version 3.2.3 (2015-12-10)
## Platform: x86_64-apple-darwin13.4.0 (64-bit)
## Running under: OS X 10.11.3 (El Capitan)
##
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] luzlogr_0.2.0
##
## loaded via a namespace (and not attached):
## [1] assertthat_0.1 magrittr_1.5 formatR_1.2.1 htmltools_0.3
## [5] tools_3.2.3 yaml_2.1.13 stringi_1.0-1 rmarkdown_0.9.2
## [9] knitr_1.12.3 stringr_1.0.0 digest_0.6.9 evaluate_0.8By default individual lines are prefixed with a timestamp, end with a carriage return, and the entire log starts with an open message and ends with a close one.
Any printable object can be written to a log. For example:
openlog("test.log")
printlog("message", 1, 2)
printlog(head(cars))
closelog(sessionInfo = FALSE)(Notice in this case we’ve told closelog() not to append sessionInfo() output, as it does by default.)
## Thu Feb 25 11:52:58 2016 Opening test.log
## Thu Feb 25 11:52:58 2016 message 1 2
## Thu Feb 25 11:52:58 2016
## speed dist
## 1 4 2
## 2 4 10
## 3 7 4
## 4 7 22
## 5 8 16
## 6 9 10
##
## Thu Feb 25 11:52:58 2016 Closing test.log flags = 0By design, luzlogr is intended to be simple and easy to use. Nonetheless, it does provide additional features, including:
In many circumstances, we want messages to have different priorities or levels associated with them. Each logfiles has a minimum priority level, set when it’s opened, making it easy to produce logs with varying levels of detail–for example, under development versus release conditions.
By default, luzlogr logs have a minimum levels of -Inf: in other words, they’ll accept every single message sent to them via printlog(), which produces messages with a default level of zero. We can change the log’s level, however, and this will then affect which messages appear in the log.
openlog("test.log", loglevel = 0)
printlog("This message will appear", level = 0)
printlog("So will this (level 0 by default)")
printlog("This will not", level = -1)
closelog(sessionInfo = FALSE)produces
## Thu Feb 25 11:52:58 2016 Opening test.log
## Thu Feb 25 11:52:58 2016 This message will appear
## Thu Feb 25 11:52:58 2016 So will this (level 0 by default)
## Thu Feb 25 11:52:58 2016 Closing test.log flags = 0Notice that the third message didn’t get logged. If we change the loglevel parameter in openlog() to -1 or lower, however, all these messages will appear.
Another way to differentiate messages is by flagging them. Note that in all the above examples, when the log is closed, a flags = 0 message is printed. But we can change that:
openlog("test.log")
printlog("A normal message")
printlog("A flagged message!", flag = TRUE)
flaglog("Another")
closelog(sessionInfo = FALSE)## Thu Feb 25 11:52:58 2016 Opening test.log
## Thu Feb 25 11:52:58 2016 A normal message
## ** Flagged message: **
## Thu Feb 25 11:52:58 2016 A flagged message!
## ** Flagged message: **
## Thu Feb 25 11:52:58 2016 Another
## Thu Feb 25 11:52:58 2016 Closing test.log flags = 2So far, only messages sent via printlog() appear in the log. We might, however, want to capture everything1 produced by a script. To do this, use the sink = TRUE option of openlog().
Logs can also be sent to any R connection: a pipe, compressed file, URL, etc.
con <- gzfile("test.log.gz")
openlog(con)
printlog("Sending to a compressed logfile")
closelog(sessionInfo = FALSE)Note that luzlogr won’t close a connection that was already open at the time of the openlog() call.
If you’re logging to log A and open log B (without closing A), subsequent printlog() messages will go to B. When you close B, logging switches back to A (i.e., there’s a stack of logs that gets pushed/popped when necessary).
If you need to append to an existing log, use append = TRUE when calling openlog(). By default, existing logfiles are erased upon opening.
This concludes the Introduction to luzlogr vignette.
Almost. Messages, warnings, and errors will not appear; but see ?sink and its type = "message" parameter.↩