YEAR: 2021 117 | COPYRIGHT HOLDER: rlog authors 118 |119 | 120 |
NEWS.md
115 | Copyright (c) 2021 rlog authors
119 |Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
120 |The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
121 |THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
122 |Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_info(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_info("This is an info message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_info("This is an info message") 145 | } 146 |
Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_debug(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_debug("This is a debug message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_debug("This is a debug message") 145 | } 146 |
Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_fatal(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_fatal("This is a fatal message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_fatal("This is a fatal message") 145 | } 146 |
Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_trace(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_trace("This is a trace message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_trace("This is a trace message") 145 | } 146 |
Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_error(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_error("This is an error message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_error("This is an error message") 145 | } 146 |
Log messages will only be emitted if the log priority matches or is higher 122 | than the priority of your message
123 |log_warn(message)126 | 127 |
| message | 132 |your message to log |
133 |
|---|
invisibly returns TRUE/FALSE
139 | 140 |147 |if (FALSE) { 142 | log_warn("This is a warning message") 143 | Sys.setenv("LOG_LEVEL" = "TRACE") 144 | log_warn("This is a warning message") 145 | } 146 |
rlog is an opinionated, lightweight logging package for R.
78 |It relies on long standing Unix traditions, to write simple log messages in a flexible way.
79 |Log message output looks like this:
80 |2021-02-21 17:19:06 [INFO] This is my log messageInstall rlog from GitHub with the following:
85 |
86 | devtools::install_github("sellorm/rlog")We think so, yes!
92 |There are already loads of logging packages for R. Many are no longer maintained and of the remaining selection some are overly complex, making them less approachable for beginners.
93 |Since logging should be an essential part of any production application or pipeline I think it’s important that as many people as possible are introduced to good logging practice.
94 |If rlog doesn’t have enough features for you, I’d recommend the excellent “logger” instead.
95 |The rlog philosophy is the Unix philosophy and as such, we expect applications using rlog to be able to integrate with other enterprise software quickly and efficiently.
100 |rlog is simple by design and it relies on existing Unix/Linux norms to get the job done.
101 |The best way to use rlag is to call the functions directly from within your applications.
111 |There is one function per log message level:
112 |
113 | rlog::log_fatal("my fatal message")
114 | rlog::log_error("my error message")
115 | rlog::log_warn("my warn message")
116 | rlog::log_info("my info message")
117 | rlog::log_debug("my debug message")
118 | rlog::log_trace("my trace message")If you run this code as-is without setting a custom LOG_LEVEL with the environment variable, you’ll get output like this:
2021-02-21 17:19:06 [FATAL] fatal
121 | 2021-02-21 17:19:06 [ERROR] error
122 | 2021-02-21 17:19:06 [WARN] warn
123 | 2021-02-21 17:19:06 [INFO] infoThe “DEBUG” and “TRACE” message won’t be printed, since the default LOG_LEVEL is “INFO” and those message have lower priority.
Play around with setting the LOG_LEVEL directly in R and seeing what messages are emitted:
127 | Sys.setenv("LOG_LEVEL" = "ERROR")
128 | rlog::log_fatal("my fatal message")
129 | rlog::log_error("my error message")
130 | rlog::log_warn("my warn message")
131 | rlog::log_info("my info message")
132 | rlog::log_debug("my debug message")
133 | rlog::log_trace("my trace message")Gives us this output:
135 |2021-02-21 17:19:06 [FATAL] fatal
136 | 2021-02-21 17:19:06 [ERROR] errorRemember though, the best way to set the environment variable is outside of the app. That way it’s easier to change at run-time.
138 |So in your terminal you can do something like this before you run your script:
139 |$ export LOG_LEVEL=TRACE
140 | $ ./my_script.ROr you can even call your script with the appropriate value at run-time:
142 |$ LOG_LEVEL=ERROR ./my_script.RIf you’re using RStudio Connect users can set an environment variable called LOG_LEVEL in the “Vars” tab of their apps control panel.
rlog relies on an environment variable called LOG_LEVEL to control which log messages are emitted.
If it’s not set, it will default to “INFO”.
150 |The available levels – in decreasing order of severity – are as follows:
151 |When the LOG_LEVEL environment variable is set to “INFO”, only messages at that level and above will be emitted.
Another example:
161 |This is a really powerful way of only including the messages you want to see in the log files at any given time. For example, you may choose to set the LOG_LEVEL to “TRACE” while developing your application or if it runs into a problem in production, but you might choose to run the application with a LOG_LEVEL of “ERROR” under normal circumstances.
rlog outputs it log messages into the console in the same way that most Unix/Linux tools do. Ordinary messages go to “standard output” (stdout) and errors go to “standard error” (stderr).
175 |This means they can be captured in the standard Unix/Linux way:
176 |./my_script.R > /path/to/file.log 2>&1This command redirects stderr to stdout and drops it all into the /path/to/file.log file.
You can also keep the “normal” and error outputs separate:
179 |./my_script.R > /path/to/file.log 2> /path/to/errors.logMany enterprise software products, such as RStudio Connect will capture this output automatically and save it for you.
181 |