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):
lg <- readLines("test.log") invisible(file.remove("test.log")) for(i in seq_along(lg)) cat(lg[i], "\n")
By 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.)
lg <- readLines("test.log") invisible(file.remove("test.log")) for(i in seq_along(lg)) cat(lg[i], "\n")
By 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
lg <- readLines("test.log") invisible(file.remove("test.log")) for(i in seq_along(lg)) cat(lg[i], "\n")
Notice 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)
lg <- readLines("test.log") invisible(file.remove("test.log")) for(i in seq_along(lg)) cat(lg[i], "\n")
So far, only messages sent via printlog()
appear in the log. We might, however, want to capture everything^[Almost. Messages, warnings, and errors will not appear; but see ?sink
and its type = "message"
parameter.] produced by a script. To do this, use the sink = TRUE
option of openlog()
.
If an error occurs in your script, any log files will by default remain open. If using a single log file, it's easy to put a statement such as suppressWarnings(closelog())
at the start of your script. Alternatively, you can tell luzlogr to close all open logs if an error occurs:
options(luzlogr.close_on_error = TRUE)
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)
invisible(file.remove("test.log.gz"))
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.