debug_logging 4.0.0 → 4.0.2

data/lib/debug_logging/constants.rb

@@ -1,23 +1,27 @@
 module DebugLogging
   module Constants
     DEFAULT_ELLIPSIS = " ✂️ …"
+    DEFAULT_TIME_FORMATTER = ->(time) { "[#{time.strftime("%Y%m%d %H:%M:%S")}] " }
+    EVENT_TIME_FORMATTER = ->(time) { time.strftime("%F %T %z") }
     CONFIG_ATTRS_DEFAULTS = {
       enabled: true,
-      logger: Logger.new($stdout),
-      log_level: :debug,
+      logger: Logger.new($stdout), # probably want to override to be the Rails.logger
+      log_level: :debug, # at what level do the messages created by this gem sent at?
       multiple_last_hashes: false,
-      last_hash_to_s_proc: nil,
+      last_hash_to_s_proc: nil, # e.g. ->(hash) { "keys: #{hash.keys}" }
       last_hash_max_length: 1_000,
-      args_to_s_proc: nil,
+      args_to_s_proc: nil, # e.g. ->(*record) { "record id: #{record.first.id}" }
       args_max_length: 1_000,
-      colorized_chain_for_method: false,
-      colorized_chain_for_class: false,
-      add_invocation_id: true,
+      colorized_chain_for_method: false, # e.g. ->(colorized_string) { colorized_string.red.on_blue.underline }
+      colorized_chain_for_class: false,  # e.g. ->(colorized_string) { colorized_string.colorize(:light_blue ).colorize( :background => :red) }
+      add_invocation_id: true, # allows unique identification of method call; association of entry and exit log lines
       ellipsis: DEFAULT_ELLIPSIS,
       mark_scope_exit: false,
       add_payload: true, # Can also be a proc returning a string, which will be called when printing the payload
       payload_max_length: 1_000,
       error_handler_proc: nil,
+      time_formatter_proc: DEFAULT_TIME_FORMATTER,
+      add_timestamp: false,
     }.freeze
     CONFIG_ATTRS = CONFIG_ATTRS_DEFAULTS.keys
     CONFIG_READERS_DEFAULTS = {

data/lib/debug_logging/hooks.rb

@@ -3,12 +3,14 @@ require "timeout"
 
 module DebugLogging
   module Hooks
-    def self.included(mod)
-      mod.extend(ClassMethods)
-    end
+    class << self
+      def included(mod)
+        mod.extend(ClassMethods)
+      end
 
-    def self.extend(mod)
-      mod.extend(ClassMethods)
+      def extended(mod)
+        mod.extend(ClassMethods)
+      end
     end
 
     module ClassMethods

data/lib/debug_logging/instance_logger.rb

@@ -1,5 +1,33 @@
 module DebugLogging
   module InstanceLogger
+    class << self
+      def extended(base)
+        base.include(LambDartable::Log)
+      end
+    end
+
+    # NOTE: These params can be passed in / hidden in a last hash of *args
+    # NOTE: They can also be passed in discretely for each method, by passing *args as an array of arrays
+    # TODO: Refactor to use modern Ruby 3 *args, **kwargs instead
+    # @param logger [Logger] Logger.new($stdout), # probably want to override to be the Rails.logger
+    # @param log_level [Symbol] default: :debug, at what level do the messages created by this gem sent at?
+    # @param multiple_last_hashes [true, false] default: false,
+    # @param last_hash_to_s_proc [nil, Proc] default: nil, e.g. ->(hash) { "keys: #{hash.keys}" }
+    # @param last_hash_max_length [Integer] default: 1_000,
+    # @param args_to_s_proc [nil, Proc] default: nil, e.g. ->(*record) { "record id: #{record.first.id}" }
+    # @param args_max_length [Integer] default: 1_000,
+    # @param colorized_chain_for_method [false, Proc] default: false, e.g. ->(colorized_string) { colorized_string.red.on_blue.underline }
+    # @param colorized_chain_for_class [false, Proc] default: false, e.g. ->(colorized_string) { colorized_string.colorize(:light_blue ).colorize( :background => :red) }
+    # @param add_invocation_id [true, false] default: true, allows unique identification of method call; association of entry and exit log lines
+    # @param ellipsis [String] default: " ✂️ …".freeze,
+    # @param mark_scope_exit [true, false] default: false,
+    # @param add_payload [true, false, Proc] default: true, # Can also be a proc returning a string, which will be called when printing the payload
+    # @param payload_max_length [Integer] default: 1_000,
+    # @param error_handler_proc [nil, Proc] default: nil,
+    # @param time_formatter_proc [nil, Proc] default: DebugLogging::Constants::DEFAULT_TIME_FORMATTER,
+    # @param add_timestamp [true, false] default: false,
+    # @param instance_benchmarks [true, false] default: false,
+    # @param class_benchmarks [true, false] default: false,
     def i_logged(*methods_to_log)
       methods_to_log, payload, config_opts = DebugLogging::Util.extract_payload_and_config(
         method_names: methods_to_log,
@@ -7,9 +35,9 @@ module DebugLogging
         config: nil,
       )
       instance_method_modules =
-        Array(methods_to_log).map do |method_to_log|
+        Array(methods_to_log).map do |decorated_method|
           DebugLogging::InstanceLoggerModulizer.to_mod(
-            methods_to_log: Array(method_to_log),
+            methods_to_log: Array(decorated_method),
             payload: payload,
             config: config_opts,
           )

data/lib/debug_logging/instance_logger_modulizer.rb

@@ -8,57 +8,31 @@ module DebugLogging
             payload:,
             config:,
           )
