nrser 0.2.2 → 0.3.0

data/lib/nrser/log/formatters/mixin.rb

@@ -0,0 +1,270 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Log; end
+module NRSER::Log::Formatters; end
+
+
+# Definitions
+# =======================================================================
+
+# A mix-in to include in {SemanticLogger::Formatter::Default} and subclasses
+# to improve configurability.
+# 
+module NRSER::Log::Formatters::Mixin
+  
+  # Inner Classes
+  # ==========================================================================
+  # 
+  # Small helper classes only created via the mix-in.
+  # 
+  
+  # Abstract base class for {HeaderTokens} and {BodyTokens}, instances of which are used
+  # by formatters that include {NRSER::Log::Formatters::Mixin} to
+  # configure what pieces of information make up the header and body sections
+  # of log messages that it formats.
+  # 
+  # Entries are {SemanticLogger::Formatter::Default} method names, which I've
+  # called "tokens", and the order of the "tokens" dictates the order the
+  # results of those method calls will be joined to form the formatted
+  # message section.
+  # 
+  # Adding, removing and reordering tokens is used to control what elements
+  # appear and where in the formatted result.
+  # 
+  # Token arrays are mutable and meant to changed in place via {Array#delete}
+  # and friends.
+  # 
+  class Tokens < ::Array
+    # Create a new token array.
+    # 
+    # @param [Array<#to_sym>] tokens
+    #   The token symbols to initialize the array with. Must be covetable
+    #   to symbols (really, just pass symbols in the first place).
+    # 
+    def initialize tokens = self.class::ALL
+      super tokens.map( &:to_sym )
+    end
+    
+    
+    # Reset the array to be all the available tokens for the section in
+    # their original order.
+    # 
+    # **Mutates the array in place.**
+    # 
+    # @return [Tokens]
+    #   `self`.
+    # 
+    def reset!
+      clear
+      self.class::ALL.each { |token| self << token }
+      self
+    end
+  end # class Tokens
+  
+  
+  # {Tokens} subclass for log message headers.
+  # 
+  # @see #header
+  # @see #header=
+  # 
+  class HeaderTokens < Tokens
+    # All header tokens in a default order.
+    # 
+    # @return [Array<Symbol>]
+    # 
+    ALL = [
+      :time,
+      :level,
+      :process_info,
+      :tags,
+      :named_tags,
+      :duration,
+      :name,
+    ].freeze
+  end
+  
+  
+  # {Tokens} subclass for log message bodies.
+  # 
+  # @see #body
+  # @see #body=
+  # 
+  class BodyTokens < Tokens
+    # All body tokens in a default order.
+    # 
+    # @return [Array<Symbol>]
+    # 
+    ALL = [
+      :message,
+      :payload,
+      :exception,
+    ]
+  end
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # Get or set the header "tokens" - {SemanticLogger::Formatters::Default}
+  # method names in the order their responses should be joined to form the
+  # header section of formatted log messages (time, level, name, etc.).
+  # 
+  # @example Getting the {HeaderTokens}
+  #   # You won't see much unless logging is setup
+  #   NRSER::Log.setup! dest: $stdout, level: :info
+  #   
+  #   # Full object path to HeaderTokens - there's also a {NRSER::Log.header}
+  #   # shortcut
+  #   NRSER::Log.appender.formatter.header
+  #   # => [:time, :level, :process_info, :tags, :named_tags, :duration, :name]
+  #   
+  #   NRSER.logger.info "Hey yo!"
+  #   # > 2018-04-12 23:43:24.982040 INFO [19301:main] NRSER
+  #   # > -- Hey yo!
+  #   # >
+  #   # => true
+  # 
+  # @example Setting the {HeaderTokens}
+  #   # You won't see much unless logging is setup
+  #   NRSER::Log.setup! dest: $stdout, level: :info
+  #   
+  #   # Set a very simple header
+  #   NRSER::Log.header :level, :name
+  #   # => [:level, :name]
+  #   
+  #   # And notice the reduced log header
+  #   NRSER.logger.info "Hey yo!"
+  #   # > INFO NRSER
+  #   # > -- Hey yo!
+  #   # >
+  #   # => true
+  # 
+  # @param [Array<Symbol>] *tokens
+  #   Optional list of token symbols to set as the header format.
+  #   
+  #   When empty, the method works as a getter, returning the current header
+  #   format tokens.
+  # 
+  # @return [HeaderTokens]
+  #   The current header tokens.
+  # 
+  def header *tokens
+    if tokens.empty?
+      @header ||= HeaderTokens.new
+    else
+      @header = HeaderTokens.new tokens
+    end
+  end
+  
+  
+  # Set the header section format tokens.
+  # 
+  # See {#header} for details and examples of how the header works.
+  # 
+  # @see #header
+  # 
+  # @param [Array<Symbol>] *tokens
+  #   Token symbols to set as the header format.
+  # 
+  # @return [HeaderTokens]
+  #   The new header format.
+  # 
+  def header= tokens
+    @header = HeaderTokens.new tokens
+  end
+  
+  
+  # Get or set the body section tokens.
+  # 
+  # Just like {#header}, which has details and examples, but for the "body"
+  # section of log messages (message, payload, exception).
+  # 
+  # @see #header
+  # 
+  # @param [Array<Symbol>] *tokens
+  #   When not empty, sets the body to those tokens in that order.
+  #   
+  #   When empty, the current body is returned.
+  # 
+  # @return [BodyTokens]
+  #   The new and/or current body.
+  # 
+  def body *tokens
+    if tokens.empty?
+      @body ||= BodyTokens.new
+    else
+      @body = BodyTokens.new tokens
+    end
+  end
+  
+  
+  # Set the body section format tokens.
+  # 
+  # See {#header} for details and examples of how the header works.
+  # 
+  # @see #header
+  # 
+  # @param [Array<Symbol>] *tokens
+  #   Token symbols to set as the body format.
+  # 
+  # @return [HeaderTokens]
+  #   The new body format.
+  # 
+  def body= tokens
+    @body = BodyTokens.new tokens
+  end
+  
+  
+  protected
+  # ========================================================================
+    
+    # Use {#header} to render the header string for the current log.
+    # 
+    # @return [String]
+    # 
+    def render_header
+      header.map( &method( :send ) ).compact.join ' '
+    end # #header
+    
+    
+    # Use {#body} to render the header string for the current log.
+    # 
+    # @return [String]
+    # 
+    def render_body
+      body.map( &method( :send ) ).compact.join ' '
+    end
+    
+    
+    # Render the current log message using {#render_header} and {#render_body}.
+    # 
+    # @return [String]
+    # 
+    def render_log
+      render_header + "\n" + render_body + "\n"
+    end
+    
+  public # end protected ***************************************************
+  
+end # module NRSER::Log::Formatter::Mixin

