DVLA::Herodotus

A Gem that produces loggers that are pre-formatted into an agreed log format

Installation

Add this line to your application's Gemfile:

gem 'dvla-herodotus'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install dvla-herodotus

---

Usage

Logger

You can get a logger by calling the following once Herodotus is installed:

logger = DVLA::Herodotus.logger('<system-name>')

You can also log out to a file. If you want all the logs in a single file, provide a string of the path to that output file and it will be logged to simultaneously with standard console logger.

Note: Log messages are stripped of colour codes before being saved to file.

logger = DVLA::Herodotus.logger('<system-name>', output_path: 'logs.txt')

Alternatively, if you want each scenario to log out to a separate file based on the scenario name, pass in a lambda that returns a string that attempts to interpolate @scenario.

logger = DVLA::Herodotus.logger('<system-name>', output_path: -> { "#{@scenario}_log.txt" })

This is a standard Ruby logger, so anything that would work on a logger acquired the traditional way will also work here, however it is formatted such that all logs will be output in the following format:

[SystemName CurrentDate CurrentTime CorrelationId] Level : -- Message

Configuration

You can configure Herodotus in the following way to add a Process Id to the output:

config = DVLA::Herodotus.config do |config|
  config.display_pid = true
end
logger = DVLA::Herodotus.logger('<system-name>', config: config)

This would result in logs in the following format:

[SystemName CurrentDate CurrentTime CorrelationId PID] Level : -- Message

Prefix Colourisation

You can colourise different parts of the log prefix by providing a hash to style each component. It accepts strings, symbols or arrays of either:

config = DVLA::Herodotus.config do |config|
  config.prefix_colour = {
    system: %w[blue bold],
    date: 'green',
    time: :yellow,
    correlation: %w[magenta italic],
    pid: %w[cyan],
    level: %i[red bold],
    separator: %w[white],
    overall: %w[underline]
  }
end

Each key is optional, and you can simply use the overall key to style the whole prefix.

Syncing logs

Herodotus allows you to Sync correlation_ids between instantiated HerodotusLogger objects.

The HerodotusLogger flagged as main will be used as the source.

config = DVLA::Herodotus.config do |config|
  config.main = true
end
main_logger = DVLA::Herodotus.logger('<system-name>', config: config)

new_scenario method

You can call new_scenario with the identifier just before each scenario to create a unique correlation_id per scenario.

logger.new_scenario('Scenario Id')

---

Strings

Also included is a series of additional methods on String that allow you to modify the colour and style of logs. You can stack multiple method calls to add additional styling and use string interpolation to style different parts of the string

  example_string = "#{'H'.red}#{'E'.bright_red}#{'R'.yellow}#{'O'.green}#{'D'.blue}#{'O'.bright_blue}#{'T'.magenta}#{'U'.bright_magenta}#{'S'.cyan}".bold.reverse_colour

Available String Methods

Type	Examples
Text Styles	bold dim italic underline
Colours	black red green brown yellow blue magenta cyan gray white
Bright Colours	bright_red bright_green bright_blue bright_magenta bright_cyan
Background Colours	bg_black bg_red bg_green bg_brown bg_yellow bg_blue bg_magenta bg_cyan bg_gray bg_white
Bright Background Colours	bg_bright_red bg_bright_green bg_bright_blue bg_bright_magenta bg_bright_cyan
Utility	strip_colour reverse_colour

To handle differences in spelling the following methods have been given aliases:

Alias	Original
bg_grey	bg_gray
colorize	colourise
grey	gray
reverse_color	reverse_colour
strip_color	strip_colour

---

Development

Herodotus is very lightweight. Currently, all code to generate a new logger can be found in herodotus.rb and the code for the logger is in herodotus_logger.rb so that is the best place to start with any modifications