ougai-formatters-customizable 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64f9b36ed7779caff3e9ce05fe6062d1f6c0ab7e7754b55463a3475147bc1b27
-  data.tar.gz: 62c6c4db4205f4faea3a3c5f6cc5cb1c1b3cdbf6849f1cf3085636eb5e5e19b0
+  metadata.gz: f9ac580c652c5578865e731227f1488dfb95bec37644f78366414bc69268424c
+  data.tar.gz: b8afc7c9c56f01bcd742987e08c4e0daa201aad503fd86c9950061169bb3a440
 SHA512:
-  metadata.gz: 445010e474a5863bf5311395b474857825962a67b7f2f72ad030656f46e8e99b339264dff77057d06e2f8bde3eda75ce661c620fd7afade58f94461b0a2393db
-  data.tar.gz: 7b06933a749c5632e87d7828f6009145c4d21ec3e01a23696d982e160bc96bd1fa8854a71c8a142d5e400deac0becbe2264055c9c17005855f50cbd1a448509a
+  metadata.gz: 92ae20d2af4f58607ceaebc80197d3195441a5b2e54733ec2bdc094c0a479425e7c5f85403a80c194455cdfbbd1bf7080b9c55ddd746dba6c680fec7ec454602
+  data.tar.gz: 9e1adbf551fc7f260a92155da26d5959c2819d8905f0be3495b96a133338a2da6489036f23ca427bf64826106ec3adacb9fc1798032aa06a572476ff45480ade

data/README.md