data/lib/nrser/log/logger.rb

@@ -0,0 +1,229 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+require 'semantic_logger'
+
+
+# Definitions
+# =======================================================================
+
+# Extension of {SemanticLogger::Logger} to add and customize behavior.
+# 
+class NRSER::Log::Logger < SemanticLogger::Logger
+  
+  # Classes
+  # ========================================================================
+  
+  # Class that points to a {NRSER::Log::Logger} and provides the log methods
+  # (`#error`, `#warn`, ... `#trace`) with an additional `&block` parameter.
+  # 
+  # Each of those methods calls the block in a `begin` / `rescue`, and if it
+  # raises, the log message will be dispatched with the raised error added.
+  # 
+  # @see NRSER::Log::Logger#catch
+  # 
+  class Catcher
+    
+    # Construction
+    # ========================================================================
+    
+    # Instantiate a new `Catcher`.
+    # 
+    # @param [NRSER::Log::Logger] logger
+    #   The logger to use if the block raises.
+    # 
+    # @param [*] on_fail:
+    #   Value to return when `&block` raises.
+    # 
+    def initialize logger, on_fail: nil
+      @logger = logger
+      @on_fail = on_fail
+    end # #initialize
+    
+    
+    # Instance Methods
+    # ========================================================================
+    
+    SemanticLogger::LEVELS.each do |level|
+      define_method level do |message = nil, payload = nil, &block|
+        begin
+          block.call
+        rescue Exception => error
+          @logger.send level, message, payload, error
+          @on_fail
+        end
+      end
+    end
+    
+  end # class Catcher
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # TODO document `awesome_name` attribute.
+  # 
+  # @return [String]
+  #     
+  attr_reader :awesome_name
+  
+  
+  # Constructor
+  # ========================================================================
+  
+  # Overrides {SemanticLogger::Logger#initialize}¹ to extend "subject" support
+  # to instances (as well as modules/classes and strings).
+  #
+  # > ¹ {SemanticLogger::Logger#initialize} is just a proxy to
+  # >   {SemanticLogger::Base#initialize}, which is what this implementation
+  # >   is based off.
+  # 
+  # @param [Module | String | INSTANCE] subject
+  #   Name of the class, module, or other identifier for which the log messages
+  #   are being logged
+  #
+  # @param [nil | Symbol] level:
+  #   Only allow log entries of this level or higher to be written to this
+  #   appender For example if set to :warn, this appender would only log
+  #   `:warn` and `:fatal` log messages when other appenders could be logging
+  #   `:info` and lower.
+  #
+  # @param [nil | Regexp | Proc<(SemanticLogger::Log) => Boolean>] filter:
+  #   1.  {RegExp}: Only include log messages where the class name matches
+  #       the supplied regular expression. All other messages will be
+  #       ignored.
+  #       
+  #   2.  {Proc}: Only include log messages where the supplied Proc returns
+  #       `true`.
+  #       
+  # @raise [NRSER::TypeError]
+  #   If `filter:` is not an acceptable type.
+  # 
+  def initialize subject, level: nil, filter: nil
+    # Support filtering all messages to this logger using a Regular Expression
+    # or Proc
+    unless filter.nil? || filter.is_a?( Regexp ) || filter.is_a?( Proc )
+      raise NRSER::TypeError,
+        ":filter must be a Regexp or Proc",
+        filter: filter,
+        subject: subject,
+        level: level
+    end
+
+    @filter = filter.is_a?(Regexp) ? filter.freeze : filter
+    
+    # @name   = klass.is_a?(String) ? klass : klass.name
+    case subject
+    when String
+      @name = subject
+      @awesome_name = subject
+      @type = :string
+      
+    when Module
+      @name = subject.safe_name
+      @awesome_name = subject.ai multiline: true, raw: true
+      @type = subject.is_a?( Class ) ? :class : :module
+      
+    else
+      @name = subject.to_s
+      @awesome_name = subject.ai multiline: true, raw: true
+      @type = :instance
+      
+    end
+    
+    if level.nil?
+      # Allow the global default level to determine this loggers log level
+      @level_index = nil
+      @level       = nil
+    else
+      self.level = level
+    end
+  end
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # A sweet way to try something and just log any {Exception}.
+  # 
+  # Useful for situations where the operation is question is not necessary
+  # or can not be allowed to propagate errors, but you would like to record
+  # and/or let the user know that it failed.
+  # 
+  # Create a new {Catcher} for this logger that defines the log methods
+  # (`#error`, `warn`, ... `:trace`) to also accept blocks that will be
+  # executed in a `begin`/`rescue`.
+  # 
+  # If the block raises, the catcher will call the log method, adding the
+  # caught {Exception}.
+  # 
+  # @example Log any error as a warning
+  #   logger.catch.warn do
+  #     something_that_may_raise
+  #   end
+  #   
+  #   # We should "always" get to here
+  # 
+  # @example Log any error as warning with message and payload
+  #   logger.catch.warn(
+  #     "This thing failed!",
+  #     some_detail: some_value,
+  #   ) do
+  #     something_that_may_raise
+  #   end
+  #   
+  #   # We should "always" get to here
+  # 
+  # @example Return a custom value on error
+  #   result = logger.catch( on_fail: :blue ).debug do
+  #     what_is_your_favorite_color?
+  #   end
+  # 
+  # @param **options
+  #   Passed to {Catcher#initialize}.
+  # 
+  # @return [Catcher]
+  # 
+  def catch **options
+    Catcher.new self, **options
+  end # #catch
+  
+  
+  # Set the level for the execution of `&block`, restoring it to it's previous
+  # level afterwards.
+  # 
+  # Like what {SemanticLogger::Logger#silence} does (which just forwards to
+  # {SemanticLogger.silence}), but applies only to *this* logger (where as
+  # {SemanticLogger::Logger#silence} applies on to the global default level).
+  # 
+  # Useful for quickly turning down the log level to see trace/debug output
+  # from a specific section.
+  # 
+  # @param [Symbol?] level
+  #   One of {SemanticLogger::LEVELS} or `nil` to use the global default level.
+  # 
+  # @param [Proc<() => RESULT] &block
+  #   Block to execute with the `level`.
+  # 
+  # @return [RESULT]
+  #   Whatever `&block` returns.
+  # 
+  def with_level level, &block
+    prior_level = @level
+    self.level = level
+    
+    begin
+      block.call
+    ensure
+      self.level = prior_level
+    end
+  end
+  
+  
+end # class NRSER::Log::Logger

