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.