@@ -1,39 +1,311 @@
-# Ougai::Formatters::Customizable
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ougai/formatters/customizable`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ougai-formatters-customizable'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install ougai-formatters-customizable
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ougai-formatters-customizable.
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+# Ougai-formatters-customizable
+
+[![Gem Version](https://badge.fury.io/rb/ougai-formatters-customizable.svg)](https://badge.fury.io/rb/ougai-formatters-customizable)
+[![Build Status](https://travis-ci.com/Al-un/ougai-formatters-customizable.svg?branch=master)](https://travis-ci.com/Al-un/ougai-formatters-customizable)
+[![Maintainability](https://api.codeclimate.com/v1/badges/eaf20e90252260db1b68/maintainability)](https://codeclimate.com/github/Al-un/ougai-formatters-customizable/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/eaf20e90252260db1b68/test_coverage)](https://codeclimate.com/github/Al-un/ougai-formatters-customizable/test_coverage)
+
+A fully customizable formatters for [Ougai](https://github.com/tilfin/ougai) 
+library. Customization is about formatting and colorization
+
+**Formatting**
+
+Ougai log printing can be split in three components:
+
+ 1. Main log message: usually timestamp, log severity and a message
+ 2. Data: the structured logging, represented by a Hash
+ 3. Errors
+
+**Colorization**
+
+Each part of the main log message can be colored independently. Colorization can
+be extended to custom formatters as well.
+
+## Usage
+
+In your Gemfile, add *ougai-formatters-customizable* and its dependencies:
+
+```ruby
+gem 'awesome_print'
+gem 'ougai'
+gem 'ougai-formatters-customizable'
+```
+
+Then initialize a formatter and assign it to your logger:
+
+```ruby
+formatter           = Ougai::Formatters::Customizable.new
+# See Ougai documentation about how to initialize a Ougai logger
+logger.formatter    = formatter
+```
+
+The default *Customizable* configuration is exactly identical to a 
+*Ougai::Formatters::Readable* as-of Ougai 1.7.0.
+
+#### Datetime format
+
+Inherited from Ruby logger formatters, you can assign a datetime format:
+
+```ruby
+formatter.datetime_format = '%H:%M:%S.%L' # print time only such as '15:42:36.246'
+```
+
+#### Message formatter: `format_msg`
+
+Main log message formatter is a `proc` which takes four arguments: 
+
+ - [String] severity: log severity. Is in capital letters
+ - [String] datetime: log timestamp. Is already formatted according to `datetime_format`. 
+   Has to be treated like a String
+ - [String] progname: optional program name
+ - [Hash] data: structured log data. The main message is logged under the `:msg` key. 
+
+Custom message formatter can be assigned at initialization via the key `format_msg`:
+
+```ruby
+formatter = Ougai::Formatters::Customizable.new(
+    format_msg: proc do |severity, datetime, _progname, data|
+        msg = data.delete(:msg)
+        format('%s %s: %s', severity, datetime, msg)
+    end
+)
+```
+
+**Notes**
+
+ - It is recommended that this proc removes the `:msg` key from `data` to avoid
+   duplicates
+ - Although not mandatory, this formatter aims at outputting a single line String
+
+#### Data formatter: `format_data`
+
+Data formatter is a `proc` which takes only `data` as argument. Custom data 
+formatter can be assigned at initialization via `format_data` key:
+
+```ruby
+formatter = Ougai::Formatters::Customizable.new(
+    format_data: proc do |data|
+        data.ai # Awesome-print printing
+    end
+)
+```
+
+**Notes**
+
+ - Data formatter must return `nil` if `data` is empty.
+ - Default data formatter takes the `excluded_fields` option into account. You
+   need to add it to your custom formatter if you want to keep it.
+
+#### Error formatter: `format_err`
+
+Error formatter is a `proc` with only `data` as argument and can be assigned at 
+initialization via the `format_err` key:
+
+```ruby
+formatter = Ougai::Formatters::Customizable.new(
+    format_err: proc do |data|
+        next nil unless data.key?(:err)
+
+        err = data.delete(:err)
+        "  #{err[:name]} (#{err[:message]})"
+    end
+)
+```
+
+**Notes**
+
+ - Error formatter must return `nil` if `data` does not contain the `:err` key
+ - Error formatter must remove `:err` key
+ - Default error formatter takes the `trace_indent` option into account. You need
+   to add it to your custom formatter if you want to keep it
+
+#### Colorization
+
+Colorization is handled by an instance of `Ougai::Formatters::Colors::Configuration`
+and is basically a mapping *subject => value* to define the colors. Default subject
+are:
+
+ - `:severity`: log severity coloring
+ - `:datetime`: datetime coloring
+ - `:msg`: log main message coloring
+
+You can add your own subject if you need it in your custom formatters. 
+
+Values can have three types:
+
+ - String: this color is applied to the subject regardless the situation
+ - Hash: the color is defined by log severity. Non defined severity colors are
+   fetched from the `default` severity
+ - Symbol: the color is copied from the referenced symbol
+
+Example:
+
+```ruby
+color_configuration = Ougai::Formatters::Colors::Configuration.new(
+    severity: {
+      trace:    Ougai::Formatters::Colors::WHITE,
+      debug:    Ougai::Formatters::Colors::GREEN,
+      info:     Ougai::Formatters::Colors::CYAN,
+      warn:     Ougai::Formatters::Colors::YELLOW,
+      error:    Ougai::Formatters::Colors::RED,
+      fatal:    Ougai::Formatters::Colors::PURPLE
+    },
+    msg: :severity,
+    datetime: {
+      default:  Ougai::Formatters::Colors::PURPLE,
+      error:    Ougai::Formatters::Colors::RED,
+      fatal:    Ougai::Formatters::Colors::RED
+    },
+    custom:     Ougai::Formatters::Colors::BLUE
+)
+```
+
+ - *Severity* has a different color dependending on log severity
+ - Main log *message* color is identical to severity color
+ - *Datetime* has a red color for *error* and *fatal* logs. Otherwise it is
+   colored in purple.
+ - A *custom* subject is always colored in blue regardless log severity
+
+**Notes**
+ 
+ - If `:severity` is not defined, it is loaded from a default configuration
+ - If `:severity` is partially defined, missing severities are fetched from 
+   default configuration
+ - Circular references are not checked and infinite loops can then be triggered. 
+
+## Integration
+
+#### Lograge / Lograge-sql
+
+I initially made this gem to couple Ougai with [lograge](https://github.com/roidrage/lograge)/[lograge-sql](https://github.com/iMacTia/lograge-sql). Lograge logs has to be 
+formatted in a way so that our custom formatters can catch it:
+
+```ruby
+# config/initializers/lograge.rb
+config.lograge.formatter = Class.new do |fmt|
+    def fmt.call(data)
+        { request: data }
+    end
+end
+```
+
+I chose this format because I am also using Loggly and it is pretty convenient 
+to filter by `json.request.*` to fetch Lograge logs.
+
+If using lograge-sql, make sure that Lograge format it as a Hash so that we can
+leverage our main message formatter and data formatter:
+
+```ruby
+# config/initializers/lograge.rb
+  config.lograge_sql.extract_event = proc do |event|
+    {
+      name: event.payload[:name],
+      duration: event.duration.to_f.round(2),
+      sql: event.payload[:sql]
+    }
+  end
+  config.lograge_sql.formatter = proc do |sql_queries|
+    sql_queries
+  end
+```
+
+Wrap everything together example:
+
+```ruby
+# Define our colors
+color_configuration = Ougai::Formatters::Colors::Configuration.new(
+    severity: {
+      trace:    Ougai::Formatters::Colors::WHITE,
+      debug:    Ougai::Formatters::Colors::GREEN,
+      info:     Ougai::Formatters::Colors::CYAN,
+      warn:     Ougai::Formatters::Colors::YELLOW,
+      error:    Ougai::Formatters::Colors::RED,
+      fatal:    Ougai::Formatters::Colors::PURPLE
+    },
+    msg: :severity,
+    datetime: {
+      default:  Ougai::Formatters::Colors::PURPLE,
+      error:    Ougai::Formatters::Colors::RED,
+      fatal:    Ougai::Formatters::Colors::RED
+    }
+)
+
+# Lograge specific configuration
+EXCLUDED_FIELD = [:credit_card] # example only
+LOGRAGE_REJECT = [:sql_queries, :sql_queries_count]
+
+# Console formatter configuration
+console_formatter = Ougai::Formatters::Customizable.new(
+    format_msg: proc do |severity, datetime, _progname, data|
+        # Remove :msg regardless the outcome
+        msg = data.delete(:msg)
+        # Lograge specfic stuff: do not print sql queries in main log message
+        if data.key?(:request)
+            lograge = data[:request].reject { |k, _v| LOGRAGE_REJECT.include?(k) }
+                                    .map { |key, val| "#{key}: #{val}" }
+                                    .join(', ')
+            msg = color_config.color(:msg, lograge, severity) 
+        # Standard text
+        else
+            msg = color_config.color(:msg, msg, severity)
+        end
+
+        # Standardize output
+        format('%s %s: %s',
+                color_config.color(:severity, severity, severity),
+                color_config.color(:datetime, datetime, severity),
+                msg)
+    end,
+    format_data: proc do |data|
+        # Lograge specfic stuff: main controller output handled by msg formatter
+        if data.key?(:request)
+            lograge_data = data[:request]
+            # concatenate SQL queries
+            if lograge_data.key?(:sql_queries)
+                lograge_data[:sql_queries].map do |sql_query|
+                    format('%<duration>6.2fms %<name>25s %<sql>s', sql_query)
+                end
+                .join("\n")
+            # no queries: nothing to print
+            else
+                nil
+            end
+        # Default styling
+        else
+            # report excluded field parameter here: no need to add it to options
+            EXCLUDED_FIELD.each { |field| data.delete(field) }
+            next nil if data.empty?
+
+            # report plain parameter here: no need to add it to options
+            data.ai(plain: false)
+        end
+    end
+)
+console_formatter.datetime_format = '%H:%M:%S.%L' # local development: need only time
+
+# Define console logger
+console_logger            = Log::Ougai::Logger.new(STDOUT)
+console_logger.formatter  = console_formatter
+
+# Not this gem related: define file logger
+file_logger               = Log::Ougai::Logger.new(Rails.root.join('log/ougai.log'))
+file_logger.formatter     = Ougai::Formatters::Bunyan.new
+
+# Extend console logger to file logger
+console_logger.extend(Ougai::Logger.broadcast(file_logger))
+
+# Assign Ougai logger
+config.logger = console_logger
+```
+
+Output looks like
+![Screenshot](https://raw.githubusercontent.com/Al-un/ougai-formatters-customizable/master/images/screenshot.png)
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Al-un/ougai-formatters-customizable.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ougai/formatters/colors.rb

@@ -16,30 +16,51 @@ module Ougai
 
       # Reset formatting. To be appended after every formatted text
       RESET             = "\e[0m"
-      # Foreground colors
+      # Font black color
       BLACK             = "\e[30m"
+      # Font red color
       RED               = "\e[31m"
+      # Font green color
       GREEN             = "\e[32m"
+      # Font yello color
       YELLOW            = "\e[33m"
+      # Font blue color
       BLUE              = "\e[34m"
+      # Font purple color
       PURPLE            = "\e[35m"
+      # Font cyan color
       CYAN              = "\e[36m"
+      # Font white color
       WHITE             = "\e[37m"
+      # Font bright/bold red color
       BOLD_RED          = "\e[1;31m"
+      # Font bright/bold green color
       BOLD_GREEN        = "\e[1;32m"
+      # Font bright/bold yellow color
       BOLD_YELLOW       = "\e[1;33m"
+      # Font bright/bold blue color
       BOLD_BLUE         = "\e[1;34m"
-      BOLD_MAGENTA      = "\e[1;35m"
+      # Font bright/bold purple color
+      BOLD_PURPLE       = "\e[1;35m"
+      # Font bright/bold cyan color
       BOLD_CYAN         = "\e[1;36m"
+      # Font bright/bold white color
       BOLD_WHITE        = "\e[1;37m"
-      # Background colors
+      # Background black color
       BG_BLACK          = "\e[40m"
+      # Background red color
       BG_RED            = "\e[41m"
+      # Background green color
       BG_GREEN          = "\e[42m"
+      # Background yellow color
       BG_YELLOW         = "\e[43m"
+      # Background blue color
       BG_BLUE           = "\e[44m"
-      BG_MAGENTA        = "\e[45m"
+      # Background purple color
+      BG_PURPLE         = "\e[45m"
+      # Background cyan color
       BG_CYAN           = "\e[46m"
+      # Background white color
       BG_WHITE          = "\e[47m"
 
       class << self
@@ -53,8 +74,9 @@ module Ougai
         #         above or have a complete custom String value depending on the
         #         terminal. If +nil+, text is not modified.
         # @param [String] text text to be colored
-        # @param [String] reset reset font styling escape sequence. Default
-        #         to +\e[0m+
+        # @param [String] reset reset font styling escape sequence
+        #
+        # @return [String] colored or uncolored text
         def color_text(color, text, reset = Ougai::Formatters::Colors::RESET)
           return text if color.nil?
 

data/lib/ougai/formatters/colors/configuration.rb

@@ -9,10 +9,11 @@ module Ougai
       # The configuration,split by subject such as +level+, +msg+,
       # or +datetime+ is basically a Hash: +config+ with the subject as key
       # and values. Values can be have three types:
-      #   - String: the color escape sequence for the subject
-      #   - Hash: the color escape sequence per severity. If not all severities
-      #     are defined, a +:default+ value must be defined
-      #   - Symbol: refers to another key and same coloring is applied
+      #
+      # - +String+: the color escape sequence for the subject
+      # - +Hash+: the color escape sequence per severity. If not all severities
+      #   are defined, a +:default+ value must be defined
+      # - +Symbol+: refers to another key and same coloring is applied
       class Configuration
         class << self
           # list default color configuration
@@ -20,6 +21,7 @@ module Ougai
           #       +Ougai::Logging::Severity#to_label+
           # @note values are copied from +Ougai::Formatters::Readable+ coloring
           #       values
+          # @return [Hash] default color configuration is severities only
           def default_configuration
             {
               severity: {
@@ -35,10 +37,14 @@ module Ougai
           end
         end
 
-        # @param [Hash] configuration Color configuration mapping. Cannot be nil
-        # @param [Boolean] load_default_config If true, then default configuration
-        #         values is fetched to fill missing value from the provided 
-        #         configuration. Default is true.
+        # Configuration accept following keys:
+        # - +:load_default_config+ If true, then default configuration
+        #   values is fetched to fill missing value from the provided 
+        #   configuration. Default is true.
+        # - any remaining key is considered to be color-related and is translated
+        #   into a *subject => color rule* mapping
+        #
+        # @param [Hash] configuration color configuration. Cannot be nil
         def initialize(configuration = {})
           # check if loading or not from default configuration
           if configuration.fetch(:load_default_config) { true }
@@ -62,10 +68,13 @@ module Ougai
           end
         end
 
+        # Convenience method to color a subject for a given log severity
+        #
         # @param [Symbol] subject_key to fetch the color to color the text
         # @param [String] text to be colored text
         # @param [Symbol] severity log level
-        # @return a colored text depending on the subject
+        #
+        # @return [String] a colored text depending on the subject
         def color(subject_key, text, severity)
           color = get_color_for(subject_key, severity)
           Ougai::Formatters::Colors.color_text(color, text)
@@ -78,12 +87,14 @@ module Ougai
         # +get_color_for+ handles color inheritance: if a subject inherit color
         # from another subject, subject value is the symbol refering to the
         # other subject.
-        # !!WARNING!!: Circular references are not checked and lead to infinite
+        #
+        # @note !!WARNING!!: Circular references are not checked and lead to infinite
         # loop  
         #
-        # @param [Symbol] subject_key: to define the color to color the text
-        # @param [Symbol] severity: log level
-        # @return requested color String value or +nil+ if not colored
+        # @param [Symbol] subject_key to define the color to color the text
+        # @param [Symbol] severity log level
+        #
+        # @return [String,nil] requested color String value or +nil+ if not colored
         def get_color_for(subject_key, severity)
           # no colorization
           return nil unless @config.key?(subject_key)

data/lib/ougai/formatters/customizable.rb

@@ -1,145 +1,160 @@
-# frozen_string_literal: true
-
-require 'ougai/formatters/base'
-require 'ougai/formatters/colors/configuration'
-
-module Ougai
-  module Formatters
-    # Ougai log printing can be split in three components:
-    # 1. Main log message: usually with timestamp, log severity and a single
-    #    line message
-    # 2. Log data: the structured logging component. Can be represented by
-    #    a Hash
-    # 3. Errors: errors require specific log formatting
-    #
-    # Customizable offers a flexible way to handle each component
-    # independently with three procs:
-    # +format_msg+    Format message. Proc arguments are
-    #                 +|level, datetime, progname, data|+. This block must
-    #                 remove the key +:msg+ from +data+
-    # +format_data+   Format data. Proc argument is +|data|+.
-    # +format_err+    Format err. Proc argument is +|data|+. The proc must
-    #                 remove the key +:err+
-    class Customizable < Ougai::Formatters::Base
-      class << self
-        # Define the default main log message formatting to use.
-        # @param [Ougai::Formatters::Colors::Configuration] color_config: the
-        #         color configuration to use. Cannot be null but can have an
-        #         empty +config+ hash meaning that there is no colorization
-        def default_msg_format(color_config)
-          proc do |severity, datetime, _progname, data|
-            msg = data.delete(:msg)
-            severity = color_config.color(:severity, severity, severity)
-
-            "[#{datetime}] #{severity}: #{msg}"
-          end
-        end
-
-        # Define the default error formatting to use.
-        # @param [Array<Symbol>] excluded_fields list of key to exclude from
-        #         +data+ before printing logs
-        # @param [Boolean] plain parameter to define if Awesome-Print renders
-        #         in plain mode or not
-        def default_data_format(excluded_fields, plain)
-          proc do |data|
-            excluded_fields.each { |field| data.delete(field) }
-            next nil if data.empty?
-
-            data.ai(plain: plain)
-          end
-        end
-
-        # Define the default error formatting to use.
-        # @param [Integer] trace_indent space indentation to prepend before
-        #         trace content
-        def default_err_format(trace_indent = 4)
-          proc do |data|
-            next nil unless data.key?(:err)
-
-            err = data.delete(:err)
-            err_str = "  #{err[:name]} (#{err[:message]}):"
-            err_str += "\n" + (' ' * trace_indent) + err[:stack] if err.key?(:stack)
-            err_str
-          end
-        end
-      end
-
-      # Intialize a formatter
-      #
-      # @param [String] app_name application name (execution program name if nil)
-      # @param [String] hostname hostname (hostname if nil)
-      # @param [Hash] opts the initial values of attributes
-      # @option opts [String] :trace_max_lines (100) the value of trace_max_lines attribute
-      # @option opts [String] :plain (false) the value of plain attribute
-      # @option opts [String] :excluded_fields ([]) the value of excluded_fields attribute
-      # @option opts [Ougai::Formatters::Colors::Configuration] :color_config
-      #         assign a color configuration. Takes predecence over :colors
-      # @option opts [Proc] :format_msg main message formatter
-      # @option opts [Proc] :format_data data formatter
-      # @option opts [Proc] :format_err error formatter
-      def initialize(app_name = nil, hostname = nil, opts = {})
-        aname, hname, opts = Base.parse_new_params([app_name, hostname, opts])
-        super(aname, hname, opts)
-
-        # Message logging
-        color_config = opts.fetch(:color_config) {
-          color_config = Ougai::Formatters::Colors::Configuration.new({})
-        }
-        @format_msg = opts.fetch(:format_msg) {
-          Customizable.default_msg_format(color_config)
-        }
-
-        # Data logging
-        plain = opts.fetch(:plain) { false }
-        excluded_fields = opts[:excluded_fields] || []
-        @format_data = opts.fetch(:format_data) {
-          Customizable.default_data_format(excluded_fields, plain)
-        }
-
-        # Error logging
-        trace_indent = opts.fetch(:trace_indent) { 4 }
-        @format_err = opts.fetch(:format_err) {
-          Customizable.default_err_format(trace_indent)
-        }
-
-        # Ensure dependency are present
-        load_dependent
-      end
-
-      # Format a log entry
-      #
-      # @param [String] severity log severity, in capital letters
-      # @param [Time] time timestamp of the log. Is formatted by +strftime+
-      # @param [String] progname optional program name
-      # @param [Hash] data log data. Main message is stored under the key +:msg+
-      #         while errors are logged under the key +:err+.
-      def _call(severity, time, progname, data)
-        strs = ''.dup
-        # Main message
-        dt =  format_datetime(time)
-        msg_str = @format_msg.call(severity, dt, progname, data)
-        strs.concat(msg_str)
-
-        # Error: displayed before additional data
-        err_str = @format_err.call(data)
-        strs.concat("\n").concat(err_str) unless err_str.nil?
-
-        # Additional data
-        data_str = @format_data.call(data)
-        strs.concat("\n").concat(data_str) unless data_str.nil?
-
-        strs.concat("\n")
-      end
-
-      protected
-
-      # Ensure `awesompe_print` is loaded
-      def load_dependent
-        require 'awesome_print'
-      rescue LoadError
-        puts 'You must install the awesome_print gem to use this output.'
-        raise
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'ougai/formatters/base'
+require 'ougai/formatters/colors/configuration'
+
+module Ougai
+  module Formatters
+    # Ougai log printing can be split in three components:
+    # 1. Main log message: usually with timestamp, log severity and a single
+    #    line message
+    # 2. Log data: the structured logging component. Can be represented by
+    #    a Hash
+    # 3. Errors: errors require specific log formatting
+    #
+    # Customizable offers a flexible way to handle each component
+    # independently by assigning a proc to the following keys:
+    #
+    # 1. +:format_msg+ Format message. Proc arguments are +|level, datetime, progname, data|+. This block must remove the key +:msg+ from +data+
+    # 2. +:format_data+ Format data. Proc argument is +|data|+.
+    # 3. +:format_err+ Format err. Proc argument is +|data|+. The proc must  remove the key +:err+
+    class Customizable < Ougai::Formatters::Base
+      class << self
+        # Define the default main log message formatting to use. A non-null
+        # color configuration has to be provided. The configuration can however
+        # be empty
+        #
+        # @param [Ougai::Formatters::Colors::Configuration] color_config the 
+        #         color configuration to use
+        #
+        # @return [Proc] main message formatter
+        def default_msg_format(color_config)
+          proc do |severity, datetime, _progname, data|
+            msg = data.delete(:msg)
+            severity  = color_config.color(:severity, severity, severity)
+            datetime  = color_config.color(:datetime, datetime, severity)
+            msg       = color_config.color(:msg, msg, severity)
+
+            "[#{datetime}] #{severity}: #{msg}"
+          end
+        end
+
+        # Define the default error formatting to use which handles field
+        # exclusion and plain mode for awesome-print
+        #
+        # @param [Array<Symbol>] excluded_fields list of key to exclude from
+        #         +data+ before printing logs
+        # @param [Boolean] plain parameter to define if Awesome-Print renders
+        #         in plain mode or not
+        #
+        # @return [Proc] data formatter
+        def default_data_format(excluded_fields, plain)
+          proc do |data|
+            excluded_fields.each { |field| data.delete(field) }
+            next nil if data.empty?
+
+            data.ai(plain: plain)
+          end
+        end
+
+        # Define the default error formatting to use.
+        #
+        # @param [Integer] trace_indent space indentation to prepend before 
+        #         trace content
+        #
+        # @return [Proc] error formatter
+        def default_err_format(trace_indent = 4)
+          proc do |data|
+            next nil unless data.key?(:err)
+
+            err = data.delete(:err)
+            err_str = "  #{err[:name]} (#{err[:message]}):"
+            err_str += "\n" + (' ' * trace_indent) + err[:stack] if err.key?(:stack)
+            err_str
+          end
+        end
+      end
+
+      # Intialize a formatter
+      #
+      # @param [String] app_name application name (execution program name if nil)
+      # @param [String] hostname hostname (hostname if nil)
+      # @param [Hash] opts the initial values of attributes
+      # @option opts [String] :trace_max_lines (100) the value of 
+      #         trace_max_lines attribute
+      # @option opts [String] :plain (false) the value of plain attribute
+      # @option opts [String] :excluded_fields ([]) the value of 
+      #         excluded_fields attribute
+      # @option opts [Ougai::Formatters::Colors::Configuration] :color_config
+      #         assign a color configuration.
+      # @option opts [Proc] :format_msg main message formatter
+      # @option opts [Proc] :format_data data formatter
+      # @option opts [Proc] :format_err error formatter
+      def initialize(app_name = nil, hostname = nil, opts = {})
+        aname, hname, opts = Base.parse_new_params([app_name, hostname, opts])
+        super(aname, hname, opts)
+
+        # Message logging
+        color_config = opts.fetch(:color_config) {
+          color_config = Ougai::Formatters::Colors::Configuration.new({})
+        }
+        @format_msg = opts.fetch(:format_msg) {
+          Customizable.default_msg_format(color_config)
+        }
+
+        # Data logging
+        plain = opts.fetch(:plain) { false }
+        excluded_fields = opts[:excluded_fields] || []
+        @format_data = opts.fetch(:format_data) {
+          Customizable.default_data_format(excluded_fields, plain)
+        }
+
+        # Error logging
+        trace_indent = opts.fetch(:trace_indent) { 4 }
+        @format_err = opts.fetch(:format_err) {
+          Customizable.default_err_format(trace_indent)
+        }
+
+        # Ensure dependency are present
+        load_dependent
+      end
+
+      # Format a log entry
+      #
+      # @param [String] severity log severity, in capital letters
+      # @param [Time] time timestamp of the log. Is formatted by +strftime+
+      # @param [String] progname optional program name
+      # @param [Hash] data log data. Main message is stored under the key +:msg+
+      #         while errors are logged under the key +:err+.
+      # 
+      # @return [String] log text, ready to be printed out
+      def _call(severity, time, progname, data)
+        strs = ''.dup
+        # Main message
+        dt =  format_datetime(time)
+        msg_str = @format_msg.call(severity, dt, progname, data)
+        strs.concat(msg_str)
+
+        # Error: displayed before additional data
+        err_str = @format_err.call(data)
+        strs.concat("\n").concat(err_str) unless err_str.nil?
+
+        # Additional data
+        data_str = @format_data.call(data)
+        strs.concat("\n").concat(data_str) unless data_str.nil?
+
+        strs.concat("\n")
+      end
+
+      protected
+
+      # Ensure +awesompe_print+ is loaded
+      def load_dependent
+        require 'awesome_print'
+      rescue LoadError
+        puts 'You must install the awesome_print gem to use this output.'
+        raise
+      end
+    end
+  end
+end

data/lib/ougai/formatters/customizable/version.rb

@@ -1,7 +1,8 @@
-# frozen_string_literal: true
-
-module Ougai
-  module Formatters
-    CUSTOMIZABLE_VERSION = '0.1.0'
-  end
-end
+# frozen_string_literal: true
+
+module Ougai
+  module Formatters
+    # Customizable extension version
+    CUSTOMIZABLE_VERSION = '1.0.0'
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ougai-formatters-customizable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Al-un
@@ -92,6 +92,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |2
       This library aims at providing a fully flexible formatter compatible with the
       Ougai library. Customization is about colorization and log formatting.