data/lib/nrser/log/mixin.rb

@@ -0,0 +1,56 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Definitions
+# =======================================================================
+
+# Adaptation of {SemanticLogger::Loggable} mixin to use {NRSER::Log::Logger}
+# instances from {NRSER::Log.[]}.
+# 
+# Like {SemanticLogger::Loggable} adds class and instance `logger` and
+# `logger=` methods that create loggers on demand and store them in the
+# `@semantic_logger` instance variables.
+# 
+module NRSER::Log::Mixin
+  
+  # Methods to mix into the including class.
+  # 
+  module ClassMethods
+    # Returns [SemanticLogger::Logger] class level logger
+    def logger
+      @semantic_logger ||= NRSER::Log[ self ]
+    end
+
+    # Replace instance class level logger
+    def logger= logger
+      @semantic_logger = logger
+    end
+  end
+  
+  
+  # Class Methods
+  # ========================================================================
+  
+  def self.included base
+    base.extend ClassMethods
+    
+    # Adds `.logger_measure_method`
+    base.extend SemanticLogger::Loggable::ClassMethods
+  end
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # Returns [SemanticLogger::Logger] instance level logger
+  def logger
+    @semantic_logger ||= self.class.logger
+  end
+  
+  
+  # Replace instance level logger
+  def logger= logger
+    @semantic_logger = logger
+  end
+  
+end # module NRSER::Log::Mixin