-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* mnt: Reduction of te readme * mnt: Reduction of te readme II * mnt: More precise reasons to use * mnt: Reduction of Description in DESCRIPTION * mnt: Vignette formatting * mnt: Vignette w/o redundant JSON doc * fix: Badge name * mnt: Add acknowledgments * mnt: container environments
- Loading branch information
Showing
4 changed files
with
145 additions
and
245 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,120 +14,94 @@ knitr::opts_chunk$set( | |
| collapse = TRUE, | ||
| comment = "#>" | ||
| ) | ||
| options(width = 150) | ||
| ``` | ||
|
|
||
| Modern Logging for the R Ecosystem | ||
| Easy-to-use, dependencyless Logger for R | ||
| ================================== | ||
| Ryan Price <[email protected]> | ||
|
|
||
| <!-- badges: start --> | ||
| [](https://cran.r-project.org/package=loggit) | ||
| [](https://cran.r-project.org/package=loggit) | ||
| [](https://cran.r-project.org/package=loggit) | ||
| [](https://github.com/MEO265/loggit_private/actions/workflows/R-CMD-check.yaml) | ||
| [](https://codecov.io/gh/MEO265/loggit_private) | ||
| <!-- badges: end --> | ||
|
|
||
| ------------------------------------------------------------------------ | ||
|
|
||
| `loggit` is an [`ndJSON`](https://github.com/ndjson/ndjson-spec) logging library | ||
| for R software. It is blazingly fast when writing logs, and has _zero_ external | ||
| dependencies. `loggit` can be as simple and unobstrusive as you'd like, or as | ||
| involved as your application needs it to be. | ||
| `loggit` is an easy-to-use [`ndJSON`](https://github.com/ndjson/ndjson-spec) logging library for R software, | ||
| with _zero_ external dependencies. | ||
|
|
||
| Please see below for some quick examples, and [read the | ||
| vignettes](https://cran.r-project.org/web/packages/loggit/vignettes/) for the | ||
| Getting Started guide, as well as some other use case examples. | ||
| Please see below for some quick examples, and read the [vignettes](https://cran.r-project.org/web/packages/loggit/vignettes/) for the | ||
| Getting Started guide. | ||
|
|
||
| Why use `loggit`? | ||
| ----------------- | ||
|
|
||
| There are indeed several logging packages available for R. `loggit`, however, | ||
| takes a more modern approach approach to logging in R: | ||
| `loggit` takes a modern approach to logging in R: | ||
|
|
||
| - Opting to use the JSON format, which is parsable by most modern software | ||
| - Designed with log streams in mind | ||
| - Unobtrusive, yet highly flexible | ||
| - Convenient ability to log data, then analyze that log data on the same host. | ||
| - Opting to use the JSON format | ||
| - Highly flexible log streams | ||
| - Enables log data analysis on the same host | ||
| - _Zero_ external dependencies | ||
|
|
||
| Additionally, the boilerplate to get going with `loggit` is minimal at worst, | ||
| only requiring you to point to the log file. If deploying your R code in a | ||
| container ecosystem, you don't even need to do that, since `loggit` will | ||
| echo its formatted logs to `stdout`. No need to write custom formatters, | ||
| handlers, levels, etc. -- ***just f&ck#n' loggit!*** | ||
| Additionally, the boilerplate to get going with `loggit` is minimal at worst. | ||
| No need to write custom formatters, handlers, levels, etc. -- ***just loggit!*** | ||
|
|
||
| Quick Examples | ||
| Usage | ||
| -------------- | ||
|
|
||
| The quickest way to get up & running with `loggit` is to... do nothing special. | ||
| `loggit`'s simplest functionality does its best to stay out of your way. You'll | ||
| probably want to point it to a log file, though; otherwise, logs will print to | ||
| the console, but land in a tempfile. | ||
| The quickest way to get up & running with `loggit` is to do nearly nothing. | ||
|
|
||
| ```{r handlers} | ||
| library(loggit) | ||
| # set_logfile("./loggit.log") | ||
| message("This is a message") | ||
| warning("This is a warning") | ||
| # stop("This actually throws a critical error, so I'm not actually going to run it here :)")) | ||
| #> {"timestamp": "2020-05-31T20:59:33-0500", "log_lvl": "ERROR", "log_msg": "This actually throws a critical error, so I'm not actually going to run it here :)"} | ||
| `loggit` provides a set of wrappings for base R's `message()`, `warning()`, and | ||
| `stop()` functions that maintain identical functionality, making it sufficient to | ||
| import the `loggit` namespace, for example by using `library("loggit")`, or by | ||
| prefixing `loggit::` at the desired locations. | ||
|
|
||
| ```{r, error = TRUE} | ||
| loggit::message("This is a message") | ||
| loggit::warning("This is a warning") | ||
| loggit::stop("This is an error") | ||
| ``` | ||
|
|
||
| You can suppress each part of the console output separately (both the `loggit` | ||
| ndJSON and the regular R output) but the default is to post both. Only the | ||
| ndJSON is written to the log file. | ||
| You can suppress the additional console output by using `echo = FALSE` and | ||
| you won't notice any difference to the base functions (except that the log | ||
| will be filled in the background). | ||
|
|
||
| ```{r, error = TRUE} | ||
| loggit::message("This is another message", echo = FALSE) | ||
| loggit::warning("This is another warning", echo = FALSE) | ||
| loggit::stop("This is another error", echo = FALSE) | ||
| ``` | ||
|
|
||
| You can also use the `loggit()` function directly to compose much more custom | ||
| logs, including ***entirely custom fields*** (and prevent throwing actual status | ||
| codes until you wish to handle them). `loggit` doesn't require that you set | ||
| custom logger objects or anything like that: just throw whatever you want at it, | ||
| and it'll become a structured log. | ||
| You can also use `loggit()` directly to compose much more custom | ||
| logs, including ***entirely custom fields*** (and prevent throwing actual conditions). | ||
| `loggit` doesn't require that you set custom logger objects or anything like that: | ||
| just throw whatever you want at it, and it'll become a structured log. | ||
|
|
||
| ```{r loggit} | ||
| loggit("ERROR", "This will log an error - but not actually throw one yet", rows = nrow(iris), anything_else = "you want to include") | ||
| loggit::loggit("ERROR", "This will log an error", anything_else = "you want to include") | ||
| # Read log file into data frame to implement logic based on entries | ||
| logdata <- read_logs() | ||
| print(logdata) | ||
| if (any(logdata$log_lvl == "ERROR")) { | ||
| print("Errors detected somewhere in your code!") # but you can throw a stop() here, too, for example | ||
| } | ||
| loggit::read_logs() | ||
| ``` | ||
|
|
||
| Again, [check out the | ||
| vignettes](https://cran.r-project.org/web/packages/loggit/vignettes/) for more | ||
| details! | ||
| Check out the [vignettes](https://cran.r-project.org/web/packages/loggit/vignettes/) for more details. | ||
|
|
||
| Installation | ||
| ------------ | ||
|
|
||
| You can install the latest CRAN release of `loggit` via | ||
| `install.packages("loggit")`. | ||
|
|
||
| Or, to get the latest development version from GitHub -- | ||
| install.packages("loggit") | ||
|
|
||
| Via [devtools](https://github.com/hadley/devtools): | ||
| or, get the latest development version from GitHub via | ||
|
|
||
| devtools::install_github("ryapric/loggit") | ||
|
|
||
| Or, clone & build from source: | ||
|
|
||
| cd /path/to/your/repos | ||
| git clone https://github.com/ryapric/loggit.git loggit | ||
| make install | ||
|
|
||
| To use the most recent development version of `loggit` in your own package, you | ||
| can include it in your `Remotes:` field in your DESCRIPTION file: | ||
|
|
||
| Remotes: github::ryapric/loggit | ||
|
|
||
| Note that packages being submitted to CRAN *cannot* have a `Remotes` field. | ||
| Refer | ||
| [here](https://cran.r-project.org/web/packages/devtools/vignettes/dependencies.html) | ||
| for more info. | ||
|
|
||
| License | ||
| ------- | ||
| Acknowledgments | ||
| ----------- | ||
| This package is based on the [eponymous package by Ryan Price](https://github.com/ryapric/loggit), specifically version 2.1.1. | ||
|
|
||
| MIT | ||
| Due to technical reasons, this repository is not a GitHub fork of [Ryan's repository](https://github.com/ryapric/loggit). | ||
Oops, something went wrong.