dry-logger 1.0.0.rc2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5c096685f8199a216c865178cc4a5633975fa45e9b158e0a25254ec8edaa6b5
-  data.tar.gz: 48e24dcd35809d47677964fe48df6d9e6c32bc0bda00cbfe3ee0e0dd76681660
+  metadata.gz: 730cb488952659e0a7499948d6f77e3ed61b7be38e462d7a000479d7e6a8c7f2
+  data.tar.gz: 81ddc5b02fc960cb3650f1305e19bfc33d21488722455c8bfdcb3e411cb07bf4
 SHA512:
-  metadata.gz: f298b5262eb94c6312122519bfcc17ced78512dfe53fe1db097c95aa68aa6cf717e7da0bde929e74c6d5df9f58938ce22e4e66167d96031e9d1530baded90311
-  data.tar.gz: e8413dddf934581b0fadaca47c108f53145ba8a5ad4603d9b02cfa0a6fbe89c1b29c933c51205a5e171619e69502a3e1f9658e6b19b763306e52f04768b4c0ce
+  metadata.gz: 02d8e2eb6e2029a3c29269db001e5e3f50eacf1605efa4cdd62ae01a1e8349b80073e0b591761ed3bc82f7acda5b139a2a03c120c32b3716c27c2d054eee0a64
+  data.tar.gz: 2f11fec53ac321f0157f3c620944d460a189fa4da112a5b2d617a21171533dcacf17370bf1288d2ef1e4574ab4f35518aca2e280a7063df669768d1c3dda73b6

data/CHANGELOG.md

@@ -1,13 +1,27 @@
 <!--- DO NOT EDIT THIS FILE - IT'S AUTOMATICALLY GENERATED VIA DEVTOOLS --->
 
-## 1.0.0.rc1 2022-11-07
+## 1.0.0 
 
 This is a port of the original Hanami logger from hanami-utils extended with support for logging
-dispatchers that can log to different destinations.
+dispatchers that can log to different destinations and plenty more.
 
 
 ### Added
 
