debug_logging 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cab0a0dee00124b49ff568d1b1f8dbeaee9ba25b975af8d3fa1f0b4d3af88054
-  data.tar.gz: f8427104b804d23a284edd3ab8878c96273e8edf4dec850ae3001c15a60bf6ed
+  metadata.gz: efda45f99c32dcb0acc32896a61f2d209c527cf62bd74a74282cf044607f396f
+  data.tar.gz: d4af27fc700abaa9a536d15c56af36f8a202db7c40d0107a8d8eb1262252aaeb
 SHA512:
-  metadata.gz: e871fdb1af74fe7b17c5e66b918edcec67d696b4d45b9bca79025b2a9c35c41a42aa1c8794bd0184aacf34e39ce4c43348ed6b6b96e6d17abb180db10fcabc3b
-  data.tar.gz: 389312d99d1060d3349bf8f9a1e05a579dfeaf17c40151d1670483152da18c043a4a2b401749dad884b99b9acf3042dcc75e61189e0fc7141ca41d28bac6f264
+  metadata.gz: d857b33f90f75e8bdfb3f2deedfb5c503bd90adbabb6b9aead0ecb305ba72715c25435f9d543ff8471454b5c9c5ff631792b870a97864fdb30e530ba4c0e6fb0
+  data.tar.gz: 6985ed5caff4dbe017946a61b4f4242867110bcafcf266b62c98ce340d8af28f148b1dee364d3291296d2d5444789a429b254bedcd54bd63be28e4ce5a771b10

data/.rubocop_todo.yml

@@ -33,7 +33,7 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, ExcludedMethods.
 # ExcludedMethods: refine
 Metrics/BlockLength:
-  Max: 756
+  Max: 810
 
 # Offense count: 6
 # Configuration parameters: CountBlocks.
@@ -87,9 +87,13 @@ Style/Documentation:
     - 'lib/debug_logging.rb'
     - 'lib/debug_logging/argument_printer.rb'
     - 'lib/debug_logging/class_logger.rb'
+    - 'lib/debug_logging/class_notifier.rb'
     - 'lib/debug_logging/configuration.rb'
     - 'lib/debug_logging/instance_logger.rb'
     - 'lib/debug_logging/instance_logger_modulizer.rb'
+    - 'lib/debug_logging/instance_notifier.rb'
+    - 'lib/debug_logging/instance_notifier_modulizer.rb'
+    - 'lib/debug_logging/log_subscriber.rb'
     - 'lib/simple_debug_logging.rb'
 
 # Offense count: 1
@@ -99,6 +103,7 @@ Style/Documentation:
 Style/EmptyElse:
   Exclude:
     - 'lib/debug_logging/class_logger.rb'
+    - 'lib/debug_logging/class_notifier.rb'
 
 # Offense count: 2
 # Configuration parameters: EnforcedStyle.
@@ -111,7 +116,9 @@ Style/FormatStringToken:
 Style/IdenticalConditionalBranches:
   Exclude:
     - 'lib/debug_logging/class_logger.rb'
+    - 'lib/debug_logging/class_notifier.rb'
     - 'lib/debug_logging/instance_logger_modulizer.rb'
+    - 'lib/debug_logging/instance_notifier_modulizer.rb'
 
 # Offense count: 1
 Style/MultilineBlockChain:

data/README.md

@@ -29,7 +29,9 @@ Unobtrusive, inheritable-overridable-configurable, drop-in debug logging, that w
 * *single line config, per class/instance/method config*
 * *separate logger, if needed*
 * *log method calls, also when exit scope*
-* *Prevents heavy computation of strings with `logger.debug { 'log me' }` block format.*
+* *Prevents heavy computation of strings with `logger.debug { 'log me' }` block format, since v1.0.12*
+* *ActiveSupport::Notifications integration for instrumenting/logging events on class and instance methods, since v3.1*
+* *Optional instance variable logging, sine v3.1*
 * **so many free ponies** 🎠🐴🎠🐴🎠🐴
 
 ## Next Level Magic
