Verbose Logging

Preconfigured log levels for Ruby libraries.

An extraction from the Smith agent framework that wraps around the Logging gem.

Rationale

Some libraries and applications require a more fine-grained set of log levels than what Ruby’s standard library logger provides. For example, developers may want to flip on a verbose mode in their software to dump sophisticated diagnostic messages that don’t fit into either debug or info levels.

It’s fine and normal for applications to manually configure their own set of expected log levels. But configuring custom log levels is error-prone and tricky to manage when the same logging dependency is being loaded by library code that’s shared across multiple applications.

Instead of taking a ‘convention over configuration’ approach to sharing a common set of log levels across libraries, this Gem packages up this default configuration as a shared dependency.

Log Levels

Level	Context
verbose	Fine-grained diagnostic traces
debug	Debugging information
info	Standard operational events
warn	Recoverable fault or breach of boundary conditions
error	Critical fault affecting a single operation
fatal	Critical fault affecting the entire system

Usage

Add verbose-logging as a dependency in the gemspec for your library:

spec.add_dependency "verbose-logging", "~> 1.0"

Replace any direct requires of the logging Gem with verbose-logging:

require 'verbose-logging'

This will automatically switch on the predefined set of log levels for verbose logging.

Manual Configuration

In some circumstances, the Logging module will be loaded and initialised by another library before your library or application gets the chance to do anything with it. This is a common source of bugs, as described above.

This gem takes a conservative approach automatically configuring the log levels, and logs a warning rather than resetting any existing loggers.

If you do want to do that, you can load and initialize verbose logging manually, passing the reset: true parameter to trigger an internal reset of the global logging state.

require 'logging/verbose'

Logging.init_verbose_levels(reset: true)