LogRedux is a simple but rather customizable logging library for Ruby. It was completely inspired by Log.c3.
LogRedux does not aim to be a replacement for stdlib's Logger library - it's neither better nor more complete than it. Rather, LogRedux is simply another alternative for logging in your Ruby application.
A rather complete example of LogRedux in action can be found in the examples folder.
Get the log_redux
gem by running:
gem install log_redux
Or add this line to your application's Gemfile:
gem 'log_redux'
After installing the gem, add the following line to your application:
require 'log_redux'
Create a logger by instantiating the LogRedux::Logger
class:
logger = LogRedux::Logger.new
Logger.new
accepts the following options:
output_filename
: The name of the file to which the logger will write. Defaults to$stderr
. Expects either a string,$stdout
or$stderr
.
Note
By default,
output_filename
will be opened in append mode, meaning that if the file already exists, the logger will append to it instead of overwriting it. If you wish to overwrite the contents of the file, make sure to always clear or delete it before creating the logger or after closing it.
The following arguments must be named:
color
: Whether the logger should colorize the output using ANSI color codes. Defaults totrue
.timestamp
: Whether the logger should add a timestamp to the output. Defaults totrue
.filename
: Whether the logger should add the name and the line number of the file from which the log was generated. Defaults totrue
.track
: Whether to keep track internally of all logs emitted. Defaults tofalse
.
For example:
logger = LogRedux::Logger.new('log.txt', color: false, timestamp: true, filename: false, track: true)
Note
I recommend disabling
color
when logging to a file, as it will add ANSI color codes to the output, making it harder to read. If later you wish to read from the file and print these logs to the screen, it's better to instead create two loggers, one for the file and one for the terminal ($stdout
or$stderr
).
These arguments can be accessed and modified after the logger is created via their respective instance variables:
attr_accessor :color, :timestamp, :filename, :track
The actual File
object of the logger can be accessed (but not modified) via the log_file
instance variable.
Log messages to output_filename
using the following methods:
logger.log(level, msg: msg)
# Internally, these call the `log` method:
logger.trace(msg)
logger.debug(msg)
logger.info(msg)
logger.warn(msg)
logger.error(msg)
logger.fatal(msg)
All the methods above return the formatted log message.
x = logger.warn("Hi!") #=> x == "17:00:00 WARN test.rb:1: Hi!"
LogRedux offers 6 different log levels:
- "TRACE" (also :TRACE) - Used for verbose, fine-grained information of what is happening in your application or inside third-party libraries.
- "DEBUG" (also :DEBUG) - Less verbose than TRACE. Used for messages needed for diagnosing and troubleshooting.
- "INFO" (also :INFO) - The standard log level for regular events. Used for general information about the application's operation.
- "WARN" (also :WARN) - Used for potentially harmful situations that are not necessarily errors.
- "ERROR" (also :ERROR) - Used for errors preventing one or more operations from working properly.
- "FATAL" (also :FATAL) - Used for unrecoverable errors that are fatal to crucial operations.
If tracking is enabled, the logging history can be accessed via the history
instance variable:
p logger.history # This will always print [] if `track` is set to false
history
is an array of hashes with the following keys:
:level
: The level of the log.:time
: The timestamp of the log.:filename
: The file from which the log was generated.:line
: The line number where the log was generated.:msg
: The message of the log.:formatted
: The complete formatted log message.
For example:
[
{
level: :TRACE,
time: "17:00:00",
filename: "test.rb",
line: 1,
msg: "Hello, world!",
formatted: "17:00:00 INFO main.rb:1: Hello, world!" # Note that this example has `color` set to false, otherwise the ANSI color codes would be present.
}
]
The methods []
, first
and last
can be used to get the formatted log of a given history entry. For the example above, all three would return the same thing:
logger[0] # => "17:00:00 TRACE test.rb:1: Hello, world!"
logger.first # => "17:00:00 TRACE test.rb:1: Hello, world!"
logger.last # => "17:00:00 TRACE test.rb:1: Hello, world!"
If you wish to access the full detailed log for a specific entry, do it via the history
instance variable:
logger.history[0] # => {level: :TRACE, time: "17:00:00", filename: "test.rb", line: 1, msg: "Hello, world!", formatted: "17:00:00 INFO test.rb:1: Hello, world!"}
Remember to always close a logger when you're done with it:
logger.close
Note
$stdout
and$stderr
loggers should not be closed, and trying to do so will raise an error.
As previously mentioned, thanks to Its-Kenta and his logging library Log.c3 for the inspiration.