@@ -40,7 +42,10 @@ Herein you will find:
 * Zero tolerance policy on monkey patching
 * 100% clean, 0% obtrusive
 * 100% tested
-* 100% Ruby 2.3+ compatible
+* 100% Ruby 2.1+ compatible
+  - use version ~1.0 for Ruby < 2.3
+  - use version ~2.0 for Ruby 2.3
+  - use version ~3.0 for Ruby 2.4+
 
 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.
 
@@ -62,8 +67,6 @@ Or install it yourself as:
 
 ## Usage
 
-NOTE: Starting with version `1.0.12` this gem utilizes the `logger.debug { "block format" }` to avoid heavy debug processing when the log level threshold is set higher than the level of the statements produced as a result of the configuration of this gem.
-
 Crack open the specs for more complex usage examples than the ones below.
 
 ### Without Rails
@@ -85,6 +88,7 @@ DebugLogging.configuration.last_hash_max_length = 1_000
 DebugLogging.configuration.args_max_length = 1_000
 DebugLogging.configuration.instance_benchmarks = false
 DebugLogging.configuration.class_benchmarks = false
+DebugLogging.configuration.active_support_notifications = false
 DebugLogging.configuration.colorized_chain_for_method = false # e.g. ->(colorized_string) { colorized_string.red.on_blue.underline }
 DebugLogging.configuration.colorized_chain_for_class = false # e.g. ->(colorized_string) { colorized_string.colorize(:light_blue ).colorize( :background => :red) }
 DebugLogging.configuration.add_invocation_id = true # identify a method call uniquely in a log, pass a proc for colorization, e.g. ->(colorized_string) { colorized_string.light_black }
@@ -104,6 +108,7 @@ DebugLogging.configure do |config|
   config.args_max_length = 1_000
   config.instance_benchmarks = false
   config.class_benchmarks = false
+  config.active_support_notifications = false
   config.colorized_chain_for_method = false # e.g. ->(colorized_string) { colorized_string.red.on_blue.underline }
   config.colorized_chain_for_class = false # e.g. ->(colorized_string) { colorized_string.colorize(:light_blue ).colorize( :background => :red) }
   config.add_invocation_id = true # identify a method call uniquely in a log, pass a proc for colorization, e.g. ->(colorized_string) { colorized_string.light_black }
@@ -127,7 +132,7 @@ Just send along a hash of the config options when you call `logged` or `include
 DebugLogging.configuration.logger = Rails.logger
 ```
 
-Every time a method is called, get logs, optionally with arguments, a benchmarck, and a unique invocation identifier:
+Every time a method is called, you can now get logs, optionally with arguments, a benchmark, and a unique invocation identifier:
 
 ```ruby
 class Car
@@ -170,6 +175,60 @@ class Car
 end
 ```
 
+### ActiveSupport::Notifications integration
+
+To use `ActiveSupport::Notifications` integration, enable `active_support_notifications` in the config, either single line or block style:
+
+```ruby
+DebugLogging.configuration.active_support_notifications = true
+```
+
+or
+
+```ruby
+DebugLogging.configure do |config|
+  config.active_support_notifications = true
+end
+```
+
+Every time a method is called, class and instance method events are instrumented, consumed and logged:
+
+```ruby
+class Car
+
+  # adds the helper methods to the class, all are prefixed with debug_*,
+  #   except for the instrumented class method, which comes from extending DebugLogging::ClassNotifier
+  extend DebugLogging
+
+  # For instance methods:
+  # Option 1: specify the exact method(s) to add instrumentation to (including capturing instance variable values as part of the event payload)
+  include DebugLogging::InstanceNotifier.new(i_methods: [:drive,
+                                                         :stop,
+                                                         [:turn, { instance_variables: %i[direction angle] }]])
+
+  # Provides the `notifies` method decorator
+  extend DebugLogging::ClassNotifier
+
+  notifies def make; new; end
+  def design(*args); new; end
+  def safety(*args); new; end
+  def dealer_options(*args); new; end
+  notifies :design, :safety
+  # adding additional event payload options for any instance method(s), by passing a hash as the last argument
+  notifies :dealer_options, { sport_package: true }
+
+  def drive(speed); speed; end
+  def stop(**opts); 0; end
+
+  # For instance methods:
+  # Option 2: add instrumentation to all instance methods defined above (but *not* defined below)
+  include DebugLogging::InstanceNotifier.new(i_methods: self.instance_methods(false))
+
+  def will_not_be_logged; false; end
+
+end
+```
+
 ## 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.
