log_open: Open a log
In logr: Creates Log Files

log_open

R Documentation

Open a log

Description

A function to initialize the log file.

Usage

log_open(
  file_name = "",
  logdir = TRUE,
  show_notes = TRUE,
  autolog = NULL,
  compact = FALSE,
  traceback = TRUE
)

Arguments

`file_name`	The name of the log file. If no path is specified, the working directory will be used. As of v1.2.7, the name and path of the program or script will be used as a default if the `file_name` parameter is not supplied.
`logdir`	Send the log to a log directory named "log". If the log directory does not exist, the function will create it. Valid values are TRUE and FALSE. The default is TRUE.
`show_notes`	If true, will write notes to the log. Valid values are TRUE and FALSE. Default is TRUE.
`autolog`	Whether to turn on autolog functionality. Autolog automatically logs functions from the dplyr, tidyr, and sassy family of packages. To enable autolog, either set this parameter to TRUE or set the "logr.autolog" option to TRUE. A FALSE value on this parameter will override the global option. The global option will override a NULL on this parameter. Default is that autolog is disabled.
`compact`	When the compact option is TRUE, logr will minimize the number of blank spaces in the log. This option generates the same logging information, but in less space. The "logr.compact" global option does the same thing.
`traceback`	By default, if there is an error in the program being logged, logr will print a traceback of the error. You may turn this feature off by setting the `traceback` parameter to FALSE.

Details

The log_open function initializes and opens the log file. This function must be called first, before any logging can occur. The function determines the log path, attaches event handlers, clears existing log files, and initiates a new log.

The file_name parameter may be a full path, a relative path, or a file name. An relative path or file name will be assumed to be relative to the current working directory. If the file_name does not have a '.log' extension, the log_open function will add it.

As of v1.2.7, if the file_name parameter is not supplied, the function will use the program/script name as the default log file name, and the program/script path as the default path.

If requested in the logdir parameter, the log_open function will write to a 'log' subdirectory of the path specified in the file_name. If the 'log' subdirectory does not exist, the function will create it.

The log file will be initialized with a header that shows the log file name, the current working directory, the current user, and a timestamp of when the log_open function was called.

All errors, the last warning, and any log_print output will be written to the log. The log file will exist in the location specified in the file_name parameter, and will normally have a '.log' extension.

If errors or warnings are generated, a second file will be written that contains only error and warning messages. This second file will have a '.msg' extension and will exist in the specified log directory. If the log is clean, the msg file will not be created. The purpose of the msg file is to give the user a visual indicator from the file system that an error or warning occurred. This indicator msg file is useful when running programs in batch.

To use logr, call log_open, and then make calls to log_print as needed to print variables or data frames to the log. The log_print function can be used in place of a standard print function. Anything printed with log_print will be printed to the log, and to the console if working interactively.

This package provides the functionality of sink, but in much more user-friendly way. Recommended usage is to call log_open at the top of the script, call log_print as needed to log interim state, and call log_close at the bottom of the script.

Logging may be controlled globally using the "logr.on" option. This option accepts a TRUE or FALSE value. If the option is set to FALSE, logr will print to the console, but not to the log. Example: options("logr.on" = TRUE)

Notes may be controlled globally using the "logr.notes" option. This option also accepts a TRUE or FALSE value, and determines whether or not to print notes in the log. The global option will override the show_notes parameter on the log_open function. Example: options("logr.notes" = FALSE)

Version v1.2.0 of the logr package introduced autolog. The autolog feature provides automatic logging for dplyr, tidyr, and the sassy family of packages. To use autolog, set the autolog parameter to TRUE, or set the global option logr.autolog to TRUE. To maintain backward compatibility with prior versions, autolog is disabled by default.

The "compact" parameter will remove all the blank lines between log entries. The downside of a compact log is that it makes the log harder to read. The benefit is that it will take up less space. The global option "logr.compact" will achieve the same result.

If an error is encountered, a traceback of the error message is printed to the log and message files by default. This traceback helps in finding the source of the error, particularly in situations where you have deeply nested functions. If you wish to turn the traceback off, set the traceback parameter of the log_open function to FALSE. You may also use the global option logr.traceback to control printing of this information.

Value

The path of the log.

Examples

# Create temp file location
tmp <- file.path(tempdir(), "test.log")

# Open log
lf <- log_open(tmp)

# Send message to log
log_print("High Mileage Cars Subset")

# Perform operations
hmc <- subset(mtcars, mtcars$mpg > 20)

# Print data to log
log_print(hmc)

# Close log
log_close()

# View results
writeLines(readLines(lf))

logr documentation built on Nov. 10, 2023, 1:07 a.m.