knitr::opts_chunk$set( #nolint collapse = TRUE, comment = "#>" ) old <- options(width = 200L)
loggit2
can be used immediately and fully without configuration after installation. However, to fully utilize the potential of loggit2
, some configurations can be made.
loggit2
uses a three-tier configuration system:
The first tier is the Meta or System-wide Configuration. It is defined by environment variables that are read by loggit2
when the package is loaded. These settings then serve as default values for the session-wide configuration.
The second tier is the Global or Session-wide Configuration. It is defined by the set_*()
functions of loggit2
.
The third tier is the Local or Function-specific Configuration, implemented through the arguments of the functions. For a quick overview of the functions, refer to the Getting Started Vignette.
Each time a function of loggit2
is called, the settings from the three tiers are combined. A higher tier/specificity configuration always takes precedence over a lower tier/specificity configuration.
The configuration options of loggit2
are described below. For details, refer to the function documentation.
The log file can be set either via the environment variable FILE_LOGGIT2
, the function set_log_file()
, or the logfile
argument of the logging functions loggit()
and with_loggit()
. The wrappers of the base R condition handler always use the session-wide configuration.
setwd(tempdir()) old_log <- loggit2::set_logfile(logfile = "logfile.log") loggit2::loggit( log_lvl = "DEBUG", log_msg = "This message will be logged to `logfile.log`." ) loggit2::loggit( log_lvl = "DEBUG", log_msg = "This message will be logged to `otherlogfile.log`.", logfile = "otherlogfile.log" ) loggit2::with_loggit(logfile = "logfile2.log", { base::message("This message will be logged to `logfile2.log`.") }) loggit2::set_logfile(old_log)
The log level can be set either via the environment variable LEVEL_LOGGIT2
or the function set_log_level()
. The .loggit
argument can also be passed to the wrappers of the base R condition handler to enforce logging (TRUE
) or suppress it (FALSE
). The logging function loggit()
can enforce logging through the ignore_log_level
argument. with_loggit()
allows setting a log level for the code block being executed.
old_log_lvl <- loggit2::set_log_level("INFO") loggit2::message("This message will be logged, since the log level is INFO.") loggit2::loggit( log_lvl = "DEBUG", log_msg = "This message will not be logged, since the log level is INFO." ) loggit2::loggit( log_lvl = "DEBUG", "This message will be logged because the log level is ignored.", ignore_log_level = TRUE ) loggit2::warning( "This warning message will not be logged, since .loggit = FALSE.", .loggit = FALSE ) loggit2::set_log_level("ERROR") loggit2::warning("This warning will not be logged, since the log level is set to ERROR.") loggit2::message("This message will be logged, since .loggit = TRUE.", .loggit = TRUE) loggit2::stop("This error message will be logged because the log level is set to ERROR.") loggit2::with_loggit(log_level = "DEBUG", { base::message("This message will be logged because the log level is set to DEBUG.") }) loggit2::set_log_level(old_log_lvl)
Whether log messages should also be output to stdout
can be controlled via the environment variable ECHO_LOGGIT2
or the function set_echo()
. Additionally, all logging functions and wrappers of the base R condition handler allow direct control via the echo
argument.
old_echo <- loggit2::set_echo(FALSE) loggit2::message("This message will not be logged, but it will be output to the console.") loggit2::message("This message will be logged and output to the console.", echo = TRUE) loggit2::set_echo(TRUE, confirm = FALSE) loggit2::message("This message will be logged and output to the console.") loggit2::message("This message will be logged, but it will not be echoed.", echo = FALSE) loggit2::with_loggit(echo = FALSE, { base::message("This message will be logged, but it will not be output to the console.") }) loggit2::set_echo(old_echo)
The format of the timestamp can be controlled via the environment variable TIMESTAMP_LOGGIT2
or the function set_timestamp_format()
.
old_ts <- loggit2::set_timestamp_format("%H:%M:%S") loggit2::message("This message will be logged with a timestamp in the format HH:MM:SS.") loggit2::set_timestamp_format(old_ts)
Depending on the use case, it may be useful to change temporary configurations, e.g., to log to a different file in a specific code block or to log a particular part of the code with more details (higher log level).
One way is to manually set and reset the configurations (e.g., by using on.exit()
), but this is cumbersome and error-prone.
An alternative is to use with_loggit()
. As mentioned above, almost all configurations can be adjusted directly in with_loggit()
.
[^1]: Note: "Session-wide" means that (unless locally configured otherwise) calls to loggit2
functions in other packages will use the same settings. Consider this when using loggit2
in a package that will be used elsewhere.
options(old)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.