{"id":13398934,"url":"https://github.com/s-fleck/lgr","last_synced_at":"2025-04-12T19:44:28.237Z","repository":{"id":34221303,"uuid":"154803571","full_name":"s-fleck/lgr","owner":"s-fleck","description":"A fully featured logging framework for R","archived":false,"fork":false,"pushed_at":"2025-04-08T06:13:15.000Z","size":5587,"stargazers_count":80,"open_issues_count":17,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-10T19:35:24.673Z","etag":null,"topics":["log4j","logging","r","r6"],"latest_commit_sha":null,"homepage":"https://s-fleck.github.io/lgr/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s-fleck.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-26T08:39:18.000Z","updated_at":"2025-04-08T06:09:28.000Z","dependencies_parsed_at":"2024-06-19T05:25:22.153Z","dependency_job_id":"51bb1679-5973-48de-a079-c83b0b26473b","html_url":"https://github.com/s-fleck/lgr","commit_stats":{"total_commits":780,"total_committers":7,"mean_commits":"111.42857142857143","dds":0.4012820512820513,"last_synced_commit":"cd21d695008e9adc0061c2e4eb44174388d364ce"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-fleck%2Flgr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-fleck%2Flgr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-fleck%2Flgr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s-fleck%2Flgr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s-fleck","download_url":"https://codeload.github.com/s-fleck/lgr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625479,"owners_count":21135512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["log4j","logging","r","r6"],"created_at":"2024-07-30T19:00:32.828Z","updated_at":"2025-04-12T19:44:28.208Z","avatar_url":"https://github.com/s-fleck.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n\nlibrary(lgr)\nbasic_config(console_connection = stdout())  # ensure default config\n# \u003cimg src=\"man/figures/lgr-logo-plain.svg\" align=\"right\" width=160 height=160/\u003e\n```\n# lgr\n\n[![CRAN status](https://www.r-pkg.org/badges/version/lgr)](https://cran.r-project.org/package=lgr)\n[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)\n\nlgr is a logging package for R built on the back of \n[R6](https://github.com/r-lib/R6) classes. It is designed to be flexible,\nperformant and extensible. The package \n[vignette](https://s-fleck.github.io/lgr/articles/lgr.html) contains a \ncomprehensive description of the features of lgr (some of them unique among\nR logging packages) along with many code examples.\n\nUsers that have not worked with R6 classes before, will find configuring\nLoggers a bit strange and verbose, but care was taken to keep\nthe syntax for common logging tasks and interactive usage simple and concise.\nUser that have experience with \n  [shiny](https://github.com/rstudio/shiny), \n  [plumber](https://github.com/rstudio/plumber),\n  [python logging](https://docs.python.org/3/library/logging.html) or \n  [Apache Log4j](https://logging.apache.org/log4j/2.x/) will feel\nat home. User that are proficient with R6 classes will also find it easy\nto extend and customize lgr, for example with their own appenders Loggers or \nAppenders. \n\n\n\n## Features\n\n* *Hierarchical loggers* like in log4j and python logging. This is useful if you\n  want to be able to configure logging on a per-package basis.\n* An *arbitrary number of appenders* for each logger. A single logger can write\n  to the console, a logfile, a database, etc... .\n* Support for structured logging. As opposed to many other logging \n  packages for R a log event is not just a message with a timestamp, but an\n  object that can contain arbitrary data fields. This is useful for producing \n  machine readable logs.\n* *Vectorized* logging (so `lgr$fatal(capture.output(iris))` works)\n* Lightning fast *in-memory logs* for interactive use.\n* Appenders that write logs to a wide range of destinations:\n    * databases (buffered or directly)\n    * email or pushbullet\n    * plaintext files (with a powerful formatting syntax)\n    * JSON files with arbitrary data fields\n    * Rotating files that are reset and backed-up after they reach\n      a certain file size or age\n    * memory buffers\n    * (colored) console output\n* Optional support to use [glue](https://glue.tidyverse.org/) instead of \n  `sprintf()` for composing log messages.\n\n\n## Usage\n\nTo log an *event* with with lgr we call `lgr$\u003clogging function\u003e()`. Unnamed \narguments to the logging function are interpreted by `sprintf()`. For a way\nto create loggers that [glue](https://glue.tidyverse.org/) instead\nplease refer to the vignette.\n\n```{r}\nlgr$fatal(\"A critical error\")\nlgr$error(\"A less severe error\")\nlgr$warn(\"A potentially bad situation\")\nlgr$info(\"iris has %s rows\", nrow(iris))\n\n# the following log levels are hidden by default\nlgr$debug(\"A debug message\")\nlgr$trace(\"A finer grained debug message\")\n```\n\nA Logger can have several Appenders. For example, we can add a JSON appender to\nlog to a file with little effort. \n\n```{r}\ntf \u003c- tempfile()\nlgr$add_appender(AppenderFile$new(tf, layout = LayoutJson$new()))\nlgr$info(\"cars has %s rows\", nrow(cars))\ncat(readLines(tf))\n```\n\nBy passing a named argument to `info()`, `warn()`, and co you can log not only \ntext but arbitrary R objects. Not all appenders support structured logging\nperfectly, but JSON does. This way you can create \nlogfiles that are machine as well as (somewhat) human readable.\n\n```{r}\nlgr$info(\"loading cars\", \"cars\", rows = nrow(cars), cols = ncol(cars))\ncat(readLines(tf), sep = \"\\n\")\n```\n\n```{r, echo=FALSE}\nunlink(tf)\n```\n\nFor more examples please see the \npackage \n[vignette](https://s-fleck.github.io/lgr/articles/lgr.html) and \n[documentation](https://s-fleck.github.io/lgr/)\n\n\n## See lgr in action\n\nlgr is used to govern console output in my shiny based csv editor \n[shed](https://github.com/s-fleck/shed)\n\n```{r eval = FALSE}\n# install.packages(\"remotes\")\nremotes::install_github(\"s-fleck/shed\")\nlibrary(shed)\n\n# log only output from the \"shed\" logger to a file\nlogfile \u003c- tempfile()\nlgr::get_logger(\"shed\")$add_appender(AppenderFile$new(logfile))\nlgr::threshold(\"all\")\n\n# edit away and watch the rstudio console!\nlgr$info(\"starting shed\")\nshed(iris)  \nlgr$info(\"this will not end up in the log file\")\n\nreadLines(logfile)\n\n# cleanup\nfile.remove(logfile)\n```\n\n\n## Development status\n\nlgr in general is stable and safe for use, but **the following features are still experimental**: \n\n* Database appenders which are available from the separate package\n  [lgrExtra](https://github.com/s-fleck/lgrExtra). \n* yaml/json config files for loggers (do not yet support all planned features)\n* The documentation in general. I'm still hoping for more R6-specific features\n  in [roxygen2](https://github.com/r-lib/roxygen2) before I invest more\n  time in object documentation.\n\n\n## Dependencies\n\n[R6](https://github.com/r-lib/R6): The R6 class system provides the framework\non which lgr is built and the **only Package lgr will ever depend on**. If you \nare a **package developer** and want to add logging to your package, this is the\nonly transitive dependency you have to worry about, as configuring of the \nloggers should be left to the user of your package.\n\n\n### Optional dependencies\n\nlgr comes with a long list of optional dependencies that make a wide range of\nappenders possible. You only need the dependencies for the Appenders you\nactually want to use. Care was taken to choose packages that are slim, stable, \nhave minimal dependencies, and are well maintained :\n\n  \n  Extra appenders (in the main package):\n  \n  - [jsonlite](https://github.com/jeroen/jsonlite) for JSON logging via \n    `LayoutJson`. JSON is a popular plaintext based file format that is easy to \n    read for humans and machines alike.\n    \n  - [rotor](https://github.com/s-fleck/rotor) for log rotation via \n    AppenderFileRotating and co. \n    \n  - [data.table](https://github.com/Rdatatable/) for fast in-memory \n    logging with `AppenderDt`, and also by all database / DBI Appenders. \n\n  - [glue](https://glue.tidyverse.org/) for a more flexible formatting syntax\n    via LoggerGlue and LayoutGlue.\n    \n  Extra appenders via [lgrExtra](https://github.com/s-fleck/lgrExtra):\n  \n  - [DBI](https://github.com/r-dbi/DBI) for logging to databases. lgr is \n    confirmed to work with the following backends: \n    - [RSQLite](https://github.com/r-dbi/RSQLite), \n    - [RMariaDB](https://github.com/r-dbi/RMariaDB) for MariaDB and MySQL,\n    - [RPostgres](https://cran.r-project.org/package=RPostgres),\n    - [RJDBC](https://github.com/s-u/RJDBC) for DB2, and\n    - [odbc](https://github.com/r-dbi/odbc) also for DB2. \n    \n    In theory all DBI compliant database packages should work. If you\n    are using lgr with a database backend, please report your (positive and\n    negative) experiences, as database support is still somewhat experimental.\n  \n  - [gmailr](https://cran.r-project.org/package=gmailr) or\n  \n  - [sendmailR](https://cran.r-project.org/package=sendmailR) for email \n      notifications.\n      \n  - [RPushbullet](https://github.com/eddelbuettel/rpushbullet) for push\n    notifications.\n    \n  - [Rsyslog](https://cran.r-project.org/package=rsyslog) for logging to\n    syslog on POSIX-compatible systems.\n    \n  - [elastic](https://cran.r-project.org/package=elastic) for logging\n    to ElasticSearch\n  \n  Other extra features:\n  \n  - [yaml](https://CRAN.R-project.org/package=yaml) for configuring loggers \n    via YAML files  \n  - [crayon](https://github.com/r-lib/crayon) for colored console output.  \n  - [whoami](https://github.com/r-lib/whoami/blob/master/DESCRIPTION) for \n    guessing the user name from various sources. You can also set the user name \n    manually if you want to use it for logging.\n  - [desc](https://CRAN.R-project.org/package=desc) for the package development\n    convenience function `use_logger()`\n  - [cli](https://CRAN.R-project.org/package=cli) for printing the tree \n    structure of registered loggers with `logger_tree()`\n    \n  Other `Suggests`\n  ([future](https://CRAN.R-project.org/package=future), \n  [future.apply](https://CRAN.R-project.org/package=future.apply)) do not \n  provide extra functionality but had to be included for some of \n  the automated unit tests run by lgr.\n    \n\n## Installation\n\nYou can install lgr from CRAN\n\n```{r eval = FALSE}\ninstall.packages(\"lgr\")\n```\n\nOr you can install the current development version directly from github\n\n```{r eval = FALSE}\n#install.packages(\"remotes\")\nremotes::install_github(\"s-fleck/lgr\")\n```\n\n## Outlook\n\nThe long term goal is to support (nearly) all features of the python logging\nmodule. If you have experience with python logging or Log4j and are missing\nfeatures/appenders that you'd like to see, please feel free to post a feature \nrequest on the issue tracker.\n\n\n\n\n## Acknowledgement\n\n* [diagrams.net](https://app.diagrams.net/) for the flow chart in the vignette\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-fleck%2Flgr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs-fleck%2Flgr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs-fleck%2Flgr/lists"}