ualacecafe / log_redux Goto Github PK

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 to true.
• timestamp: Whether the logger should add a timestamp to the output. Defaults to true.
• filename: Whether the logger should add the name and the line number of the file from which the log was generated. Defaults to true.
• track: Whether to keep track internally of all logs emitted. Defaults to false.

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.