logsly 1.2.0 → 1.3.0

data/lib/logsly/logging182/config/configurator.rb

@@ -0,0 +1,187 @@
+
+module Logsly::Logging182::Config
+
+  # The Configurator class is used to configure the Logsly::Logging182 framework
+  # using information found in a block of Ruby code. This block is evaluated
+  # in the context of the configurator's DSL.
+  #
+  class Configurator
+
+    class Error < StandardError; end  # :nodoc:
+
+    # call-seq:
+    #    Configurator.process( &block )
+    #
+    def self.process( &block )
+      new.load(&block)
+    end
+
+    # call-seq:
+    #    load { block }
+    #
+    # Loads the configuration from the _block_ and configures the Logsly::Logging182
+    # gem.
+    #
+    def load( &block )
+      raise Error, "missing configuration block" unless block
+
+      dsl = TopLevelDSL.new
+      dsl.instance_eval(&block)
+
+      pre_config dsl.__pre_config
+      ::Logsly::Logging182::Logger[:root]  # ensures the log levels are defined
+      appenders  dsl.__appenders
+      loggers    dsl.__loggers
+    end
+
+    # call-seq:
+    #    pre_config( config )
+    #
+    # Configures the logging levels, object format style, and root logging
+    # level.
+    #
+    def pre_config( config )
+      if config.nil?
+        ::Logsly::Logging182.init unless ::Logsly::Logging182.initialized?
+        return
+      end
+
+      # define levels
+      levels = config[:levels]
+      ::Logsly::Logging182.init(levels) unless levels.nil?
+
+      # format as
+      format = config[:format_as]
+      ::Logsly::Logging182.format_as(format) unless format.nil?
+
+      # backtrace
+      value = config[:backtrace]
+      ::Logsly::Logging182.backtrace(value) unless value.nil?
+    end
+
+    # call-seq:
+    #    appenders( ary )
+    #
+    # Given an array of Appender configurations, this method will iterate
+    # over each and create the Appender(s).
+    #
+    def appenders( ary )
+      ary.each {|name, config| appender(name, config)}
+    end
+
+    # call-seq:
+    #    loggers( ary )
+    #
+    # Given an array of Logger configurations, this method will iterate over
+    # each and create the Logger(s).
+    #
+    def loggers( ary )
+      ary.each do |name, config|
+        l = Logsly::Logging182::Logger[name]
+        l.level     = config[:level] if config[:level]
+        l.additive  = config[:additive] if l.respond_to? :additive=
+        l.trace     = config[:trace]
+        l.appenders = Array(config[:appenders]).
+                            map {|nm| ::Logsly::Logging182::Appenders[nm]}
+      end
+    end
+
+    # call-seq:
+    #    appender( name, config )
+    #
+    # Creates a new Appender based on the given _config_ options (a hash).
+    # The type of Appender created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Appender
+    # initializer.
+    #
+    # The config options can also contain a 'layout' option. This should be
+    # another set of options used to create a Layout for this Appender.
+    #
+    def appender( name, config )
+      type = config.delete(:type)
+      raise Error, "appender type not given for #{name.inspect}" if type.nil?
+
+      config[:layout] = layout(config[:layout]) if config.has_key? :layout
+
+      clazz = ::Logsly::Logging182::Appenders.const_get type
+      clazz.new(name, config)
+    rescue NameError
+      raise Error, "unknown appender class Logsly::Logging182::Appenders::#{type}"
+    end
+
+    # call-seq:
+    #    layout( config )
+    #
+    # Creates a new Layout based on the given _config_ options (a hash).
+    # The type of Layout created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Layout
+    # initializer.
+    #
+    def layout( config )
+      return ::Logsly::Logging182::Layouts::Basic.new if config.nil?
+
+      type = config.delete(:type)
+      raise Error, 'layout type not given' if type.nil?
+
+      clazz = ::Logsly::Logging182::Layouts.const_get type
+      clazz.new config
+    rescue NameError
+      raise Error, "unknown layout class Logsly::Logging182::Layouts::#{type}"
+    end
+
+    class DSL
+      instance_methods.each do |m|
+        undef_method m unless m[%r/^(__|object_id|instance_eval)/]
+      end
+
+      def self.process( &block )
+        dsl = new
+        dsl.instance_eval(&block)
+        dsl.__hash
+      end
+
+      def __hash
+        @hash ||= Hash.new
+      end
+
+      def method_missing( method, *args, &block )
+        args << DSL.process(&block) if block
+
+        key = method.to_sym
+        value = (1 == args.length ? args.first : args)
+        __store(key, value)
+      end
+
+      def __store( key, value )
+        __hash[key] = value
+      end
+    end
+
+    class TopLevelDSL < DSL
+      undef_method :method_missing
+
+      def initialize
+        @loggers = []
+        @appenders = []
+      end
+
+      def pre_config( &block )
+        __store(:preconfig, DSL.process(&block))
+      end
+
+      def logger( name, &block )
+        @loggers << [name, DSL.process(&block)]
+      end
+
+      def appender( name, &block )
+        @appenders << [name, DSL.process(&block)]
+      end
+
+      def __pre_config() __hash[:preconfig]; end
+      def __loggers() @loggers; end
+      def __appenders() @appenders; end
+    end
+
+  end  # class Configurator
+end  # module Logsly::Logging182::Config
+