-          Array(methods_to_log).each do |method_to_log|
-            method_to_log, method_payload, method_config_opts = DebugLogging::Util.extract_payload_and_config(
-              method_names: method_to_log,
+          Array(methods_to_log).each do |decorated_method|
+            decorated_method, method_payload, method_config_opts = DebugLogging::Util.extract_payload_and_config(
+              method_names: decorated_method,
               payload:,
               config: config_opts,
             )
-            define_method(method_to_log) do |*args, **kwargs, &block|
-              method_return_value = nil
-              config_proxy = DebugLogging::Util.config_proxy_finder(
-                scope: self.class,
-                config_opts: method_config_opts,
-                method_name: method_to_log,
-                proxy_ref: "ilm",
+            define_method(decorated_method) do |*args, **kwargs, &block|
+              lamb_dart = LambDart::Log.new(
+                instance: self,
+                method_config_opts:,
+                method_payload:,
+                args:,
+                kwargs:,
+                decorated_method:,
               )
-              log_prefix = self.class.debug_invocation_to_s(
-                klass: self.class.to_s,
-                separator: "#",
-                method_to_log: method_to_log,
-                config_proxy: config_proxy,
-              )
-              invocation_id = self.class.debug_invocation_id_to_s(args:, kwargs:, config_proxy:)
-              config_proxy.log do
-                paydirt = DebugLogging::Util.payload_instance_variable_hydration(scope: self, payload: method_payload)
-                signature = self.class.debug_signature_to_s(args:, kwargs:, config_proxy:)
-                paymud = debug_payload_to_s(payload: paydirt, config_proxy:)
-                "#{log_prefix}#{signature}#{invocation_id} debug: #{paymud}"
-              end
-              if config_proxy.benchmarkable_for?(:debug_instance_benchmarks)
-                tms = Benchmark.measure do
-                  method_return_value = super(*args, **kwargs, &block)
-                end
-                config_proxy.log do
-                  "#{log_prefix} #{self.class.debug_benchmark_to_s(tms: tms)}#{invocation_id}"
-                end
-              else
-                begin
-                  method_return_value = super(*args, **kwargs, &block)
-                rescue StandardError => e
-                  if config_proxy.error_handler_proc
-                    config_proxy.error_handler_proc.call(config_proxy, e, self, method_to_log, args, kwargs)
-                  else
-                    raise e
-                  end
-                end
-                if config_proxy.exit_scope_markable? && invocation_id && !invocation_id.empty?
-                  config_proxy.log do
-                    "#{log_prefix} completed#{invocation_id}"
-                  end
+              real_mccoy = ->() {
+                super(*args, **kwargs, &block)
+              }
+              _dl_ld_enter_log(lamb_dart) do
+                _dl_ld_error_handle(lamb_dart) do
+                  return _dl_ld_benchmarked(lamb_dart) { real_mccoy.call } if lamb_dart.bench?
+
+                  _dl_ld_exit_log(lamb_dart) { real_mccoy.call }
                 end
               end
-              method_return_value
             end
           end
         end

data/lib/debug_logging/instance_notifier.rb

@@ -1,5 +1,11 @@
 module DebugLogging
   module InstanceNotifier
+    class << self
+      def extended(base)
+        base.include(LambDartable::Note)
+      end
+    end
+
     def i_notified(*methods_to_log)
       method_names, payload, config_opts = DebugLogging::Util.extract_payload_and_config(
         method_names: methods_to_log,

data/lib/debug_logging/instance_notifier_modulizer.rb

@@ -8,40 +8,24 @@ module DebugLogging
             payload:,
             config:,
           )
-          Array(methods_to_notify).each do |method_to_notify|
-            method_to_notify, method_payload, method_config_opts = DebugLogging::Util.extract_payload_and_config(
-              method_names: method_to_notify,
+          Array(methods_to_notify).each do |decorated_method|
+            decorated_method, method_payload, method_config_opts = DebugLogging::Util.extract_payload_and_config(
+              method_names: decorated_method,
               payload:,
               config: config_opts,
             )
-            define_method(method_to_notify) do |*args, **kwargs, &block|
-              config_proxy = DebugLogging::Util.config_proxy_finder(
-                scope: self.class,
-                config_opts: method_config_opts,
-                method_name: method_to_notify,
-                proxy_ref: "inm",
-              ) do |config_proxy|
-                ActiveSupport::Notifications.subscribe(
-                  DebugLogging::ArgumentPrinter.debug_event_name_to_s(method_to_notify:),
-                ) do |*subscribe_args|
-                  config_proxy&.log do
-                    DebugLogging::LogSubscriber.log_event(ActiveSupport::Notifications::Event.new(*subscribe_args))
-                  end
-                end
-              end
-              paydirt = DebugLogging::Util.payload_instance_variable_hydration(scope: self, payload: method_payload)
-              ActiveSupport::Notifications.instrument(
-                DebugLogging::ArgumentPrinter.debug_event_name_to_s(method_to_notify:),
-                debug_args: kwargs.empty? ? args : args + [kwargs],
-                config_proxy: config_proxy,
-                **paydirt,
-              ) do
-                super(*args, **kwargs, &block)
-              rescue StandardError => e
-                if config_proxy.error_handler_proc
-                  config_proxy.error_handler_proc.call(config_proxy, e, self, method_to_notify, args, kwargs)
-                else
-                  raise e
+            define_method(decorated_method) do |*args, **kwargs, &block|
+              lamb_dart = LambDart::Note.new(
+                instance: self,
+                method_config_opts:,
+                method_payload:,
+                args:,
+                kwargs:,
+                decorated_method:,
+              )
+              _dl_ld_notify(lamb_dart) do
+                _dl_ld_error_handle(lamb_dart) do
+                  super(*args, **kwargs, &block)
                 end
               end
             end

data/lib/debug_logging/lamb_dart/base.rb

@@ -0,0 +1,46 @@
+require "forwardable"
+
+module DebugLogging
+  module LambDart
+    class Base
+      extend Forwardable
+
+      attr_reader :instance, # For ClassLogger, this will be the same as klass
+        :klass,
+        :is_class,
+        :config_proxy,
+        :method_payload,
+        :args,
+        :kwargs,
+        :scope_term,
+        :decorated_method
+
+      def_delegator :@config_proxy, :error_handler_proc
+
+      def initialize(instance: nil, klass: nil, method_config_opts:, method_payload:, args:, kwargs:, decorated_method:)
+        @instance = instance || klass
+        @klass = klass || instance.class
+        @method_payload = method_payload
+        @args = args
+        @kwargs = kwargs
+        @decorated_method = decorated_method
+        @is_class = (self.klass == self.instance)
+        @scope_term = is_class ? "class" : "instance"
+        @config_proxy = DebugLogging::Util.config_proxy_finder(
+          scope: self.klass,
+          config_opts: method_config_opts,
+          method_name: self.decorated_method,
+          proxy_ref:,
+        ) do |proxy|
+          yield proxy if block_given?
+        end
+      end
+
+      private
+
+      def proxy_ref
+        raise "#{self.class}##{__method__} is not defined, please fix!"
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_dart/log.rb

@@ -0,0 +1,47 @@
+module DebugLogging
+  module LambDart
+    class Log < Base
+      attr_reader :log_prefix,
+        :invocation_id,
+        :start_at
+
+      def initialize(...)
+        @start_at = Time.now
+        super
+        @log_prefix = klass.debug_invocation_to_s(
+          klass: klass.to_s,
+          separator: is_class ? "::" : "#",
+          decorated_method:,
+          config_proxy:,
+        )
+        @invocation_id = klass.debug_invocation_id_to_s(args:, config_proxy:)
+      end
+
+      def end_timestamp
+        klass.debug_time_to_s(Time.now, config_proxy:)
+      end
+
+      def benchmarked(tms)
+        klass.debug_benchmark_to_s(tms: tms)
+      end
+
+      def mark_exit_scope?
+        config_proxy.exit_scope_markable? && invocation_id && !invocation_id.empty?
+      end
+
+      def bench_scope
+        "debug_#{scope_term}_benchmarks".to_sym
+      end
+
+      def bench?
+        config_proxy.benchmarkable_for?(bench_scope)
+      end
+
+      private
+
+      def proxy_ref
+        is_class ? "kl" : "ilm"
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_dart/note.rb

@@ -0,0 +1,30 @@
+module DebugLogging
+  module LambDart
+    class Note < Base
+      attr_reader :debug_args
+
+      def initialize(...)
+        super do |proxy|
+          subscribe(proxy)
+        end
+        @debug_args = kwargs.empty? ? args : args + [kwargs]
+      end
+
+      private
+
+      def subscribe(proxy)
+        ActiveSupport::Notifications.subscribe(
+          DebugLogging::ArgumentPrinter.debug_event_name_to_s(decorated_method: decorated_method),
+        ) do |*subscribe_args|
+          proxy.log do
+            DebugLogging::LogSubscriber.log_event(ActiveSupport::Notifications::Event.new(*subscribe_args))
+          end
+        end
+      end
+
+      def proxy_ref
+        is_class ? "kn" : "inm"
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_dart.rb

@@ -0,0 +1,9 @@
+require_relative "lamb_dart/base"
+require_relative "lamb_dart/log"
+require_relative "lamb_dart/note"
+
+module DebugLogging
+  module LambDart
+    # Namespace
+  end
+end

data/lib/debug_logging/lamb_dartable.rb

@@ -0,0 +1,41 @@
+require_relative "lamb_darts/benchmarked"
+require_relative "lamb_darts/enter_log"
+require_relative "lamb_darts/error_handle"
+require_relative "lamb_darts/exit_log"
+require_relative "lamb_darts/notify"
+
+module DebugLogging
+  module LambDartable
+    module Log
+      class << self
+        def included(base)
+          base.include(LambDarts::Benchmarked)
+          base.include(LambDarts::EnterLog)
+          base.include(LambDarts::ErrorHandle)
+          base.include(LambDarts::ExitLog)
+        end
+
+        def extended(base)
+          base.extend(LambDarts::Benchmarked)
+          base.extend(LambDarts::EnterLog)
+          base.extend(LambDarts::ErrorHandle)
+          base.extend(LambDarts::ExitLog)
+        end
+      end
+    end
+
+    module Note
+      class << self
+        def included(base)
+          base.include(LambDarts::ErrorHandle)
+          base.include(LambDarts::Notify)
+        end
+
+        def extended(base)
+          base.extend(LambDarts::ErrorHandle)
+          base.extend(LambDarts::Notify)
+        end
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_darts/benchmarked.rb

@@ -0,0 +1,19 @@
+module DebugLogging
+  module LambDarts
+    module Benchmarked
+      def _dl_ld_benchmarked(ld)
+        brv = nil
+        # Benchmarking as close to the real mccoy as possible,
+        #   so as to not pollute performance tracking with the effects of debug_logging,
+        #   which may be removed once data has been gathered, or turned off.
+        tms = Benchmark.measure do
+          brv = yield
+        end
+        ld.config_proxy.log do
+          "#{ld.end_timestamp}#{ld.log_prefix} #{ld.benchmarked(tms)}#{ld.invocation_id}"
+        end
+        brv
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_darts/enter_log.rb

@@ -0,0 +1,16 @@
+module DebugLogging
+  module LambDarts
+    module EnterLog
+      def _dl_ld_enter_log(ld)
+        start_timestamp = ld.klass.debug_time_to_s(ld.start_at, config_proxy: ld.config_proxy)
+        ld.config_proxy.log do
+          paydirt = DebugLogging::Util.payload_instance_variable_hydration(scope: ld.instance, payload: ld.method_payload)
+          signature = ld.klass.debug_signature_to_s(args: ld.args, kwargs: ld.kwargs, config_proxy: ld.config_proxy)
+          paymud = ld.instance.debug_payload_to_s(payload: paydirt, config_proxy: ld.config_proxy)
+          "#{start_timestamp}#{ld.log_prefix}#{signature}#{ld.invocation_id} debug: #{paymud}"
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_darts/error_handle.rb

@@ -0,0 +1,28 @@
+module DebugLogging
+  module LambDarts
+    module ErrorHandle
+      def _dl_ld_error_handle(ld)
+        if ld.config_proxy.error_handler_proc
+          begin
+            yield
+          rescue StandardError => e
+            if ld.error_handler_proc
+              ld.error_handler_proc.call(
+                ld.config_proxy,
+                e,
+                self,
+                ld.decorated_method,
+                *ld.args,
+                **ld.kwargs,
+              )
+            else
+              raise e
+            end
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_darts/exit_log.rb

@@ -0,0 +1,15 @@
+module DebugLogging
+  module LambDarts
+    module ExitLog
+      def _dl_ld_exit_log(ld)
+        hrv = yield
+        return hrv unless ld.mark_exit_scope?
+
+        ld.config_proxy.log do
+          "#{ld.end_timestamp}#{ld.log_prefix} completed#{ld.invocation_id}"
+        end
+        hrv
+      end
+    end
+  end
+end

data/lib/debug_logging/lamb_darts/notify.rb

@@ -0,0 +1,17 @@
+module DebugLogging
+  module LambDarts
+    module Notify
+      def _dl_ld_notify(ld)
+        paydirt = DebugLogging::Util.payload_instance_variable_hydration(scope: ld.instance, payload: ld.method_payload)
+        ActiveSupport::Notifications.instrument(
+          DebugLogging::ArgumentPrinter.debug_event_name_to_s(decorated_method: ld.decorated_method),
+          debug_args: ld.debug_args,
+          config_proxy: ld.config_proxy,
+          **paydirt,
+        ) do
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/debug_logging/log_subscriber.rb

@@ -32,8 +32,8 @@ module DebugLogging
       {
         name: event.name,
         duration: Rational(event.duration, 1000).to_f,
-        time: debug_time_to_s(event.time),
-        end: debug_time_to_s(event.end),
+        time: debug_event_time_to_s(event.time),
+        end: debug_event_time_to_s(event.end),
         args: debug_signature_to_s(args: args, config_proxy: config_proxy),
         payload: debug_payload_to_s(payload: payload, config_proxy: config_proxy),
       }

data/lib/debug_logging/util.rb

@@ -2,6 +2,20 @@ module DebugLogging
   module Util
     module_function
 
+    def debug_time(time_or_monotonic)
+      case time_or_monotonic
+      when Time, DateTime
+        time_or_monotonic
+      when Numeric
+        Time.at(time_or_monotonic)
+      when String
+        Time.parse(time_or_monotonic)
+      else
+        # Garbage in, Sweet Nourishing Gruel Out
+        Time.now
+      end
+    end
+
     # methods_to_log may be an array of a single method name, followed by config options and payload,
     #   or it could be an array of method names followed by config options and payload to be shared by the whole set.
     def extract_payload_and_config(method_names:, payload: nil, config: nil)
@@ -36,6 +50,8 @@ module DebugLogging
             # logged :meth1, :meth2, :meth3 without options is valid
             method_names
           end
+        else
+          raise ArgumentError, "unknown type for method_names: #{method_names.class}"
         end
       [method_names, payload, config_opts]
     end
@@ -55,27 +71,31 @@ module DebugLogging
     end
 
     def config_proxy_finder(scope:, method_name:, proxy_ref:, config_opts: {}, &block)
-      if (proxy = scope.send(:instance_variable_get, DebugLogging::Configuration.config_pointer(
-        proxy_ref,
-        method_name,
-      )))
-        proxy
+      proxy = scope.send(
+        :instance_variable_get,
+        DebugLogging::Configuration.config_pointer(
+          proxy_ref,
+          method_name,
+        ),
+      )
+      # short circuit on subsequent calls is required
+      #   so we only register notifications once
+      return proxy if proxy
+
+      base = scope.respond_to?(:debug_config) ? scope.debug_config : DebugLogging.debug_logging_configuration
+      proxy = if config_opts.empty?
+        base
       else
-        base = scope.respond_to?(:debug_config) ? scope.debug_config : DebugLogging.debug_logging_configuration
-        proxy = if config_opts.empty?
-          base
-        else
-          DebugLogging::Configuration.new(**base.to_hash.merge(config_opts))
-        end
-        proxy.register(method_name)
-        scope.send(
-          :instance_variable_set,
-          DebugLogging::Configuration.config_pointer(proxy_ref, method_name),
-          proxy,
-        )
-        yield proxy if block
-        proxy
+        DebugLogging::Configuration.new(**base.to_hash.merge(config_opts))
       end
+      proxy.register(method_name)
+      scope.send(
+        :instance_variable_set,
+        DebugLogging::Configuration.config_pointer(proxy_ref, method_name),
+        proxy,
+      )
+      yield proxy if block
+      proxy
     end
   end
 end

data/lib/debug_logging/version.rb

@@ -1,5 +1,5 @@
 module DebugLogging
   module Version
-    VERSION = "4.0.0"
+    VERSION = "4.0.2"
   end
 end

data/lib/debug_logging.rb

@@ -15,17 +15,12 @@ require "debug_logging/util"
 require "debug_logging/finalize"
 require "debug_logging/argument_printer"
 require "debug_logging/hooks"
+require "debug_logging/lamb_dart"
+require "debug_logging/lamb_dartable"
 require "debug_logging/instance_logger_modulizer"
 require "debug_logging/instance_logger"
 require "debug_logging/class_logger"
 
-####################
-#                  #
-# NOTE: The manner this is made to work for class methods is totally different
-#       than the way this is made to work for instance methods.
-# NOTE: The instance method manner works on Ruby 2.0+
-# NOTE: The class method manner works on Ruby 2.1+
-#                  #
 ####################
 #                  #
 # USAGE (see specs)#
@@ -233,6 +228,22 @@ module DebugLogging
       @debug_logging_configuration.colorized_chain_for_class = colorized_chain_for_class
     end
 
+    def debug_add_timestamp
+      @debug_logging_configuration.add_timestamp
+    end
+
+    def debug_add_timestamp=(add_timestamp)
+      @debug_logging_configuration.add_timestamp = add_timestamp
+    end
+
+    def debug_time_formatter_proc
+      @debug_logging_configuration.time_formatter_proc
+    end
+
+    def debug_time_formatter_proc=(time_formatter_proc)
+      @debug_logging_configuration.time_formatter_proc = time_formatter_proc
+    end
+
     def debug_add_invocation_id
       @debug_logging_configuration.add_invocation_id
     end