@@ -202,7 +261,7 @@ dependency on this gem using the [Pessimistic Version Constraint](http://docs.ru
 For example:
 
 ```ruby
-spec.add_dependency 'debug_logging', '~> 2.0'
+spec.add_dependency 'debug_logging', '~> 3.1'
 ```
 
 ## License [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

data/debug_logging.gemspec

@@ -27,6 +27,7 @@ Automatically log selected methods and their arguments as they are called at run
   spec.required_ruby_version = '>= 2.4.0' # Uses magic comments
 
   spec.add_runtime_dependency 'colorize', '>= 0'
+  spec.add_development_dependency 'activesupport', '~> 5.2', '>= 5.2.4.4'
   spec.add_development_dependency 'bundler', '>= 2'
   spec.add_development_dependency 'byebug', '>= 11'
   spec.add_development_dependency 'rake', '>= 13'

data/lib/debug_logging/active_support_notifications.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'debug_logging/log_subscriber'
+require 'debug_logging/class_notifier'
+require 'debug_logging/instance_notifier_modulizer'
+require 'debug_logging/instance_notifier'

data/lib/debug_logging/argument_printer.rb

@@ -6,6 +6,10 @@ module DebugLogging
       "completed in #{format('%f', tms.real)}s (#{format('%f', tms.total)}s CPU)"
     end
 
+    def debug_event_name_to_s(method_to_notify: nil)
+      "#{method_to_notify}.log"
+    end
+
     def debug_invocation_id_to_s(args: nil, config_proxy: nil)
       if config_proxy.debug_add_invocation_id
         invocation = " ~#{args.object_id}@#{(Time.now.to_f.to_s % '%#-21a')[4..-4]}~"
@@ -79,7 +83,7 @@ module DebugLogging
           # handle double splat
           printed_args += ("**#{args.map(&:inspect).join(', ').tap { |x| add_args_ellipsis = x.length > config_proxy.debug_args_max_length }}")[0..(config_proxy.debug_args_max_length)]
         else
-          printed_args += args.map(&:inspect).join(', ').tap { |x| add_args_ellipsis = x.length > config_proxy.debug_args_max_length}[0..(config_proxy.debug_args_max_length)]
+          printed_args += args.map(&:inspect).join(', ').tap { |x| add_args_ellipsis = x.length > config_proxy.debug_args_max_length }[0..(config_proxy.debug_args_max_length)]
         end
         printed_args += config_proxy.debug_ellipsis if add_args_ellipsis
       end

data/lib/debug_logging/class_notifier.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DebugLogging
+  module ClassNotifier
+    def notifies(*methods_to_notify)
+      payload = methods_to_notify.last.is_a?(Hash) && methods_to_notify.pop || {}
+      if methods_to_notify.first.is_a?(Array)
+        methods_to_notify = methods_to_notify.shift
+      else
+        # logged :meth1, :meth2, :meth3 without options is valid too
+      end
+      methods_to_notify.each do |method_to_notify|
+        # method name must be a symbol
+        method_to_notify = method_to_notify.to_sym
+        original_method = method(method_to_notify)
+        config_proxy = nil
+        (class << self; self; end).class_eval do
+          define_method(method_to_notify) do |*args, &block|
+            config_proxy = if (proxy = instance_variable_get(DebugLogging::Configuration.config_pointer('k', method_to_notify)))
+                             proxy
+                           else
+                             proxy = if !payload.empty?
+                                       Configuration.new(**debug_config.to_hash.merge(payload))
+                                     else
+                                       debug_config
+                                     end
+                             proxy.register(method_to_notify)
+                             instance_variable_set(DebugLogging::Configuration.config_pointer('k', method_to_notify), proxy)
+                             proxy
+                           end
+            ActiveSupport::Notifications.instrument(
+              debug_event_name_to_s(method_to_notify: method_to_notify), { args: args }.merge(payload)
+            ) do
+              original_method.call(*args, &block)
+            end
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe(/log/) do |*args|
+          config_proxy&.log do
+            DebugLogging::LogSubscriber.log_event(ActiveSupport::Notifications::Event.new(*args))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/debug_logging/configuration.rb

@@ -9,7 +9,7 @@ module DebugLogging
     attr_accessor :logger, :log_level, :multiple_last_hashes, :last_hash_to_s_proc, :last_hash_max_length,
                   :args_max_length, :colorized_chain_for_method, :colorized_chain_for_class, :add_invocation_id,
                   :ellipsis, :mark_scope_exit
-    attr_reader :instance_benchmarks, :class_benchmarks, :methods_to_log
+    attr_reader :instance_benchmarks, :class_benchmarks, :active_support_notifications, :methods_to_log
     # alias the readers to the debug_* prefix so an instance of this class
     #   can have the same API granted by `extend DebugLogging`
     #
@@ -59,13 +59,14 @@ module DebugLogging
       @last_hash_to_s_proc = options.key?(:last_hash_to_s_proc) ? options[:last_hash_to_s_proc] : nil
       @last_hash_max_length = options.key?(:last_hash_max_length) ? options[:last_hash_max_length] : 1_000
       @args_max_length = options.key?(:args_max_length) ? options[:args_max_length] : 1_000
-      @instance_benchmarks = options.key?(:instance_benchmarks) ? options[:instance_benchmarks] : false
-      @class_benchmarks = options.key?(:class_benchmarks) ? options[:class_benchmarks] : false
       @colorized_chain_for_method = options.key?(:colorized_chain_for_method) ? options[:colorized_chain_for_method] : false
       @colorized_chain_for_class = options.key?(:colorized_chain_for_class) ? options[:colorized_chain_for_class] : false
       @add_invocation_id = options.key?(:add_invocation_id) ? options[:add_invocation_id] : true
       @ellipsis = options.key?(:ellipsis) ? options[:ellipsis] : DEFAULT_ELLIPSIS
       @mark_scope_exit = options.key?(:mark_scope_exit) ? options[:mark_scope_exit] : false
+      self.instance_benchmarks = options.key?(:instance_benchmarks) ? options[:instance_benchmarks] : false
+      self.class_benchmarks = options.key?(:class_benchmarks) ? options[:class_benchmarks] : false
+      self.active_support_notifications = options.key?(:active_support_notifications) ? options[:active_support_notifications] : false
       @methods_to_log = []
     end
 
@@ -108,6 +109,11 @@ module DebugLogging
       @class_benchmarks = class_benchmarks
     end
 
+    def active_support_notifications=(active_support_notifications)
+      require 'debug_logging/active_support_notifications' if active_support_notifications
+      @active_support_notifications = active_support_notifications
+    end
+
     def to_hash
       {
         logger: logger,
@@ -122,7 +128,8 @@ module DebugLogging
         colorized_chain_for_class: colorized_chain_for_class,
         add_invocation_id: add_invocation_id,
         ellipsis: ellipsis,
-        mark_scope_exit: mark_scope_exit
+        mark_scope_exit: mark_scope_exit,
+        active_support_notifications: active_support_notifications
       }
     end
 

data/lib/debug_logging/instance_notifier.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DebugLogging
+  class InstanceNotifier < Module
+    def initialize(i_methods: nil)
+      super()
+      @instance_methods_to_notify = Array(i_methods) if i_methods
+    end
+
+    def included(base)
+      return unless @instance_methods_to_notify
+
+      base.send(:include, ArgumentPrinter)
+      instance_method_notifier = DebugLogging::InstanceNotifierModulizer.to_mod(methods_to_notify: @instance_methods_to_notify)
+      base.send(:prepend, instance_method_notifier)
+    end
+  end
+end

data/lib/debug_logging/instance_notifier_modulizer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module DebugLogging
+  module InstanceNotifierModulizer
+    def self.to_mod(methods_to_notify: nil)
+      Module.new do
+        Array(methods_to_notify).each do |method_to_notify|
+          # method name must be a symbol
+          payload = method_to_notify.is_a?(Array) && method_to_notify.last.is_a?(Hash) && method_to_notify.pop || {}
+          if method_to_notify.is_a?(Array)
+            method_to_notify = method_to_notify.first&.to_sym
+          else
+            method_to_notify.to_sym
+          end
+          config_proxy = nil
+          define_method(method_to_notify) do |*args, &block|
+            config_proxy = if (proxy = instance_variable_get(DebugLogging::Configuration.config_pointer('i', method_to_notify)))
+                             proxy
+                           else
+                             proxy = if !payload.empty?
+                                       Configuration.new(**self.class.debug_config.to_hash.merge(payload))
+                                     else
+                                       self.class.debug_config
+                                     end
+                             proxy.register(method_to_notify)
+                             instance_variable_set(DebugLogging::Configuration.config_pointer('i', method_to_notify), proxy)
+                             proxy
+                           end
+            if payload.key?(:instance_variables)
+              payload[:instance_variables].each do |k|
+                payload[k] = instance_variable_get("@#{k}") if instance_variable_get("@#{k}")
+              end
+              payload.delete(:instance_variables)
+            end
+            ActiveSupport::Notifications.instrument(
+              self.class.debug_event_name_to_s(method_to_notify: method_to_notify), { args: args }.merge(payload)
+            ) do
+              super(*args, &block)
+            end
+          end
+
+          ActiveSupport::Notifications.subscribe(/log/) do |*args|
+            config_proxy&.log do
+              DebugLogging::LogSubscriber.log_event(ActiveSupport::Notifications::Event.new(*args))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/debug_logging/log_subscriber.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'active_support/log_subscriber'
+
+module DebugLogging
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    class << self
+      attr_accessor :event
+    end
+    attach_to :log
+
+    EVENT_FORMAT_STRING = '%<name>s (%<duration>.3f secs) start=%<time>s end=%<end>s payload=%<payload>s'
+
+    def self.log_event(event)
+      @event = event
+      if event.payload && event.payload[:exception_object]
+        exception = event.payload[:exception_object]
+        "#{event.name} [ERROR] : \n#{exception.class} : #{exception.message}\n" + exception.backtrace.join("\n")
+      end
+      format(EVENT_FORMAT_STRING, event_to_format_options(event))
+    end
+
+    # @param [ActiveSupport::Notifications::Event]
+    # @return [Hash]
+    def self.event_to_format_options(event)
+      {
+        name: event.name,
+        duration: Rational(event.duration, 1000).to_f,
+        time: event.time,
+        end: event.end,
+        payload: event.payload
+      }
+    end
+  end
+end

data/lib/debug_logging/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DebugLogging
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 end

data/lib/simple_debug_logging.rb

@@ -21,8 +21,6 @@
 #       logged :a_class_method
 #     end
 #
-#   Make sure you have the latest debug_logging gem (>= 1.0.10) installed for this to work
-#
 #   In an irb session:
 #     >> require_relative 'unobtrusively_logged'
 #     => true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: debug_logging
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Peter Boling
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-07 00:00:00.000000000 Z
+date: 2020-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -24,6 +24,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.4.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.4.4
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -159,11 +179,16 @@ files:
 - bin/setup
 - debug_logging.gemspec
 - lib/debug_logging.rb
+- lib/debug_logging/active_support_notifications.rb
 - lib/debug_logging/argument_printer.rb
 - lib/debug_logging/class_logger.rb
+- lib/debug_logging/class_notifier.rb
 - lib/debug_logging/configuration.rb
 - lib/debug_logging/instance_logger.rb
 - lib/debug_logging/instance_logger_modulizer.rb
+- lib/debug_logging/instance_notifier.rb
+- lib/debug_logging/instance_notifier_modulizer.rb
+- lib/debug_logging/log_subscriber.rb
 - lib/debug_logging/version.rb
 - lib/simple_debug_logging.rb
 homepage: https://github.com/pboling/debug_logging