data/lib/logsly/logging182/config/yaml_configurator.rb

@@ -0,0 +1,190 @@
+
+module Logsly::Logging182::Config
+
+  # The YamlConfigurator class is used to configure the Logsly::Logging182 framework
+  # using information found in a YAML file.
+  #
+  class YamlConfigurator
+
+    class Error < StandardError; end  # :nodoc:
+
+    class << self
+
+      # call-seq:
+      #    YamlConfigurator.load( file, key = 'logging_config' )
+      #
+      # Load the given YAML _file_ and use it to configure the Logsly::Logging182
+      # framework. The file can be either a filename, and open File, or an
+      # IO object. If it is the latter two, the File / IO object will not be
+      # closed by this method.
+      #
+      # The configuration will be loaded from the given _key_ in the YAML
+      # stream.
+      #
+      def load( file, key = 'logging_config' )
+        io, close = nil, false
+        case file
+        when String
+          io = File.open(file, 'r')
+          close = true
+        when IO
+          io = file
+        else
+          raise Error, 'expecting a filename or a File'
+        end
+
+        begin
+          new(io, key).load
+        ensure
+          io.close if close
+        end
+        nil
+      end
+    end  # class << self
+
+    # call-seq:
+    #    YamlConfigurator.new( io, key )
+    #
+    # Creates a new YAML configurator that will load the Logsly::Logging182
+    # configuration from the given _io_ stream. The configuration will be
+    # loaded from the given _key_ in the YAML stream.
+    #
+    def initialize( io, key  )
+      YAML.load_documents(io) do |doc|
+        @config = doc[key]
+        break if @config.instance_of?(Hash)
+      end
+
+      unless @config.instance_of?(Hash)
+        raise Error, "Key '#{key}' not defined in YAML configuration"
+      end
+    end
+
+    # call-seq:
+    #    load
+    #
+    # Loads the Logsly::Logging182 configuration from the data loaded from the YAML
+    # file.
+    #
+    def load
+      pre_config @config['pre_config']
+      ::Logsly::Logging182::Logger[:root]  # ensures the log levels are defined
+      appenders @config['appenders']
+      loggers @config['loggers']
+    end
+
+    # call-seq:
+    #    pre_config( config )
+    #
+    # Configures the logging levels, object format style, and root logging
+    # level.
+    #
+    def pre_config( config )
+      # if no pre_config section was given, just create an empty hash
+      # we do this to ensure that some logging levels are always defined
+      config ||= Hash.new
+
+      # define levels
+      levels = config['define_levels']
+      ::Logsly::Logging182.init(levels) unless levels.nil?
+
+      # format as
+      format = config['format_as']
+      ::Logsly::Logging182.format_as(format) unless format.nil?
+
+      # backtrace
+      value = config['backtrace']
+      ::Logsly::Logging182.backtrace(value) unless value.nil?
+
+      # grab the root logger and set the logging level
+      root = ::Logsly::Logging182::Logger.root
+      if config.has_key?('root')
+        root.level = config['root']['level']
+      end
+    end
+
+    # call-seq:
+    #    appenders( ary )
+    #
+    # Given an array of Appender configurations, this method will iterate
+    # over each and create the Appender(s).
+    #
+    def appenders( ary )
+      return if ary.nil?
+
+      ary.each {|h| appender(h)}
+    end
+
+    # call-seq:
+    #    loggers( ary )
+    #
+    # Given an array of Logger configurations, this method will iterate over
+    # each and create the Logger(s).
+    #
+    def loggers( ary )
+      return if ary.nil?
+
+      ary.each do |config|
+        name = config['name']
+        raise Error, 'Logger name not given' if name.nil?
+
+        l = Logsly::Logging182::Logger.new name
+        l.level = config['level'] if config.has_key?('level')
+        l.additive = config['additive'] if l.respond_to? :additive=
+        l.trace = config['trace'] if l.respond_to? :trace=
+
+        if config.has_key?('appenders')
+          l.appenders = config['appenders'].map {|n| ::Logsly::Logging182::Appenders[n]}
+        end
+      end
+    end
+
+    # call-seq:
+    #    appender( config )
+    #
+    # Creates a new Appender based on the given _config_ options (a hash).
+    # The type of Appender created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Appender
+    # initializer.
+    #
+    # The config options can also contain a 'layout' option. This should be
+    # another set of options used to create a Layout for this Appender.
+    #
+    def appender( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Appender type not given' if type.nil?
+
+      name = config.delete('name')
+      raise Error, 'Appender name not given' if name.nil?
+
+      config['layout'] = layout(config.delete('layout'))
+
+      clazz = ::Logsly::Logging182::Appenders.const_get type
+      clazz.new(name, config)
+    end
+
+    # call-seq:
+    #    layout( config )
+    #
+    # Creates a new Layout based on the given _config_ options (a hash).
+    # The type of Layout created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Layout
+    # initializer.
+    #
+    def layout( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Layout type not given' if type.nil?
+
+      clazz = ::Logsly::Logging182::Layouts.const_get type
+      clazz.new config
+    end
+
+  end  # class YamlConfigurator
+end  # module Logsly::Logging182::Config
+

data/lib/logsly/logging182/diagnostic_context.rb

@@ -0,0 +1,332 @@
+
+module Logsly::Logging182
+
+  # A Mapped Diagnostic Context, or MDC in short, is an instrument used to
+  # distinguish interleaved log output from different sources. Log output is
+  # typically interleaved when a server handles multiple clients
+  # near-simultaneously.
+  #
+  # Interleaved log output can still be meaningful if each log entry from
+  # different contexts had a distinctive stamp. This is where MDCs come into
+  # play.
+  #
+  # The MDC provides a hash of contextual messages that are identified by
+  # unique keys. These unique keys are set by the application and appended
+  # to log messages to identify groups of log events. One use of the Mapped
+  # Diagnostic Context is to store HTTP request headers associated with a Rack
+  # request. These headers can be included with all log messages emitted while
+  # generating the HTTP response.
+  #
+  # When configured to do so, PatternLayout instances will automatically
+  # retrieve the mapped diagnostic context for the current thread with out any
+  # user intervention. This context information can be used to track user
+  # sessions in a Rails application, for example.
+  #
+  # Note that MDCs are managed on a per thread basis. MDC operations such as
+  # `[]`, `[]=`, and `clear` affect the MDC of the current thread only. MDCs
+  # of other threads remain unaffected.
+  #
+  # By default, when a new thread is created it will inherit the context of
+  # its parent thread. However, the `inherit` method may be used to inherit
+  # context for any other thread in the application.
+  #
+  module MappedDiagnosticContext
+    extend self
+
+    # The name used to retrieve the MDC from thread-local storage.
+    NAME = 'logging.mapped-diagnostic-context'.freeze
+
+    # Public: Put a context value as identified with the key parameter into
+    # the current thread's context map.
+    #
+    # key   - The String identifier for the context.
+    # value - The String value to store.
+    #
+    # Returns the value.
+    #
+    def []=( key, value )
+      context.store(key.to_s, value)
+    end
+
+    # Public: Get the context value identified with the key parameter.
+    #
+    # key - The String identifier for the context.
+    #
+    # Returns the value associated with the key or nil if there is no value
+    # present.
+    #
+    def []( key )
+      context.fetch(key.to_s, nil)
+    end
+
+    # Public: Remove the context value identified with the key parameter.
+    #
+    # key - The String identifier for the context.
+    #
+    # Returns the value associated with the key or nil if there is no value
+    # present.
+    #
+    def delete( key )
+      context.delete(key.to_s)
+    end
+
+    # Public: Clear all mapped diagnostic information if any. This method is
+    # useful in cases where the same thread can be potentially used over and
+    # over in different unrelated contexts.
+    #
+    # Returns the MappedDiagnosticContext.
+    #
+    def clear
+      context.clear if Thread.current[NAME]
+      self
+    end
+
+    # Public: Inherit the diagnostic context of another thread. In the vast
+    # majority of cases the other thread will the parent that spawned the
+    # current thread. The diagnostic context from the parent thread is cloned
+    # before being inherited; the two diagnostic contexts can be changed
+    # independently.
+    #
+    # Returns the MappedDiagnosticContext.
+    #
+    def inherit( obj )
+      case obj
+      when Hash
+        Thread.current[NAME] = obj.dup
+      when Thread
+        return if Thread.current == obj
+        DIAGNOSTIC_MUTEX.synchronize {
+          Thread.current[NAME] = obj[NAME].dup if obj[NAME]
+        }
+      end
+
+      self
+    end
+
+    # Returns the Hash acting as the storage for this NestedDiagnosticContext.
+    # A new storage Hash is created for each Thread running in the
+    # application.
+    #
+    def context
+      Thread.current[NAME] ||= Hash.new
+    end
+  end  # MappedDiagnosticContext
+
+
+  # A Nested Diagnostic Context, or NDC in short, is an instrument to
+  # distinguish interleaved log output from different sources. Log output is
+  # typically interleaved when a server handles multiple clients
+  # near-simultaneously.
+  #
+  # Interleaved log output can still be meaningful if each log entry from
+  # different contexts had a distinctive stamp. This is where NDCs come into
+  # play.
+  #
+  # The NDC is a stack of contextual messages that are pushed and popped by
+  # the client as different contexts are encountered in the application. When a
+  # new context is entered, the client will `push` a new message onto the NDC
+  # stack. This message appears in all log messages. When this context is
+  # exited, the client will call `pop` to remove the message.
+  #
+  # * Contexts can be nested
+  # * When entering a context, call `Logsly::Logging182.ndc.push`
+  # * When leaving a context, call `Logsly::Logging182.ndc.pop`
+  # * Configure the PatternLayout to log context information
+  #
+  # There is no penalty for forgetting to match each push operation with a
+  # corresponding pop, except the obvious mismatch between the real
+  # application context and the context set in the NDC.
+  #
+  # When configured to do so, PatternLayout instance will automatically
+  # retrieve the nested diagnostic context for the current thread with out any
+  # user intervention. This context information can be used to track user
+  # sessions in a Rails application, for example.
+  #
+  # Note that NDCs are managed on a per thread basis. NDC operations such as
+  # `push`, `pop`, and `clear` affect the NDC of the current thread only. NDCs
+  # of other threads remain unaffected.
+  #
+  # By default, when a new thread is created it will inherit the context of
+  # its parent thread. However, the `inherit` method may be used to inherit
+  # context for any other thread in the application.
+  #
+  module NestedDiagnosticContext
+    extend self
+
+    # The name used to retrieve the NDC from thread-local storage.
+    NAME = 'logging.nested-diagnostic-context'.freeze
+
+    # Public: Push new diagnostic context information for the current thread.
+    # The contents of the message parameter is determined solely by the
+    # client.
+    #
+    # message - The message String to add to the current context.
+    #
+    # Returns the current NestedDiagnosticContext.
+    #
+    def push( message )
+      context.push(message)
+      self
+    end
+    alias :<< :push
+
+    # Public: Clients should call this method before leaving a diagnostic
+    # context. The returned value is the last pushed message. If no
+    # context is available then `nil` is returned.
+    #
+    # Returns the last pushed diagnostic message String or nil if no messages
+    # exist.
+    #
+    def pop
+      context.pop
+    end
+
+    # Public: Looks at the last diagnostic context at the top of this NDC
+    # without removing it. The returned value is the last pushed message. If
+    # no context is available then `nil` is returned.
+    #
+    # Returns the last pushed diagnostic message String or nil if no messages
+    # exist.
+    #
+    def peek
+      context.last
+    end
+
+    # Public: Clear all nested diagnostic information if any. This method is
+    # useful in cases where the same thread can be potentially used over and
+    # over in different unrelated contexts.
+    #
+    # Returns the NestedDiagnosticContext.
+    #
+    def clear
+      context.clear if Thread.current[NAME]
+      self
+    end
+
+    # Public: Inherit the diagnostic context of another thread. In the vast
+    # majority of cases the other thread will the parent that spawned the
+    # current thread. The diagnostic context from the parent thread is cloned
+    # before being inherited; the two diagnostic contexts can be changed
+    # independently.
+    #
+    # Returns the NestedDiagnosticContext.
+    #
+    def inherit( obj )
+      case obj
+      when Array
+        Thread.current[NAME] = obj.dup
+      when Thread
+        return if Thread.current == obj
+        DIAGNOSTIC_MUTEX.synchronize {
+          Thread.current[NAME] = obj[NAME].dup if obj[NAME]
+        }
+      end
+
+      self
+    end
+
+    # Returns the Array acting as the storage stack for this
+    # NestedDiagnosticContext. A new storage Array is created for each Thread
+    # running in the application.
+    #
+    def context
+      Thread.current[NAME] ||= Array.new
+    end
+  end  # NestedDiagnosticContext
+
+
+  # Public: Accessor method for getting the current Thread's
+  # MappedDiagnosticContext.
+  #
+  # Returns MappedDiagnosticContext
+  #
+  def self.mdc() MappedDiagnosticContext end
+
+  # Public: Accessor method for getting the current Thread's
+  # NestedDiagnosticContext.
+  #
+  # Returns NestedDiagnosticContext
+  #
+  def self.ndc() NestedDiagnosticContext end
+
+  # Public: Convenience method that will clear both the Mapped Diagnostic
+  # Context and the Nested Diagnostic Context of the current thread. If the
+  # `all` flag passed to this method is true, then the diagnostic contexts for
+  # _every_ thread in the application will be cleared.
+  #
+  # all - Boolean flag used to clear the context of every Thread (default is false)
+  #
+  # Returns the Logsly::Logging182 module.
+  #
+  def self.clear_diagnostic_contexts( all = false )
+    if all
+      DIAGNOSTIC_MUTEX.synchronize {
+        Thread.list.each { |thread|
+          thread[MappedDiagnosticContext::NAME].clear if thread[MappedDiagnosticContext::NAME]
+          thread[NestedDiagnosticContext::NAME].clear if thread[NestedDiagnosticContext::NAME]
+        }
+      }
+    else
+      MappedDiagnosticContext.clear
+      NestedDiagnosticContext.clear
+    end
+
+    self
+  end
+
+  DIAGNOSTIC_MUTEX = Mutex.new
+
+end  # module Logsly::Logging182
+
+
+# :stopdoc:
+class Thread
+  class << self
+
+    %w[new start fork].each do |m|
+      class_eval <<-__, __FILE__, __LINE__
+        alias :_orig_#{m} :#{m}
+        private :_orig_#{m}
+        def #{m}( *a, &b )
+          create_with_logging_context(:_orig_#{m}, *a ,&b)
+        end
+      __
+    end
+
+  private
+
+    # In order for the diagnostic contexts to behave properly we need to
+    # inherit state from the parent thread. The only way I have found to do
+    # this in Ruby is to override `new` and capture the contexts from the
+    # parent Thread at the time the child Thread is created. The code below does
+    # just this. If there is a more idiomatic way of accomplishing this in Ruby,
+    # please let me know!
+    #
+    # Also, great care is taken in this code to ensure that a reference to the
+    # parent thread does not exist in the binding associated with the block
+    # being executed in the child thread. The same is true for the parent
+    # thread's mdc and ndc. If any of those references end up in the binding,
+    # then they cannot be garbage collected until the child thread exits.
+    #
+    def create_with_logging_context( m, *a, &b )
+      mdc, ndc = nil
+
+      if Thread.current[Logsly::Logging182::MappedDiagnosticContext::NAME]
+        mdc = Thread.current[Logsly::Logging182::MappedDiagnosticContext::NAME].dup
+      end
+
+      if Thread.current[Logsly::Logging182::NestedDiagnosticContext::NAME]
+        ndc = Thread.current[Logsly::Logging182::NestedDiagnosticContext::NAME].dup
+      end
+
+      self.send(m, *a) { |*args|
+        Logsly::Logging182::MappedDiagnosticContext.inherit(mdc)
+        Logsly::Logging182::NestedDiagnosticContext.inherit(ndc)
+        b.call(*args)
+      }
+    end
+
+  end
+end  # Thread
+# :startdoc:
+