This is a small bugfix release for CRAN’s sake that fixes two tests that would sporadically fail; they relied on timestamps being equivalent between want and got invocations.
Add sanitizer argument to loggit(), and an unsanitizer argument to read_logs(). loggit chooses to reimplement basic JSON parsing funcitonality instead of requiring a more full-featured external JSON library like jsonlite. This reimplementation is string-pattern-based, and not based on a more formal specification of JSON using an AST. As such, it isn’t brittle, per se, but it is weak to invalid JSON characters such as embedded newlines, curly braces, double-quotes, some occurrences of commas or colons, and the like.
Sanitizers are functions allow for custom replacements of invalid (nd)JSON characters in the submitted log data. Unsanitizer functions perform the opposite action: replacing sanitized output with their original values when read back inttohe R session. If not provided, loggit() and read_logs() will invoke the default sanitizer table, which (currently) maps string replacements as follows:
| Character | Replacement in log file |
|---|---|
{ |
__LEFTBRACE__ |
} |
__RIGHTBRACE__ |
" |
__DBLQUOTE__ |
, |
__COMMA__ |
\r |
__CR__ |
\n |
__LF__ |
Users may specify their own (un)sanitizers as functions that take & return single strings, though they are regardless encouraged to not include invalid characters in the logs in the first place. Please refer to the documentation for more details.
Removed log_format from read_ndjson(), because that was silly.
Removed some erroneous functions as exports in the NAMESPACE.
Change behavior of handler masks to respect multiple arguments. Achieved by changing explicit list indexing to paste(..., collapse = "") (#12).
Remove loggit::stopifnot tests, since stopifnot() is not provided as a handler mask by this package (stopifnot() has no custom messaging mechanic to log).
loggit() now logs explicitly to ndjson-formatted log files. This is handled internally by the write_ndjson() function. Each log entry is self-contained on its own line, as its own JSON object. Previously, the log files were each a single JSON array, with JSON objects as the elements. This change provides several benefits over the old way of logging.
Please note that this change means that log entries should not contain any embedded newline characters (\r, \n, or \r\n), as this will break the logging format of the file. Your logs will still be written (with a base::warning), but parsing the data with external tools or the included read_logs() function may not behave correctly. loggit could one day enforce these content rules internally, but the decision for now is to stay out of the way of the user code generating the logs, and put the onus of correction on the developer.
Note that despite the significant backend behavioral changes presented here, the user-facing API for this package has changed very little (documented below).
Remove dplyr and jsonlite from Imports. This makes loggit entirely free from external dependencies.
Added rotate_logs(), which rotates the log file on disk based on its line count. This is not an automated process, as depending on the size of your log file, this could cause performance degradation if called on every nth write. See function docs for more details.
Added two vignettes: Getting Started, and Data Validation.
get_logs() was renamed to read_logs().
Removed log_detail as an explicit argument to loggit(). This is a non-breaking change, since loggit() will still pick up and log that field if provided, but it is no longer a formal argument.
loggit() no longer complains that a persistent log file is not set, and instead relies on the user to take note of the logfile’s location in the assigned tempdir. This can be avoided entirely by setting the log file explicitly at runtime, as has always been the case.
All configuration set and get functions are all now in snake-case, e.g. set_logfile() instead of setLogFile().
set_timestamp_format() now defaults to ISO-8601 time format, i.e. YYYY-MM-DDTHH:MM:SS+z. The function itself still provides no means to set a timezone, and this is deliberate. This ensures that all software on the host reports identical timezone data by default.
Removed package startup message; the previous message would have broken formatting consistency if capturing logs via stdout/stderr.
Automatically coerce any entries for ‘log_lvl’ and ‘log_msg’ fields to be character.
(Github-only): loggit() no longer allows for a data frame to be passed as an argument; the underlying code was not writen very well, and I got ahead of myself in throwing it in there. loggit() is, however, still vectorized by nature, so users can still pass vectors to, for example, the log_detail argument, and values will be recycled according to R’s usual recycling rules.
Add get_logs(), which returns a data frame of a provided log file. Returns the current log file by default.
(Github-only): loggit() now allows for a data frame to be passed as the sole argument, and have its results be logged. Required column names are the same as the first two arguments to loggit(): “log_lvl” and “log_msg”. Any additional number of columns can be supplied.