logging 1.7.2 → 1.8.0

data/.gitignore

@@ -10,3 +10,4 @@ doc/
 pkg/
 tmp/
 .rbx
+.rvmrc

data/History.txt

@@ -1,3 +1,13 @@
+== 1.8.0 / 2012-09-13
+
+Enhancements
+- Appenders handle string encodings [issue #46]
+- Support for diagnostic contexts [issues #23, #32, #42]
+- Enable JSON formatting of log message [issue #34]
+
+Bug Fixes
+- Fix clash with ActiveSupport autoloader (chewie) [issue #39]
+
 == 1.7.2 / 2012-04-03
 
 Bug Fixes

data/README.rdoc

@@ -2,7 +2,7 @@
 by Tim Pease {<img src="https://secure.travis-ci.org/TwP/logging.png">}[http://travis-ci.org/TwP/logging]
 
 * {Homepage}[http://rubygems.org/gems/logging]
-* {Github Project}[http://github.com/TwP/logging]
+* {Github Project}[https://github.com/TwP/logging]
 * email tim dot pease at gmail dot com
 
 == DESCRIPTION
@@ -78,17 +78,18 @@ the recommended way of accomplishing this.
 There are many more examples in the "examples" folder of the logging
 package. The recommended reading order is the following:
 
-* {simple.rb}[http://github.com/TwP/logging/blob/master/examples/simple.rb]
-* {loggers.rb}[http://github.com/TwP/logging/blob/master/examples/loggers.rb]
-* {classes.rb}[http://github.com/TwP/logging/blob/master/examples/classes.rb]
-* {hierarchies.rb}[http://github.com/TwP/logging/blob/master/examples/hierarchies.rb]
-* {names.rb}[http://github.com/TwP/logging/blob/master/examples/names.rb]
-* {appenders.rb}[http://github.com/TwP/logging/blob/master/examples/appenders.rb]
-* {layouts.rb}[http://github.com/TwP/logging/blob/master/examples/layouts.rb]
-* {formatting.rb}[http://github.com/TwP/logging/blob/master/examples/formatting.rb]
-* {colorization.rb}[http://github.com/TwP/logging/blob/master/examples/colorization.rb]
-* {consolidation.rb}[http://github.com/TwP/logging/blob/master/examples/consolidation.rb]
-* {fork.rb}[http://github.com/TwP/logging/blob/master/examples/fork.rb]
+* {simple.rb}[https://github.com/TwP/logging/blob/master/examples/simple.rb]
+* {loggers.rb}[https://github.com/TwP/logging/blob/master/examples/loggers.rb]
+* {classes.rb}[https://github.com/TwP/logging/blob/master/examples/classes.rb]
+* {hierarchies.rb}[https://github.com/TwP/logging/blob/master/examples/hierarchies.rb]
+* {names.rb}[https://github.com/TwP/logging/blob/master/examples/names.rb]
+* {appenders.rb}[https://github.com/TwP/logging/blob/master/examples/appenders.rb]
+* {layouts.rb}[https://github.com/TwP/logging/blob/master/examples/layouts.rb]
+* {formatting.rb}[https://github.com/TwP/logging/blob/master/examples/formatting.rb]
+* {colorization.rb}[https://github.com/TwP/logging/blob/master/examples/colorization.rb]
+* {consolidation.rb}[https://github.com/TwP/logging/blob/master/examples/consolidation.rb]
+* {fork.rb}[https://github.com/TwP/logging/blob/master/examples/fork.rb]
+* {mdc.rb}[https://github.com/TwP/logging/blob/master/examples/mdc.rb]
 
 == NOTES
 

data/Rakefile

@@ -22,9 +22,10 @@ Bones {
   use_gmail
 
   depend_on 'little-plugger'
+  depend_on 'multi_json'
 
-  depend_on 'flexmock',     :development => true
-  depend_on 'bones-git',    :development => true
+  depend_on 'flexmock', '~> 1.0',  :development => true
+  depend_on 'bones-git',           :development => true
   #depend_on 'bones-rcov',   :development => true
 }
 

data/examples/formatting.rb

@@ -5,14 +5,14 @@
 # "format_as" option and a global "backtrace" option.
 #
 # The format_as option allows objects to be converted to a string using the
-# standard "to_s" method, the "inspect" method, or the "to_yaml" method
-# (this is independent of the YAML layout). The format_as option can be
-# overridden by each layout as desired.
+# standard "to_s" method, the "inspect" method, the "to_json" method, or the
+# "to_yaml" method (this is independent of the YAML layout). The format_as
+# option can be overridden by each layout as desired.
 #
-#   Logging.format_as :string   # or :inspect or :yaml
+#   Logging.format_as :string   # or :inspect or :json or :yaml
 #
 # Exceptions are treated differently by the logging framework. The Exception
-# class is printed along with the message. Optionally, exception backtraces
+# class is printed along with the message. Optionally, the exception backtrace
 # can be included in the logging output; this option is enabled by default.
 #
 #   Logging.backtrace false

data/examples/mdc.rb

@@ -0,0 +1,83 @@
+# :stopdoc:
+#
+# A diagnostic context allows us to attach state information to every log
+# message. This is useful for applications that serve client requests -
+# information about the client can be included in the log messages for the
+# duration of the request processing. This allows you to identify related log
+# messages in concurrent system.
+#
+# The Mapped Diagnostic Context tracks state information in a collection of
+# key/value pairs. In this example we are creating a few threads that will log
+# quotes from famous people. Each thread has its own diagnostic context
+# containing the name of the famous person.
+#
+# Our PatternLayout is configured to attach the "first" and the "last" name of
+# our famous person to each log message.
+#
+
+  require 'logging'
+
+  # log the first and last names of the celebrity with each quote
+  Logging.appenders.stdout(
+    :layout => Logging.layouts.pattern(:pattern => '%X{first} %X{last}: %m\n')
+  )
+
+  log = Logging.logger['User']
+  log.add_appenders 'stdout'
+  log.level = :debug
+
+  Logging.mdc['first'] = 'John'
+  Logging.mdc['last']  = 'Doe'
+
+  # in this first thread we will log some quotes by Allan Rickman
+  t1 = Thread.new {
+    Logging.mdc['first'] = 'Allan'
+    Logging.mdc['last']  = 'Rickman'
+
+    [ %q{I've never been able to plan my life. I just lurch from indecision to indecision.},
+      %q{If only life could be a little more tender and art a little more robust.},
+      %q{I do take my work seriously and the way to do that is not to take yourself too seriously.},
+      %q{I'm a quite serious actor who doesn't mind being ridiculously comic.}
+    ].each { |quote|
+      sleep rand
+      log.info quote
+    }
+  }
+
+  # in this second thread we will log some quotes by William Butler Yeats
+  t2 = Thread.new {
+    Logging.mdc['first']  = 'William'
+    Logging.mdc['middle'] = 'Butler'
+    Logging.mdc['last']   = 'Yeats'
+
+    [ %q{Tread softly because you tread on my dreams.},
+      %q{The best lack all conviction, while the worst are full of passionate intensity.},
+      %q{Education is not the filling of a pail, but the lighting of a fire.},
+      %q{Do not wait to strike till the iron is hot; but make it hot by striking.},
+      %q{People who lean on logic and philosophy and rational exposition end by starving the best part of the mind.}
+    ].each { |quote|
+      sleep rand
+      log.info quote
+    }
+  }
+
+  # and in this third thread we will log some quotes by Bono
+  t3 = Thread.new {
+    Logging.mdc.clear  # otherwise we inherit the last name "Doe"
+    Logging.mdc['first'] = 'Bono'
+
+    [ %q{Music can change the world because it can change people.},
+      %q{The less you know, the more you believe.}
+    ].each { |quote|
+      sleep rand
+      log.info quote
+    }
+  }
+
+  t1.join
+  t2.join
+  t3.join
+
+  log.info %q{and now we are done}
+
+# :startdoc:

data/lib/logging.rb

@@ -9,6 +9,7 @@ require 'yaml'
 require 'stringio'
 require 'fileutils'
 require 'little-plugger'
+require 'multi_json'
 
 HAVE_SYSLOG = require? 'syslog'
 
@@ -319,6 +320,7 @@ module Logging
     # * :string  => to_s
     # * :inspect => inspect
     # * :yaml    => to_yaml
+    # * :json    => MultiJson.encode(obj)
     #
     # An +ArgumentError+ is raised if anything other than +:string+,
     # +:inspect+, +:yaml+ is passed to this method.
@@ -326,7 +328,7 @@ module Logging
     def format_as( f )
       f = f.intern if f.instance_of? String
 
-      unless [:string, :inspect, :yaml].include? f
+      unless [:string, :inspect, :yaml, :json].include? f
         raise ArgumentError, "unknown object format '#{f}'"
       end
 
@@ -508,6 +510,7 @@ module Logging
       ::Logging::Repository.reset
       ::Logging::Appenders.reset
       ::Logging::ColorScheme.reset
+      ::Logging.clear_diagnostic_contexts(true)
       LEVELS.clear
       LNAMES.clear
       remove_instance_variable :@backtrace if defined? @backtrace
@@ -534,6 +537,7 @@ module Logging
   require libpath('logging/appenders')
   require libpath('logging/layouts')
   require libpath('logging/proxy')
+  require libpath('logging/diagnostic_context')
 
   require libpath('logging/config/configurator')
   require libpath('logging/config/yaml_configurator')

data/lib/logging/appender.rb

@@ -31,6 +31,7 @@ class Appender
   #
   #    :layout   => the layout to use when formatting log events
   #    :level    => the level at which to log
+  #    :encoding => encoding to use when writing messages (defaults to UTF-8)
   #
   def initialize( name, opts = {} )
     ::Logging.init unless ::Logging.initialized?
@@ -40,6 +41,7 @@ class Appender
 
     self.layout = opts.getopt(:layout, ::Logging::Layouts::Basic.new)
     self.level = opts.getopt(:level)
+    self.encoding = opts.fetch(:encoding, self.encoding)
 
     @mutex = ReentrantMutex.new
 
@@ -231,6 +233,32 @@ class Appender
     ]
   end
 
+  # Returns the current Encoding for the appender or nil if an encoding has
+  # not been set.
+  #
+  def encoding
+    return @encoding if defined? @encoding
+    @encoding = Object.const_defined?(:Encoding) ? Encoding.default_external : nil
+  end
+
+  # Set the appender encoding to the given value. The value can either be an
+  # Encoding instance or a String or Symbol referring to a valid encoding.
+  #
+  # This method only applies to Ruby 1.9 or later. The encoding will always be
+  # nil for older Rubies.
+  #
+  # value - The encoding as a String, Symbol, or Encoding instance.
+  #
+  # Raises ArgumentError if the value is not a valid encoding.
+  #
+  def encoding=( value )
+    if value.nil?
+      @encoding = nil
+    else
+      @encoding = Object.const_defined?(:Encoding) ? Encoding.find(value.to_s) : nil
+    end
+  end
+
 
 private
 

data/lib/logging/appenders/buffering.rb

@@ -240,7 +240,10 @@ module Logging::Appenders
       if @auto_flushing == 1
         canonical_write(str)
       else
-        sync { @buffer << str }
+        sync {
+          str = str.force_encoding(encoding) if encoding and str.encoding != encoding
+          @buffer << str
+        }
         @periodic_flusher.signal if @periodic_flusher
         flush if @buffer.length >= @auto_flushing || immediate?(event)
       end

data/lib/logging/appenders/console.rb

@@ -33,6 +33,8 @@ module Logging::Appenders
       opts = Hash === args.last ? args.pop : {}
       name = args.empty? ? 'stdout' : args.shift
 
+      opts[:encoding] = STDOUT.external_encoding if STDOUT.respond_to? :external_encoding
+
       super(name, STDOUT, opts)
     end
   end  # Stdout
@@ -70,6 +72,8 @@ module Logging::Appenders
       opts = Hash === args.last ? args.pop : {}
       name = args.empty? ? 'stderr' : args.shift
 
+      opts[:encoding] = STDERR.external_encoding if STDERR.respond_to? :external_encoding
+
       super(name, STDERR, opts)
     end
   end  # Stderr

data/lib/logging/appenders/email.rb

@@ -158,6 +158,8 @@ module Logging::Appenders
       rfc822msg << "Subject: #{@subject}\n"
       rfc822msg << "Date: #{Time.new.rfc822}\n"
       rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
+
+      rfc822msg = rfc822msg.force_encoding(encoding) if encoding and rfc822msg.encoding != encoding
       rfc822msg << str
 
       ### send email

data/lib/logging/appenders/file.rb

@@ -54,6 +54,9 @@ module Logging::Appenders
       self.class.assert_valid_logfile(@fn)
       @mode = opts.getopt(:truncate) ? 'w' : 'a'
 
+      self.encoding = opts.fetch(:encoding, self.encoding)
+      @mode = "#{@mode}:#{self.encoding}" if self.encoding
+
       super(name, ::File.new(@fn, @mode), opts)
     end
 

data/lib/logging/appenders/io.rb

@@ -70,6 +70,7 @@ module Logging::Appenders
     #
     def canonical_write( str )
       return self if @io.nil?
+      str = str.force_encoding(encoding) if encoding and str.encoding != encoding
       @io.syswrite str
       self
     rescue StandardError => err

data/lib/logging/appenders/rolling_file.rb

@@ -142,7 +142,8 @@ module Logging::Appenders
 
       # we are opening the file in read/write mode so that a shared lock can
       # be used on the file descriptor => http://pubs.opengroup.org/onlinepubs/009695399/functions/fcntl.html
-      super(name, ::File.new(@fn, 'a+'), opts)
+      @mode = encoding ? "a+:#{encoding}" : 'a+'
+      super(name, ::File.new(@fn, @mode), opts)
 
       # setup the file roller
       @roller =
@@ -177,7 +178,7 @@ module Logging::Appenders
           flush
           @io.close rescue nil
         end
-        @io = ::File.new(@fn, 'a+')
+        @io = ::File.new(@fn, @mode)
       }
       super
       self
@@ -193,7 +194,8 @@ module Logging::Appenders
     def canonical_write( str )
       return self if @io.nil?
 
-      @io.flock_sh { @io.syswrite(str) }
+      str = str.force_encoding(encoding) if encoding and str.encoding != encoding
+      @io.flock_sh { @io.syswrite str }
 
       if roll_required?
         @io.flock? {

data/lib/logging/appenders/string_io.rb

@@ -60,7 +60,7 @@ module Logging::Appenders
     alias :reset :clear
 
     %w[read readline readlines].each do|m|
-      class_eval <<-CODE
+      class_eval <<-CODE, __FILE__, __LINE__+1
         def #{m}( *args )
           sync {
             begin

data/lib/logging/color_scheme.rb

@@ -203,9 +203,8 @@ module Logging
     # Return a normalized representation of a color setting.
     #
     def to_constant( v )
-      ColorScheme.const_get(v.to_s.upcase)
-    rescue NameError
-      return  nil
+      v = v.to_s.upcase
+      ColorScheme.const_get(v) if (ColorScheme.const_defined?(v, false) rescue ColorScheme.const_defined?(v))
     end
 
     # Embed in a String to clear all previous ANSI sequences.  This *MUST* be

data/lib/logging/diagnostic_context.rb

@@ -0,0 +1,330 @@
+
+module Logging
+
+  # 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
+        Thread.exclusive {
+          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 `Logging.ndc.push`
+  # * When leaving a context, call `Logging.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
+        Thread.exclusive {
+          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 Logging module.
+  #
+  def self.clear_diagnostic_contexts( all = false )
+    if all
+      Thread.exclusive {
+        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
+
+end  # module Logging
+
+
+# :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 )
+      p_mdc, p_ndc = nil
+
+      if Thread.current[Logging::MappedDiagnosticContext::NAME]
+        p_mdc = Thread.current[Logging::MappedDiagnosticContext::NAME].dup
+      end
+
+      if Thread.current[Logging::NestedDiagnosticContext::NAME]
+        p_ndc = Thread.current[Logging::NestedDiagnosticContext::NAME].dup
+      end
+
+      self.send(m, p_mdc, p_ndc, *a) { |mdc, ndc, *args|
+        Logging::MappedDiagnosticContext.inherit(mdc)
+        Logging::NestedDiagnosticContext.inherit(ndc)
+        b.call(*args)
+      }
+    end
+
+  end
+end  # Thread
+# :startdoc:
+