+- Support arbitrary logging backends through proxy (via #12) (@solnic)
+- Support for conditional logging when using arbitrary logging backends (via #13) (@solnic)
+- Support for registering templates via `Dry::Logger.register_template` (via #14) (@solnic)
+- Support for payload keys as template tokens (via #14) (@solnic)
+- Support for payload value formatter methods, ie if there's `:verb` token your formatter can implement `format_verb(value)` (via #14) (@solnic)
+- Support block-based setup (via #16) (@solnic)
+- Support for defining cherry-picked keys from the payload in string templates (via #17) (@solnic)
+- Support for `%<payload>s` template token. It will be replaced by a formatted payload, excluding any key that you specified explicitly in the template (via #17) (@solnic)
+- Support for colorized output using color tags in templates (via #18) (@solnic)
+- Support for `colorize: true` logger option which enables severity coloring in string formatter (via #18) (@solnic)
+- `:details` template: `"[%<progname>s] [%<severity>s] [%<time>s] %<message>s %<payload>s"` (@solnic)
+- A new option `on_crash` for setting up a logger-crash handling proc (via #21) (@solnic)
+- Handle logger crashes by default using a simple `$stdout` logger (via #21) (@solnic)
+- Support for regular logger backends that don't support `log?` predicate (@solnic)
 - Support for providing a string template for log entries via `template` option (via #7) (@solnic)
 - `:rack` string log formatter which inlines request info and displays params at the end (@solnic)
 - Conditional log dispatch via `#log_if` backend's predicate (via #9) (@solnic)

data/lib/dry/logger/backends/core.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "dry/logger/constants"
+
+module Dry
+  module Logger
+    module Backends
+      module Core
+        # Return a proc used by the log? predicate
+        #
+        # @since 1.0.0
+        # @api private
+        attr_reader :log_if
+
+        # Set a predicate proc that checks if an entry should be logged by a given backend
+        #
+        # The predicate will receive {Entry} as its argument and should return true/false
+        #
+        # @param [Proc, #to_proc] spec A proc-like object
+        # @since 1.0.0
+        # @api public
+        def log_if=(spec)
+          @log_if = spec&.to_proc
+        end
+
+        # @since 1.0.0
+        # @api private
+        def log?(entry)
+          if log_if
+            log_if.call(entry)
+          else
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/logger/backends/proxy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+require "dry/logger/constants"
+require "dry/logger/backends/core"
+
+module Dry
+  module Logger
+    module Backends
+      # Logger proxy is used for regular loggers that don't work with log entries
+      #
+      # @since 1.0.0
+      # @api private
+      class Proxy < SimpleDelegator
+        include Core
+
+        # @since 0.1.0
+        # @api public
+        attr_accessor :log_if
+
+        LOG_METHODS.each do |method|
+          define_method(method) { |entry| __getobj__.public_send(method, entry.message) }
+        end
+
+        # @since 1.0.0
+        # @api private
+        def log?(entry)
+          if log_if
+            log_if.call(entry)
+          else
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/logger/backends/stream.rb

@@ -3,11 +3,14 @@
 require "logger"
 
 require "dry/logger/constants"
+require "dry/logger/backends/core"
 
 module Dry
   module Logger
     module Backends
       class Stream < ::Logger
+        include Core
+
         # @since 0.1.0
         # @api private
         attr_reader :stream
@@ -16,10 +19,6 @@ module Dry
         # @api private
         attr_reader :level
 
-        # @since 0.1.0
-        # @api public
-        attr_accessor :log_if
-
         # @since 0.1.0
         # @api private
         def initialize(stream:, formatter:, level: DEFAULT_LEVEL, progname: nil, log_if: nil)
@@ -33,13 +32,9 @@ module Dry
         end
 
         # @since 1.0.0
-        # @api private
-        def log?(entry)
-          if log_if
-            log_if.call(entry)
-          else
-            true
-          end
+        # @api public
+        def inspect
+          %(#<#{self.class} stream=#{stream} level=#{level} log_if=#{log_if}>)
         end
       end
     end

data/lib/dry/logger/clock.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Dry
+  module Logger
+    # @since 1.0.0
+    # @api private
+    class Clock
+      # @since 1.0.0
+      # @api private
+      attr_reader :unit
+
+      # @since 1.0.0
+      # @api private
+      def initialize(unit: :nanosecond)
+        @unit = unit
+      end
+
+      # @since 1.0.0
+      # @api private
+      def now
+        Time.now
+      end
+
+      # @since 1.0.0
+      # @api private
+      def now_utc
+        now.getutc
+      end
+
+      # @since 1.0.0
+      # @api private
+      def measure
+        start = current
+        result = yield
+        [result, current - start]
+      end
+
+      private
+
+      # @since 1.0.0
+      # @api private
+      def current
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, unit)
+      end
+    end
+  end
+end

data/lib/dry/logger/constants.rb

@@ -4,22 +4,67 @@ require "logger"
 
 module Dry
   module Logger
-    LOG_METHODS = %i[debug error fatal info warn].freeze
+    # @since 1.0.0
+    # @api private
+    NEW_LINE = $/ # rubocop:disable Style/SpecialGlobalVars
+
+    # @since 1.0.0
+    # @api private
+    SEPARATOR = " "
+
+    # @since 1.0.0
+    # @api private
+    TAB = SEPARATOR * 2
+
+    # @since 1.0.0
+    # @api private
+    EMPTY_ARRAY = [].freeze
 
+    # @since 1.0.0
+    # @api private
+    EMPTY_HASH = {}.freeze
+
+    # @since 1.0.0
+    # @api private
+    LOG_METHODS = %i[debug info warn error fatal unknown].freeze
+
+    # @since 1.0.0
+    # @api private
     BACKEND_METHODS = %i[close].freeze
 
+    # @since 1.0.0
+    # @api private
     DEBUG = ::Logger::DEBUG
+
+    # @since 1.0.0
+    # @api private
     INFO = ::Logger::INFO
+
+    # @since 1.0.0
+    # @api private
     WARN = ::Logger::WARN
+
+    # @since 1.0.0
+    # @api private
     ERROR = ::Logger::ERROR
+
+    # @since 1.0.0
+    # @api private
     FATAL = ::Logger::FATAL
+
+    # @since 1.0.0
+    # @api private
     UNKNOWN = ::Logger::UNKNOWN
 
+    # @since 1.0.0
+    # @api private
     LEVEL_RANGE = (DEBUG..UNKNOWN).freeze
 
+    # @since 1.0.0
+    # @api private
     DEFAULT_LEVEL = INFO
 
-    # @since 0.1.0
+    # @since 1.0.0
     # @api private
     LEVELS = Hash
       .new { |levels, key|
@@ -35,9 +80,16 @@ module Dry
       )
       .freeze
 
-    DEFAULT_OPTS = {level: DEFAULT_LEVEL, formatter: nil, progname: nil}.freeze
+    # @since 1.0.0
+    # @api private
+    DEFAULT_OPTS = {level: DEFAULT_LEVEL, formatter: nil, progname: nil, log_if: nil}.freeze
 
+    # @since 1.0.0
+    # @api private
     BACKEND_OPT_KEYS = DEFAULT_OPTS.keys.freeze
+
+    # @since 1.0.0
+    # @api private
     FORMATTER_OPT_KEYS = %i[filter].freeze
   end
 end

data/lib/dry/logger/dispatcher.rb

@@ -4,6 +4,7 @@ require "logger"
 require "pathname"
 
 require "dry/logger/constants"
+require "dry/logger/backends/proxy"
 require "dry/logger/entry"
 
 module Dry
@@ -37,21 +38,48 @@ module Dry
       # @api private
       attr_reader :options
 
+      # @since 1.0.0
+      # @api private
+      attr_reader :clock
+
+      # @since 1.0.0
+      # @api private
+      attr_reader :on_crash
+
       # @since 1.0.0
       # @api private
       attr_reader :mutex
 
+      # @since 1.0.0
+      # @api private
+      CRASH_LOGGER = ::Logger.new($stdout).tap { |logger|
+        logger.formatter = -> (_, _, _, message) { "#{message}#{NEW_LINE}" }
+        logger.level = FATAL
+      }.freeze
+
+      # @since 1.0.0
+      # @api private
+      ON_CRASH = -> (progname:, exception:, message:, payload:) {
+        CRASH_LOGGER.fatal(Logger.templates[:crash] % {
+          severity: "FATAL",
+          progname: progname,
+          time: Time.now,
+          log_entry: [message, payload].map(&:to_s).reject(&:empty?).join(SEPARATOR),
+          exception: exception.class,
+          message: exception.message,
+          backtrace: TAB + exception.backtrace.join(NEW_LINE + TAB)
+        })
+      }
+
       # Set up a dispatcher
       #
       # @since 1.0.0
-      #
-      # @param [String, Symbol] id The dispatcher id, can be used as progname in log entries
-      # @param [Hash] options Options that can be used for both the backend and formatter
+      # @api private
       #
       # @return [Dispatcher]
-      # @api public
       def self.setup(id, **options)
         dispatcher = new(id, **DEFAULT_OPTS, **options)
+        yield(dispatcher) if block_given?
         dispatcher.add_backend if dispatcher.backends.empty?
         dispatcher
       end
@@ -64,12 +92,17 @@ module Dry
 
       # @since 1.0.0
       # @api private
-      def initialize(id, backends: [], context: self.class.default_context, **options)
+      def initialize(
+        id, backends: [], tags: [], context: self.class.default_context, **options
+      )
         @id = id
         @backends = backends
         @options = {**options, progname: id}
         @mutex = Mutex.new
         @context = context
+        @tags = tags
+        @clock = Clock.new(**(options[:clock] || EMPTY_HASH))
+        @on_crash = options[:on_crash] || ON_CRASH
       end
 
       # Log an entry with UNKNOWN severity
@@ -143,8 +176,25 @@ module Dry
 
       # Pass logging to all configured backends
       #
+      # @example logging a message
+      #   logger.log(:info, "Hello World")
+      #
+      # @example logging payload
+      #   logger.log(:info, verb: "GET", path: "/users")
+      #
+      # @example logging message and payload
+      #   logger.log(:info, "User index request", verb: "GET", path: "/users")
+      #
+      # @example logging exception
+      #   begin
+      #     # things that may raise
+      #   rescue => e
+      #     logger.log(:error, e)
+      #     raise e
+      #   end
+      #
       # @param [Symbol] severity The log severity name
-      # @param [String,Symbol,Array] message Optional message object
+      # @param [String] message Optional message
       # @param [Hash] payload Optional log entry payload
       #
       # @since 1.0.0
@@ -155,17 +205,24 @@ module Dry
         when Hash then log(severity, nil, **message)
         else
           entry = Entry.new(
+            clock: clock,
             progname: id,
             severity: severity,
+            tags: @tags,
             message: message,
             payload: {**context, **payload}
           )
 
           each_backend do |backend|
-            backend.__send__(severity, entry) if !backend.respond_to?(:log?) || backend.log?(entry)
+            backend.__send__(severity, entry) if backend.log?(entry)
+          rescue StandardError => e
+            on_crash.(progname: id, exception: e, message: message, payload: payload)
           end
         end
 
+        true
+      rescue StandardError => e
+        on_crash.(progname: id, exception: e, message: message, payload: payload)
         true
       end
 
@@ -182,11 +239,11 @@ module Dry
       #
       # @since 1.0.0
       # @api public
-      def tagged(tag)
-        context[:tag] = tag
+      def tagged(*tags)
+        @tags.concat(tags)
         yield
       ensure
-        context.delete(:tag)
+        @tags = []
       end
 
       # Add a new backend to an existing dispatcher
@@ -200,15 +257,27 @@ module Dry
       # @return [Dispatcher]
       # @api public
       def add_backend(instance = nil, **backend_options)
-        backend = instance || Dry::Logger.new(**options, **backend_options)
+        backend =
+          case (instance ||= Dry::Logger.new(**options, **backend_options))
+          when Backends::Stream then instance
+          else Backends::Proxy.new(instance)
+          end
+
         yield(backend) if block_given?
+
         backends << backend
         self
       end
 
+      # @since 1.0.0
+      # @api public
+      def inspect
+        %(#<#{self.class} id=#{id} options=#{options} backends=#{backends}>)
+      end
+
       # @since 1.0.0
       # @api private
-      def each_backend(*_args, &block)
+      def each_backend(&block)
         mutex.synchronize do
           backends.each(&block)
         end

data/lib/dry/logger/entry.rb

@@ -10,14 +10,6 @@ module Dry
     class Entry
       include Enumerable
 
-      # @since 1.0.0
-      # @api private
-      EMPTY_PAYLOAD = {}.freeze
-
-      # @since 1.0.0
-      # @api private
-      EMPTY_BACKTRACE = [].freeze
-
       # @since 1.0.0
       # @api public
       attr_reader :progname
@@ -28,16 +20,19 @@ module Dry
 
       # @since 1.0.0
       # @api public
-      attr_reader :level
+      attr_reader :tags
 
       # @since 1.0.0
       # @api public
-      attr_reader :time
+      attr_reader :level
 
       # @since 1.0.0
       # @api public
       attr_reader :message
-      alias_method :exception, :message
+
+      # @since 1.0.0
+      # @api public
+      attr_reader :exception
 
       # @since 1.0.0
       # @api public
@@ -45,14 +40,23 @@ module Dry
 
       # @since 1.0.0
       # @api private
-      def initialize(progname:, severity:, time: Time.now, message: nil, payload: EMPTY_PAYLOAD)
+      attr_reader :clock
+
+      # @since 1.0.0
+      # @api private
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(clock:, progname:, severity:, tags: EMPTY_ARRAY, message: nil,
+                     payload: EMPTY_HASH)
+        @clock = clock
         @progname = progname
-        @severity = severity.to_s.upcase # TODO: this doesn't feel right
+        @severity = severity.to_s
+        @tags = tags
         @level = LEVELS.fetch(severity.to_s)
-        @time = time
-        @message = message
+        @message = message unless message.is_a?(Exception)
+        @exception = message if message.is_a?(Exception)
         @payload = build_payload(payload)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # @since 1.0.0
       # @api public
@@ -99,7 +103,7 @@ module Dry
       # @since 1.0.0
       # @api public
       def exception?
-        message.is_a?(Exception)
+        !exception.nil?
       end
 
       # @since 1.0.0
@@ -109,28 +113,21 @@ module Dry
       end
 
       # @since 1.0.0
-      # @api private
-      def to_h
-        @to_h ||= meta.merge(payload)
+      # @api public
+      def tag?(value)
+        tags.include?(value)
       end
 
       # @since 1.0.0
       # @api private
       def meta
-        @meta ||= {progname: progname, severity: severity, time: time}
+        @meta ||= {progname: progname, severity: severity, time: clock.now}
       end
 
       # @since 1.0.0
       # @api private
-      def utc_time
-        @utc_time ||= time.utc.iso8601
-      end
-
-      # @since 1.0.0
-      # @api private
-      def as_json
-        # TODO: why are we enforcing UTC in JSON but not in String?
-        @as_json ||= to_h.merge(message: message, time: utc_time).compact
+      def to_h
+        @to_h ||= meta.merge(message: message, **payload)
       end
 
       # @since 1.0.0
@@ -146,10 +143,7 @@ module Dry
       # @api private
       def build_payload(payload)
         if exception?
-          {message: exception.message,
-           backtrace: exception.backtrace || EMPTY_BACKTRACE,
-           error: exception.class,
-           **payload}
+          {exception: exception, **payload}
         else
           payload
         end

data/lib/dry/logger/formatters/colors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Dry
+  module Logger
+    module Formatters
+      # Shell colorizer
+      #
+      # This was ported from hanami-utils
+      #
+      # @since 1.0.0
+      # @api private
+      class Colors
+        # Unknown color code error
+        #
+        # @since 1.0.0
+        class UnknownColorCodeError < StandardError
+          def initialize(code)
+            super("Unknown color code: `#{code.inspect}'")
+          end
+        end
+
+        # Escapes codes for terminals to output strings in colors
+        #
+        # @since 1.2.0
+        # @api private
+        COLORS = {black: 30,
+                  red: 31,
+                  green: 32,
+                  yellow: 33,
+                  blue: 34,
+                  magenta: 35,
+                  cyan: 36,
+                  gray: 37}.freeze
+
+        # @api private
+        def self.evaluate(input)
+          COLORS.keys.reduce(input.dup) { |output, color|
+            output.gsub!("<#{color}>", start(color))
+            output.gsub!("</#{color}>", stop)
+            output
+          }
+        end
+
+        # Colorizes output
+        # 8 colors available: black, red, green, yellow, blue, magenta, cyan, and gray
+        #
+        # @param input [#to_s] the string to colorize
+        # @param color [Symbol] the color
+        #
+        # @raise [UnknownColorError] if the color code is unknown
+        #
+        # @return [String] the colorized string
+        #
+        # @since 1.0.0
+        # @api private
+        def self.call(color, input)
+          "#{start(color)}#{input}#{stop}"
+        end
+
+        # @since 1.0.0
+        # @api private
+        def self.start(color)
+          "\e[#{self[color]}m"
+        end
+
+        # @since 1.0.0
+        # @api private
+        def self.stop
+          "\e[0m"
+        end
+
+        # Helper method to translate between color names and terminal escape codes
+        #
+        # @since 1.0.0
+        # @api private
+        #
+        # @raise [UnknownColorError] if the color code is unknown
+        def self.[](code)
+          COLORS.fetch(code) { raise UnknownColorCodeError, code }
+        end
+      end
+    end
+  end
+end

data/lib/dry/logger/formatters/json.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
+
+require "dry/logger/constants"
 require "dry/logger/formatters/structured"
 
 module Dry
@@ -16,7 +18,31 @@ module Dry
         # @since 0.1.0
         # @api private
         def format(entry)
-          "#{::JSON.generate(entry.as_json)}#{NEW_LINE}"
+          hash = format_values(entry).compact
+          hash.update(hash.delete(:exception)) if entry.exception?
+          ::JSON.dump(hash)
+        end
+
+        # @since 0.1.0
+        # @api private
+        def format_severity(value)
+          value.upcase
+        end
+
+        # @since 0.1.0
+        # @api private
+        def format_exception(value)
+          {
+            exception: value.class,
+            message: value.message,
+            backtrace: value.backtrace || EMPTY_ARRAY
+          }
+        end
+
+        # @since 0.1.0
+        # @api private
+        def format_time(value)
+          value.getutc.iso8601
         end
       end
     end

data/lib/dry/logger/formatters/rack.rb

@@ -12,10 +12,18 @@ module Dry
       #
       # @see String
       class Rack < String
+        # @see String#initialize
         # @since 1.0.0
         # @api private
-        def format_entry(entry)
-          [*entry.payload.except(:params).values, entry[:params]].compact.join(SEPARATOR)
+        def initialize(**options)
+          super
+          @template = Template[Logger.templates[:rack]]
+        end
+
+        # @api 1.0.0
+        # @api private
+        def format_params(value)
+          return value unless value.empty?
         end
       end
     end

data/lib/dry/logger/formatters/string.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require "dry/logger/formatters/structured"
+require "set"
+
+require_relative "template"
+require_relative "structured"
 
 module Dry
   module Logger
@@ -12,10 +15,6 @@ module Dry
       # @since 1.0.0
       # @api public
       class String < Structured
-        # @since 1.0.0
-        # @api private
-        SEPARATOR = " "
-
         # @since 1.0.0
         # @api private
         HASH_SEPARATOR = ","
@@ -24,9 +23,16 @@ module Dry
         # @api private
         EXCEPTION_SEPARATOR = ": "
 
-        # @since 1.0.0
+        # @since 1.2.0
         # @api private
-        DEFAULT_TEMPLATE = "%<message>s"
+        DEFAULT_SEVERITY_COLORS = {
+          DEBUG => :cyan,
+          INFO => :magenta,
+          WARN => :yellow,
+          ERROR => :red,
+          FATAL => :red,
+          UNKNOWN => :blue
+        }.freeze
 
         # @since 1.0.0
         # @api private
@@ -34,47 +40,108 @@ module Dry
 
         # @since 1.0.0
         # @api private
-        def initialize(template: DEFAULT_TEMPLATE, **options)
+        def initialize(template: Logger.templates[:default], **options)
           super(**options)
-          @template = template
+          @template = Template[template]
+        end
+
+        # @since 1.0.0
+        # @api private
+        def colorize?
+          options[:colorize].equal?(true)
         end
 
         private
 
         # @since 1.0.0
         # @api private
-        def format(entry)
-          "#{template % entry.meta.merge(message: format_entry(entry))}#{NEW_LINE}"
+        def format_severity(value)
+          output = value.upcase
+
+          if colorize?
+            Colors.call(severity_colors[LEVELS[value]], output)
+          else
+            output
+          end
         end
 
         # @since 1.0.0
         # @api private
-        def format_entry(entry)
+        def format(entry)
           if entry.exception?
-            format_exception(entry)
-          elsif entry.message
-            if entry.payload.empty?
-              entry.message
-            else
-              "#{entry.message}#{SEPARATOR}#{format_payload(entry)}"
-            end
+            head = template % template_data(entry, exclude: %i[exception])
+            tail = format_exception(entry.exception)
+
+            "#{head}#{NEW_LINE}#{TAB}#{tail}"
           else
-            format_payload(entry)
+            template % template_data(entry)
           end
         end
 
         # @since 1.0.0
         # @api private
-        def format_exception(entry)
-          hash = entry.payload
-          message = hash.values_at(:error, :message).compact.join(EXCEPTION_SEPARATOR)
-          "#{message}#{NEW_LINE}#{hash[:backtrace].map { |line| "from #{line}" }.join(NEW_LINE)}"
+        def format_tags(value)
+          Array(value)
+            .map { |tag|
+              case tag
+              when Hash then format_payload(tag)
+              else
+                tag.to_s
+              end
+            }
+            .join(SEPARATOR)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def format_exception(value)
+          [
+            "#{value.message} (#{value.class})",
+            format_backtrace(value.backtrace || EMPTY_BACKTRACE)
+          ].join(NEW_LINE)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def format_payload(payload)
+          payload.map { |key, value| "#{key}=#{value.inspect}" }.join(SEPARATOR)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def format_backtrace(value)
+          value.map { |line| "#{TAB}#{line}" }.join(NEW_LINE)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def template_data(entry, exclude: EMPTY_ARRAY)
+          data = format_values(entry)
+          payload = data.except(:message, *entry.meta.keys, *template.tokens, *exclude)
+          data[:payload] = format_payload(payload)
+
+          if template.include?(:tags)
+            data[:tags] = format_tags(entry.tags)
+          end
+
+          if data[:message]
+            data.except(*payload.keys)
+          elsif template.include?(:message)
+            data[:message] = data.delete(:payload)
+            data[:payload] = nil
+            data
+          else
+            data
+          end
         end
 
         # @since 1.0.0
         # @api private
-        def format_payload(entry)
-          entry.map { |key, value| "#{key}=#{value.inspect}" }.join(HASH_SEPARATOR)
+        def severity_colors
+          @severity_colors ||= DEFAULT_SEVERITY_COLORS.merge(
+            (options[:severity_colors] || EMPTY_HASH)
+              .to_h { |key, value| [LEVELS[key.to_s], value] }
+          )
         end
       end
     end

data/lib/dry/logger/formatters/structured.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "logger"
+
+require "dry/logger/constants"
 require "dry/logger/filter"
 
 module Dry
@@ -8,6 +10,8 @@ module Dry
     module Formatters
       # Default structured formatter which receives {Logger::Entry} from the backends.
       #
+      # This class can be used as the base class for your custom formatters.
+      #
       # @see http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger/Formatter.html
       #
       # @since 1.0.0
@@ -21,10 +25,6 @@ module Dry
         # @api private
         NOOP_FILTER = -> message { message }
 
-        # @since 1.0.0
-        # @api private
-        NEW_LINE = $/ # rubocop:disable Style/SpecialGlobalVars
-
         # @since 1.0.0
         # @api private
         attr_reader :filter
@@ -52,7 +52,7 @@ module Dry
         # @return [String]
         # @api public
         def call(_severity, _time, _progname, entry)
-          format(entry.filter(filter))
+          format(entry.filter(filter)) + NEW_LINE
         end
 
         # Format entry into a loggable object
@@ -63,7 +63,18 @@ module Dry
         # @return [Entry]
         # @api public
         def format(entry)
+          format_values(entry)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def format_values(entry)
           entry
+            .to_h
+            .map { |key, value|
+              [key, respond_to?(meth = "format_#{key}", true) ? __send__(meth, value) : value]
+            }
+            .to_h
         end
       end
     end

data/lib/dry/logger/formatters/template.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "set"
+require "dry/logger/constants"
+require_relative "colors"
+
+module Dry
+  module Logger
+    module Formatters
+      # Basic string formatter.
+      #
+      # This formatter returns log entries in key=value format.
+      #
+      # @since 1.0.0
+      # @api public
+      class Template
+        # @since 1.0.0
+        # @api private
+        TOKEN_REGEXP = /%<(\w*)>s/.freeze
+
+        # @since 1.0.0
+        # @api private
+        MESSAGE_TOKEN = "%<message>s"
+
+        # @since 1.0.0
+        # @api private
+        attr_reader :value
+
+        # @since 1.0.0
+        # @api private
+        attr_reader :tokens
+
+        # @since 1.0.0
+        # @api private
+        def self.[](value)
+          cache.fetch(value) {
+            cache[value] = (colorized?(value) ? Template::Colorized : Template).new(value)
+          }
+        end
+
+        # @since 1.0.0
+        # @api private
+        private_class_method def self.colorized?(value)
+          Colors::COLORS.keys.any? { |color| value.include?("<#{color}>") }
+        end
+
+        # @since 1.0.0
+        # @api private
+        private_class_method def self.cache
+          @cache ||= {}
+        end
+
+        # @since 1.0.0
+        # @api private
+        class Colorized < Template
+          # @since 1.0.0
+          # @api private
+          def initialize(value)
+            super(Colors.evaluate(value))
+          end
+        end
+
+        # @since 1.0.0
+        # @api private
+        def initialize(value)
+          @value = value
+          @tokens = value.scan(TOKEN_REGEXP).flatten(1).map(&:to_sym).to_set
+        end
+
+        # @since 1.0.0
+        # @api private
+        def %(tokens)
+          output = value % tokens
+          output.strip!
+          output.split(NEW_LINE).map(&:rstrip).join(NEW_LINE)
+        end
+
+        # @since 1.0.0
+        # @api private
+        def colorize(color, input)
+          "\e[#{Colors[color.to_sym]}m#{input}\e[0m"
+        end
+
+        # @since 1.0.0
+        # @api private
+        def include?(token)
+          tokens.include?(token)
+        end
+      end
+    end
+  end
+end

data/lib/dry/logger/global.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Dry
+  module Logger
+    # Global setup methods
+    #
+    # @api public
+    module Global
+      # Register a new formatter
+      #
+      # @example
+      #   class MyFormatter < Dry::Logger::Formatters::Structured
+      #     def format_message(value)
+      #       "WOAH: #{message}"
+      #     end
+      #
+      #     def format_time(value)
+      #       Time.now.strftime("%Y-%m-%d %H:%M:%S")
+      #     end
+      #   end
+      #
+      #   Dry::Logger.register_formatter(:my_formatter, MyFormatter)
+      #
+      #   logger = Dry.Logger(:app, formatter: :my_formatter, template: :details)
+      #
+      #   logger.info "Hello World"
+      #   # [test] [INFO] [2022-11-15 10:06:29] WOAH: Hello World
+      #
+      # @since 1.0.0
+      # @return [Hash]
+      # @api public
+      def register_formatter(name, formatter)
+        formatters[name] = formatter
+        formatters
+      end
+
+      # Register a new template
+      #
+      # @example basic template
+      #   Dry::Logger.register_template(:request, "[%<severity>s] %<verb>s %<path>s")
+      #
+      #   logger = Dry.Logger(:my_app, template: :request)
+      #
+      #   logger.info(verb: "GET", path: "/users")
+      #   # [INFO] GET /users
+      #
+      # @example template with colors
+      #   Dry::Logger.register_template(
+      #     :request, "[%<severity>s] <green>%<verb>s</green> <blue>%<path>s</blue>"
+      #   )
+      #
+      # @since 1.0.0
+      # @return [Hash]
+      # @api public
+      def register_template(name, template)
+        templates[name] = template
+        templates
+      end
+
+      # Build a logging backend instance
+      #
+      # @since 1.0.0
+      # @return [Backends::Stream]
+      # @api private
+      def new(stream: $stdout, **options)
+        backend =
+          case stream
+          when IO, StringIO then Backends::IO
+          when String, Pathname then Backends::File
+          else
+            raise ArgumentError, "unsupported stream type #{stream.class}"
+          end
+
+        formatter_spec = options[:formatter]
+        template_spec = options[:template]
+
+        template =
+          case template_spec
+          when Symbol then templates.fetch(template_spec)
+          when String then template_spec
+          when nil then templates[:default]
+          else
+            raise ArgumentError,
+                  ":template option must be a Symbol or a String (`#{template_spec}` given)"
+          end
+
+        formatter_options = {**options, template: template}
+
+        formatter =
+          case formatter_spec
+          when Symbol then formatters.fetch(formatter_spec).new(**formatter_options)
+          when Class then formatter_spec.new(**formatter_options)
+          when nil then formatters[:string].new(**formatter_options)
+          when ::Logger::Formatter then formatter_spec
+          else
+            raise ArgumentError, "Unsupported formatter option #{formatter_spec.inspect}"
+          end
+
+        backend_options = options.select { |key, _| BACKEND_OPT_KEYS.include?(key) }
+
+        backend.new(stream: stream, **backend_options, formatter: formatter)
+      end
+
+      # Internal formatters registry
+      #
+      # @since 1.0.0
+      # @api private
+      def formatters
+        @formatters ||= {}
+      end
+
+      # Internal templates registry
+      #
+      # @since 1.0.0
+      # @api private
+      def templates
+        @templates ||= {}
+      end
+    end
+  end
+end

data/lib/dry/logger/version.rb

@@ -2,6 +2,6 @@
 
 module Dry
   module Logger
-    VERSION = "1.0.0.rc2"
+    VERSION = "1.0.0"
   end
 end

data/lib/dry/logger.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "stringio"
-
+require "dry/logger/global"
 require "dry/logger/constants"
+require "dry/logger/clock"
 require "dry/logger/dispatcher"
 
 require "dry/logger/formatters/string"
@@ -42,74 +42,58 @@ module Dry
   #   logger.info(Hello: "World!")
   #   # {"progname":"my_app","severity":"INFO","time":"2022-11-06T10:11:29Z","Hello":"World!"}
   #
+  # @example Setting up multiple backends
+  #   logger = Dry.Logger(:my_app)
+  #     add_backend(formatter: :string, template: :details)
+  #     add_backend(formatter: :string, template: :details)
+  #
+  # @example Setting up conditional logging
+  #   logger = Dry.Logger(:my_app) { |setup|
+  #     setup.add_backend(formatter: :string, template: :details) { |b| b.log_if = :error?.to_proc }
+  #   }
+  #
+  # @param [String, Symbol] id The dispatcher id, can be used as progname in log entries
+  # @param [Hash] options Options for backends and formatters
+  # @option options [Symbol] :level (:info) The minimum level that should be logged,
+  # @option options [Symbol] :stream (optional) The output stream, default is $stdout
+  # @option options [Symbol, Class, #call] :formatter (:string) The default formatter or its id,
+  # @option options [String, Symbol] :template (:default) The default template that should be used
+  # @option options [Boolean] :colorize (false) Enable/disable colorized severity
+  # @option options [Hash<Symbol=>Symbol>] :severity_colors ({}) A severity=>color mapping
+  # @option options [#call] :on_crash (Dry::Logger::Dispatcher::ON_CRASH) A crash-handling proc.
+  #   This is used whenever logging crashes.
+  #
   # @since 1.0.0
-  # @return [Dispatcher]
   # @api public
-  def self.Logger(id, **opts, &block)
-    Logger::Dispatcher.setup(id, **opts, &block)
+  # @return [Dispatcher]
+  def self.Logger(id, **options, &block)
+    Logger::Dispatcher.setup(id, **options, &block)
   end
 
   module Logger
-    # Register a new formatter
-    #
-    # @example
-    #   class MyFormatter < Dry::Logger::Formatters::Structured
-    #     def format(entry)
-    #       "WOAH: #{entry.message}"
-    #     end
-    #   end
-    #
-    #   Dry::Logger.register_formatter(MyFormatter)
-    #
-    # @since 1.0.0
-    # @return [Hash]
-    # @api public
-    def self.register_formatter(name, formatter)
-      formatters[name] = formatter
-      formatters
-    end
-
-    # Build a logging backend instance
-    #
-    # @since 1.0.0
-    # @return [Backends::Stream]
-    # @api private
-    def self.new(stream: $stdout, **opts)
-      backend =
-        case stream
-        when IO, StringIO then Backends::IO
-        when String, Pathname then Backends::File
-        else
-          raise ArgumentError, "unsupported stream type #{stream.class}"
-        end
+    extend Global
 
-      formatter_opt = opts[:formatter]
-
-      formatter =
-        case formatter_opt
-        when Symbol then formatters.fetch(formatter_opt).new(**opts)
-        when Class then formatter_opt.new(**opts)
-        when NilClass then formatters[:string].new(**opts)
-        when ::Logger::Formatter then formatter_opt
-        else
-          raise ArgumentError, "unsupported formatter option #{formatter_opt.inspect}"
-        end
+    # Built-in formatters
+    register_formatter(:string, Formatters::String)
+    register_formatter(:rack, Formatters::Rack)
+    register_formatter(:json, Formatters::JSON)
 
-      backend_opts = opts.select { |key, _| BACKEND_OPT_KEYS.include?(key) }
+    # Built-in templates
+    register_template(:default, "%<message>s %<payload>s")
 
-      backend.new(stream: stream, **backend_opts, formatter: formatter)
-    end
+    register_template(:details, "[%<progname>s] [%<severity>s] [%<time>s] %<message>s %<payload>s")
 
-    # Internal formatters registry
-    #
-    # @since 1.0.0
-    # @api private
-    def self.formatters
-      @formatters ||= {}
-    end
+    register_template(:crash, <<~STR)
+      [%<progname>s] [%<severity>s] [%<time>s] Logging crashed
+        %<log_entry>s
+        %<message>s (%<exception>s)
+      %<backtrace>s
+    STR
 
-    register_formatter(:string, Formatters::String)
-    register_formatter(:rack, Formatters::Rack)
-    register_formatter(:json, Formatters::JSON)
+    register_template(:rack, <<~STR)
+      [%<progname>s] [%<severity>s] [%<time>s] \
+      %<verb>s %<status>s %<elapsed>s %<ip>s %<path>s %<length>s %<payload>s
+        %<params>s
+    STR
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-logger
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0
 platform: ruby
 authors:
 - Luca Guidi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-08 00:00:00.000000000 Z
+date: 2022-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -36,17 +36,23 @@ files:
 - README.md
 - dry-logger.gemspec
 - lib/dry/logger.rb
+- lib/dry/logger/backends/core.rb
 - lib/dry/logger/backends/file.rb
 - lib/dry/logger/backends/io.rb
+- lib/dry/logger/backends/proxy.rb
 - lib/dry/logger/backends/stream.rb
+- lib/dry/logger/clock.rb
 - lib/dry/logger/constants.rb
 - lib/dry/logger/dispatcher.rb
 - lib/dry/logger/entry.rb
 - lib/dry/logger/filter.rb
+- lib/dry/logger/formatters/colors.rb
 - lib/dry/logger/formatters/json.rb
 - lib/dry/logger/formatters/rack.rb
 - lib/dry/logger/formatters/string.rb
 - lib/dry/logger/formatters/structured.rb
+- lib/dry/logger/formatters/template.rb
+- lib/dry/logger/global.rb
 - lib/dry/logger/version.rb
 homepage: https://dry-rb.org/gems/dry-logger
 licenses:
@@ -67,9 +73,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.6
 signing_key: