lumberjack 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e1af0567acc694ebd29f04587e9203db03d14958306abd6a691721c918cd024
-  data.tar.gz: 0eab429fc4ef909b57cec680fc84ab5cb12fd99a0e986d105d497be9dee97369
+  metadata.gz: e2209d8f5b5a64c28765eb9e0756c2723354430017e8fc718ed1238678534f62
+  data.tar.gz: 3f7d07d946b9975962e9c25186cffab9a2529142430ecd1a833ba7a3bcb4dc9f
 SHA512:
-  metadata.gz: 3894fec45c2f423348c6926c5bef9c1aff794e5e3d7e11394bd791be74d606ad0ad4e5613c7295b9b4051af3a6f9089a6ac60ade8f86a7a407f4d346fcb80df7
-  data.tar.gz: 608590677da050618459e44be516f72b00d9a8e8db7edc2be63fc7622864936db74b429ce013b2e12c75da9d65e5b89b289b49cecf2683803353a2832f45463a
+  metadata.gz: 7a2c5fc583af252f983e936ed54fe75a40a3f36eec349f6ba219f798129d86022d33c4a65e3aca72d75f7c1a8a14900f94d2cea6ab74d03f96607306a5b0fde9
+  data.tar.gz: d8c7de0eb56182e0ca30c76a477281cd13fd7c728e4f837e0adc578ade6056177fcd4375c67a38e1bd85e788520f14a9c2bde6315313f368e53413eb622aae21

data/ARCHITECTURE.md

@@ -148,21 +148,6 @@ classDiagram
         +reopen(logdev) void
     }
 
-    class DeviceDateRollingLogFile["Device::DateRollingLogFile"] {
-        +String path
-        +String frequency
-        +initialize(path, options)
-        +roll_file?() Boolean
-    }
-
-    class DeviceSizeRollingLogFile["Device::SizeRollingLogFile"] {
-        +String path
-        +Integer max_size
-        +Integer keep
-        +initialize(path, options)
-        +roll_file?() Boolean
-    }
-
     class DeviceMulti["Device::Multi"] {
         +Array devices
         +initialize(*devices)
@@ -251,8 +236,6 @@ classDiagram
     Device <|-- DeviceNull : implements
     Device <|-- DeviceLoggerWrapper : implements
     DeviceWriter <|-- DeviceLogFile : inherits
-    DeviceLogFile <|-- DeviceDateRollingLogFile : inherits
-    DeviceLogFile <|-- DeviceSizeRollingLogFile : inherits
 
     DeviceWriter --* Template : uses
     DeviceWriter --* DeviceBuffer : uses

data/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.1.0
+
+### Added
+
+- Added `Lumberjack::LogEntryMatcher#diff` which returns only the fields that do not match a log entry, with the expected and actual values. This can be used to diagnose why a test assertion failed.
+- Added a `formatter` option to `Lumberjack::LogEntryMatcher`. Filter values are compared raw first; if that fails, they are formatted with the entry formatter and compared again. This allows expectations to be written with unformatted values (an Exception, for example) and still match the formatted values captured on a log entry. `#diff` reports expected values in their formatted form so both sides of a mismatch are in the same form.
+- Added `Lumberjack::Device::Test#entry_formatter` (also settable with the `:entry_formatter` option) which is used as the default formatter for `include?`, `match`, and `closest_match`. Those methods also accept a per call `formatter` argument.
+
+### Fixed
+
+- `Lumberjack::Device::Multi#reopen` now passes the log destination through to the wrapped devices instead of always passing `nil`.
+- `Lumberjack::Device::Multi#datetime_format` no longer raises an error when none of the wrapped devices have a datetime format.
+- `Lumberjack::TemplateRegistry.registered?` no longer raises a `NoMethodError`.
+- `Lumberjack::Formatter::TagsFormatter` no longer raises an error on non-string tag values and now returns an empty string instead of `nil` for empty tag arrays.
+- The `before_flush` callback on `Lumberjack::Device::Buffer` is now invoked outside of the buffer lock so callbacks that log or flush no longer deadlock. As a result, the callback may be invoked concurrently by multiple threads and must be thread safe if it modifies shared state.
+- Hardened `Lumberjack::Device::Buffer` against race conditions that could drop entries when writing concurrently with `flush` or `close`. Concurrent flushes are now serialized so buffered batches can no longer be interleaved or reordered when written to the wrapped device.
+- `Lumberjack::Device::Test#clear` and `#last_entry` are now thread safe.
+- Device, formatter, and template registries are now thread safe.
+- Log entries no longer share their attributes hash with the caller, so mutating a logging context after an entry was created no longer changes entries held in memory by buffered or test devices.
+- Contexts no longer share array attribute values with their parent context, so appending to an inherited array attribute no longer mutates the parent context.
+- `Lumberjack.context` called without a block now returns the current context as documented instead of raising an `ArgumentError`.
+- Renamed misspelled `Lumberjack::Formatter::StructuredFormatter::RecusiveReferenceError` to `RecursiveReferenceError`. The old constant is kept as an alias for backward compatibility.
+- `Lumberjack::LogEntryMatcher` no longer ignores an `attributes` filter that is not a hash. Passing a matcher like RSpec's `hash_including` as the entire filter silently matched every entry; it is now applied to the entry's attributes hash with `===`.
+- `Lumberjack::LogEntryMatcher` now exposes log entry attributes to matchers with indifferent key access, so matchers that do their own key lookups (i.e. RSpec's `hash_including`) can use either string or symbol attribute names.
+
+### Removed
+
+- Removed the methods, arguments, and classes that were deprecated in version 2.0.
+  - `Lumberjack.context?` (use `Lumberjack.in_context?`)
+  - `Lumberjack.context_tags` (use `Lumberjack.context_attributes`)
+  - `Lumberjack::Logger#tags` (use `#attributes`)
+  - `Lumberjack::Logger#tag_value` (use `#attribute_value`)
+  - `Lumberjack::Logger#tag_globally` (use `#tag!`)
+  - `Lumberjack::Logger#in_tag_context?` (use `#in_context?`)
+  - `Lumberjack::Logger#remove_tag` (use `#untag` or `#untag!`)
+  - `Lumberjack::Logger#tag_formatter` and `#tag_formatter=` (use `#attribute_formatter` and `#attribute_formatter=`)
+  - `Lumberjack::Logger#set_progname` (use `#with_progname` or `#progname=`)
+  - `Lumberjack::Logger#tagged`, `#untagged`, `#log_at`, and `#silence` (install the `lumberjack_rails` gem or use `#append_to`, `#clear_attributes`, and `#with_level`)
+  - Passing an options hash as the second argument to `Lumberjack::Logger.new` (use keyword arguments)
+  - The `:roll`, `:max_size`, `:message_formatter`, and `:tag_formatter` options on `Lumberjack::Logger.new` (use the `shift_age`, `shift_size`, and `formatter` arguments)
+  - `Lumberjack::LogEntry#tags`, `#tag`, and `#nested_tags` (use `#attributes`, `#[]`, and `#nested_attributes`)
+  - `Lumberjack::Formatter.empty` (use `.new`)
+  - `Lumberjack::AttributeFormatter#add` and `#remove` (use `#add_class`/`#add_attribute` and `#remove_class`/`#remove_attribute`)
+  - `Lumberjack::Utils.flatten_tags` and `.expand_tags` (use `.flatten_attributes` and `.expand_attributes`)
+  - `Lumberjack::TagFormatter` (use `Lumberjack::AttributeFormatter`)
+  - `Lumberjack::TagContext` (use `Lumberjack::AttributesHelper`)
+  - `Lumberjack::Tags` (use `Lumberjack::AttributesHelper`)
+  - `Lumberjack::Formatter::TaggedMessage` (use `Lumberjack::MessageAttributes`)
+  - `Lumberjack::Device::DateRollingLogFile` and `Lumberjack::Device::SizeRollingLogFile` (use `Lumberjack::Device::LogFile`)
+  - `Lumberjack::Formatter::StructuredFormatter::RecusiveReferenceError` misspelled alias (use `RecursiveReferenceError`)
+  - Version 1.x template syntax using `:placeholder` (use `{{placeholder}}`)
+
 ## 2.0.5
 
 ### Added

data/README.md

@@ -724,6 +724,41 @@ You should make sure to call `logger.device.clear` between tests to clear the ca
 > [!NOTE]
 > Log entries are captured after formatters have been applied. This provides a mechanism for including the formatting logic in your tests.
 
+Since entries are captured after formatting, you can set an entry formatter on the `Test` device to write expectations with unformatted values. Filter values are compared raw first; if that fails, they are formatted and compared again.
+
+```ruby
+formatter = Lumberjack::EntryFormatter.build do |config|
+  config.format_message(Exception) do |e|
+    Lumberjack::MessageAttributes.new(e.inspect, {error: {kind: e.class.name, message: e.message, trace: e.backtrace}})
+  end
+  config.format_attributes(Exception) do |e|
+    {kind: e.class.name, message: e.message, trace: e.backtrace}
+  end
+end
+
+logger = Lumberjack::Logger.new(:test, formatter: formatter)
+logger.device.entry_formatter = logger.formatter
+
+exception = RuntimeError.new("boom")
+logger.error(exception)
+
+# These all match the same entry.
+expect(logger.device).to include(message: exception)
+expect(logger.device).to include(message: exception.inspect, attributes: {error: exception})
+expect(logger.device).to include(
+  message: exception.inspect,
+  attributes: {error: {kind: "RuntimeError", message: "boom"}}
+)
+```
+
+You can use `Lumberjack::LogEntryMatcher#diff` to see why an entry did not match. It returns only the fields that do not match, with the expected and actual values.
+
+```ruby
+matcher = Lumberjack::LogEntryMatcher.new(message: "User logged in", attributes: {user_id: 456})
+matcher.diff(logger.device.last_entry)
+# => {"attributes" => {"user_id" => {expected: 456, actual: 123}}}
+```
+
 > [!TIP]
 > The [lumberjack_capture_device](https://github.com/bdurand/lumberjack_capture_device) gem provides some additional testing utilities and rspec integration.
 

data/UPGRADE_GUIDE.md

@@ -45,7 +45,7 @@ logger.tag(attributes) do
 end
 ```
 
-Internal uses of the word "tag" have all been updated to use "attribute" instead. The "tag" versions of the methods will still work, but they have been [marked as deprecated](CHANGELOG.md#deprecated) and will be removed in a future version.
+Internal uses of the word "tag" have all been updated to use "attribute" instead. The "tag" versions of the methods still work in version 2.0, but they are deprecated and have been removed in version 2.1.
 
 Global attributes are now set with the `tag!` method instead of `tag_globally` or calling `tag` outside of a context.
 

data/VERSION

@@ -1 +1 @@
-2.0.5
+2.1.0

data/lib/lumberjack/attribute_formatter.rb

@@ -95,37 +95,6 @@ module Lumberjack
       self
     end
 
-    # Add formatters for specific attribute names or object classes. This is a convenience method
-    # that automatically delegates to {#add_class} or {#add_attribute} based on the input type.
-    #
-    # When you pass a Module/Class, it creates a class-based formatter that applies to all
-    # attribute values of that type. When you pass a String, it creates an attribute-specific
-    # formatter for that exact attribute name.
-    #
-    # Class formatters are applied recursively to nested hashes and arrays, making them
-    # powerful for formatting complex nested structures.
-    #
-    # @param names_or_classes [String, Module, Array<String, Module>] Attribute names or object classes.
-    # @param formatter [Lumberjack::Formatter, #call, Symbol, nil] The formatter to use.
-    # @yield [value] Block-based formatter that receives the attribute value.
-    # @yieldparam value [Object] The attribute value to format.
-    # @yieldreturn [Object] The formatted attribute value.
-    # @return [Lumberjack::AttributeFormatter] Returns self for method chaining.
-    # @deprecated Use {#add_class} or {#add_attribute} instead.
-    def add(names_or_classes, formatter = nil, *args, &block)
-      Utils.deprecated("AttributeFormatter#add", "AttributeFormatter#add is deprecated and will be removed in version 2.1; use #add_class or #add_attribute instead.") do
-        Array(names_or_classes).each do |obj|
-          if obj.is_a?(Module)
-            add_class(obj, formatter, *args, &block)
-          else
-            add_attribute(obj, formatter, *args, &block)
-          end
-        end
-      end
-
-      self
-    end
-
     # Add formatters for specific object classes. The formatter will be applied to any attribute
     # value that is an instance of the registered class. This is particularly useful for formatting
     # all instances of specific data types consistently across your logs.
@@ -203,26 +172,6 @@ module Lumberjack
       self
     end
 
-    # Remove formatters for specific attribute names or classes. This reverts the specified
-    # attributes or classes to use the default formatter (if configured) or no formatting.
-    #
-    # @param names_or_classes [String, Module, Array<String, Module>] Attribute names or classes
-    #   to remove formatters for.
-    # @return [Lumberjack::AttributeFormatter] Returns self for method chaining.
-    # @deprecated Use {#remove_class} or {#remove_attribute} instead.
-    def remove(names_or_classes)
-      Utils.deprecated("AttributeFormatter#remove", "AttributeFormatter#remove is deprecated and will be removed in version 2.1; use #remove_class or #remove_attribute instead.") do
-        Array(names_or_classes).each do |key|
-          if key.is_a?(Module)
-            @class_formatter.remove(key)
-          else
-            @attribute_formatter.delete(key.to_s)
-          end
-        end
-      end
-      self
-    end
-
     # Remove formatters for specific object classes. This reverts the specified classes
     # to use the default formatter (if configured) or no formatting.
     #

data/lib/lumberjack/context.rb

@@ -46,7 +46,12 @@ module Lumberjack
       @default_severity = nil
 
       if parent_context
-        @attributes = parent_context.attributes.dup if parent_context.attributes
+        if parent_context.attributes
+          # Dup array values so appending tags in this context does not mutate the parent.
+          @attributes = parent_context.attributes.transform_values do |value|
+            value.is_a?(Array) ? value.dup : value
+          end
+        end
         self.level = parent_context.level
         self.progname = parent_context.progname
       end

data/lib/lumberjack/context_locals.rb

@@ -7,11 +7,10 @@ module Lumberjack
     #
     # @api private
     class Data
-      attr_accessor :context, :logging, :cleared
+      attr_accessor :context, :cleared
 
       def initialize(copy = nil)
         @context = copy&.context
-        @logging = copy&.logging
         @cleared = copy&.cleared
       end
     end
@@ -73,6 +72,15 @@ module Lumberjack
     def current_context_locals
       return nil unless defined?(@context_locals)
 
+      # Fast path that avoids the mutex when no context locals are set anywhere. This is
+      # safe without synchronization: Hash#empty? only reads the size and cannot raise or
+      # return garbage during a concurrent update, so the worst case is a stale value. A
+      # stale false falls through to the synchronized lookup, which is always correct. A
+      # stale true cannot hide an entry for the current scope because entries for the
+      # current scope are only ever written from code running in that same scope, so any
+      # such write is already visible here by program order.
+      return nil if @context_locals.empty?
+
       scope_id = context_locals_scope_id
       @context_locals_mutex.synchronize do
         @context_locals[scope_id]

data/lib/lumberjack/context_logger.rb

@@ -549,7 +549,8 @@ module Lumberjack
     # Dereference arguments to log calls so we can have methods with compatibility with ::Logger
     def call_add_entry(severity, message_or_progname_or_attributes, progname_or_attributes, &block) # :nodoc:
       severity = Severity.coerce(severity) unless severity.is_a?(Integer)
-      return true unless level.nil? || severity >= level
+      current_level = level
+      return true unless current_level.nil? || severity >= current_level
 
       message = nil
       progname = nil
@@ -592,10 +593,13 @@ module Lumberjack
       end
     end
 
-    def merge_all_attributes
+    # Merge the attributes from the global context, default context, current context,
+    # and the optional extra attributes into a single hash. The context locals can be
+    # passed in to avoid looking them up again if the caller has already done so.
+    def merge_all_attributes(locals = current_context_locals, extra_attributes = nil)
       attributes = nil
 
-      unless current_context_locals&.cleared
+      unless locals&.cleared
         global_context_attributes = Lumberjack.context_attributes
         if global_context_attributes && !global_context_attributes.empty?
           attributes ||= {}
@@ -609,12 +613,18 @@ module Lumberjack
         end
       end
 
-      context_attributes = current_context&.attributes
+      context_attributes = (locals&.context || default_context)&.attributes
       if context_attributes && !context_attributes.empty?
         attributes ||= {}
         attributes.merge!(context_attributes)
       end
 
+      if extra_attributes
+        # The merged hash is always freshly allocated, so it is safe to merge into it
+        # without exposing the mutation to any caller-visible hash.
+        attributes = attributes ? attributes.merge!(extra_attributes) : extra_attributes
+      end
+
       attributes
     end
   end

data/lib/lumberjack/device/buffer.rb

@@ -18,69 +18,93 @@ module Lumberjack
     class EntryBuffer
       attr_accessor :size
 
-      attr_reader :device, :last_flushed_at
+      attr_reader :device
 
       def initialize(device, size, before_flush)
         @device = device
         @size = size
         @before_flush = before_flush if before_flush.respond_to?(:call)
+        @before_flush_guard = :"lumberjack_device_buffer_before_flush_#{object_id}"
         @lock = Mutex.new
+        @flush_lock = Mutex.new
         @entries = []
         @last_flushed_at = Time.now
         @closed = false
       end
 
       def <<(entry)
-        return if closed?
+        flush_needed = false
 
         @lock.synchronize do
-          @entries << entry
+          unless @closed
+            @entries << entry
+            flush_needed = @entries.size >= @size
+          end
         end
 
-        flush if @entries.size >= @size
+        flush if flush_needed
       end
 
+      # Concurrent flushes are serialized by a separate lock so that batches cannot be
+      # interleaved or reordered when written to the wrapped device. The entry lock is
+      # only held while swapping out the buffered entries so that threads writing new
+      # entries are not blocked while the wrapped device performs I/O.
       def flush
-        entries = nil
+        call_before_flush
 
-        if closed?
-          @before_flush&.call
-          entries = @entries
-          @entries = []
-        else
+        @flush_lock.synchronize do
+          entries = nil
           @lock.synchronize do
-            @before_flush&.call
             entries = @entries
             @entries = []
+            @last_flushed_at = Time.now
           end
-        end
-
-        @last_flushed_at = Time.now
-
-        return if entries.nil?
 
-        entries.each do |entry|
-          @device.write(entry)
-        rescue => e
-          warn("Error writing log entry from buffer: #{e.inspect}")
+          entries.each do |entry|
+            @device.write(entry)
+          rescue => e
+            warn("Error writing log entry from buffer: #{e.inspect}")
+          end
         end
       end
 
       def close
-        @closed = true
+        @lock.synchronize { @closed = true }
         flush
       end
 
       def closed?
-        @closed
+        @lock.synchronize { @closed }
       end
 
       def reopen
-        @closed = false
+        @lock.synchronize { @closed = false }
       end
 
       def empty?
-        @entries.empty?
+        @lock.synchronize { @entries.empty? }
+      end
+
+      def last_flushed_at
+        @lock.synchronize { @last_flushed_at }
+      end
+
+      private
+
+      # The callback must be invoked outside the mutex so that a callback that logs
+      # through this buffer cannot deadlock on a recursive lock. The thread local
+      # guards against infinite recursion when a callback write triggers another flush.
+      # The guard is scoped per instance so a callback that logs through a different
+      # buffer does not suppress that buffer's own callback.
+      def call_before_flush
+        return if @before_flush.nil? || Thread.current[@before_flush_guard]
+
+        begin
+          Thread.current[@before_flush_guard] = true
+          @before_flush.call
+        ensure
+          Thread.current[@before_flush_guard] = nil
+        end
       end
     end
 
@@ -110,7 +134,9 @@ module Lumberjack
     # @option options [Integer] :buffer_size The number of entries to buffer before flushing. Default is 0 (no buffering).
     # @option options [Integer] :flush_seconds If specified, a background thread will flush the buffer every N seconds.
     # @option options [Proc] :before_flush A callback that will be called before each flush. The callback should
-    #  respond to +call+ and take no arguments.
+    #  respond to +call+ and take no arguments. The callback is invoked outside of the buffer lock, so it may
+    #  be called concurrently from multiple threads flushing at the same time; it must be thread safe if it
+    #  modifies any shared state.
     def initialize(wrapped_device, options = {})
       buffer_options = [:buffer_size, :flush_seconds, :before_flush]
       device_options = options.reject { |k, _| buffer_options.include?(k) }
@@ -132,7 +158,7 @@ module Lumberjack
     # Set the buffer size. The underlying device will only be written to when the buffer size
     # is exceeded.
     #
-    # @param [Integer] value The size of the buffer in bytes.
+    # @param [Integer] value The number of entries to buffer before flushing.
     # @return [void]
     def buffer_size=(value)
       @buffer.size = value
@@ -194,16 +220,5 @@ module Lumberjack
     def empty?
       @buffer.empty?
     end
-
-    private
-
-    def create_flusher_thread(flush_seconds, buffer) # :nodoc:
-      Thread.new do
-        until buffer.closed?
-          sleep(flush_seconds)
-          buffer.flush if Time.now - buffer.last_flushed_at >= flush_seconds
-        end
-      end
-    end
   end
 end

data/lib/lumberjack/device/multi.rb

@@ -80,7 +80,7 @@ module Lumberjack
     # @return [void]
     def reopen(logdev = nil)
       devices.each do |device|
-        device.reopen(logdev = nil)
+        device.reopen(logdev)
       end
     end
 
@@ -91,7 +91,7 @@ module Lumberjack
     # @return [String, nil] The datetime format string from the first device
     #   that has one configured, or nil if no devices have a format set
     def datetime_format
-      devices.detect(&:datetime_format).datetime_format
+      devices.detect(&:datetime_format)&.datetime_format
     end
 
     # Set the datetime format on all configured devices that support it.

data/lib/lumberjack/device/test.rb

@@ -86,6 +86,17 @@ module Lumberjack
     # @return [Hash] A copy of the options hash passed during initialization
     attr_reader :options
 
+    # @!attribute [rw] entry_formatter
+    #   Entry formatter used by +include?+, +match+, and +closest_match+ when
+    #   building matchers. Log entries are captured after the logger's formatter
+    #   has been applied, so setting this to the same formatter used by the logger
+    #   allows expectations to be written with unformatted values:
+    #
+    #     logger.device.entry_formatter = logger.formatter
+    #
+    #   @return [Lumberjack::EntryFormatter, nil] The entry formatter used for matching
+    attr_accessor :entry_formatter
+
     class << self
       # Format a log entry or expectation hash into a more human readable format. This is
       # intended for use in test failure messages to help diagnose why a match failed when
@@ -116,17 +127,39 @@ module Lumberjack
         message << "#{indent_str}severity: #{Lumberjack::Severity.level_to_label(severity)}" if severity
         message << "#{indent_str}message: #{expectation["message"]}" if expectation.include?("message")
         message << "#{indent_str}progname: #{expectation["progname"]}" if expectation.include?("progname")
-        if expectation["attributes"].is_a?(Hash) && !expectation["attributes"].empty?
-          attributes = Lumberjack::Utils.flatten_attributes(expectation["attributes"])
-          label = "attributes:"
-          prefix = "#{indent_str}#{label}"
-          attributes.sort_by(&:first).each do |name, value|
-            message << "#{prefix} #{name}: #{value.inspect}"
-            prefix = "#{indent_str}#{" " * label.length}"
+        expected_attributes = expectation["attributes"]
+        if expected_attributes.is_a?(Hash)
+          unless expected_attributes.empty?
+            attributes = Lumberjack::Utils.flatten_attributes(expected_attributes)
+            label = "attributes:"
+            prefix = "#{indent_str}#{label}"
+            attributes.sort_by(&:first).each do |name, value|
+              message << "#{prefix} #{name}: #{formatted_value(value)}"
+              prefix = "#{indent_str}#{" " * label.length}"
+            end
           end
+        elsif expected_attributes
+          # Matchers like RSpec's hash_including are matched against the attributes hash as a whole.
+          message << "#{indent_str}attributes: #{formatted_value(expected_attributes)}"
         end
         message.join(Lumberjack::LINE_SEPARATOR)
       end
+
+      private
+
+      # Format a value for display in an expectation. Matcher objects (i.e. RSpec matchers)
+      # that implement a +description+ method are displayed using that description since
+      # inspecting them is not very informative.
+      #
+      # @param value [Object] The value to format.
+      # @return [String] The formatted value.
+      def formatted_value(value)
+        if value.respond_to?(:description) && !value.is_a?(Module)
+          value.description.to_s
+        else
+          value.inspect
+        end
+      end
     end
 
     # Initialize a new Test device with configurable buffer management.
@@ -137,9 +170,12 @@ module Lumberjack
     # @option options [Integer] :max_entries (1000) The maximum number of entries
     #   to retain in the buffer. When this limit is exceeded, the oldest entries
     #   are automatically removed to maintain the size limit.
+    # @option options [Lumberjack::EntryFormatter] :entry_formatter Entry formatter
+    #   used when matching entries. See {#entry_formatter}.
     def initialize(options = {})
       @buffer = []
       @max_entries = options[:max_entries] || 1000
+      @entry_formatter = options[:entry_formatter]
       @lock = Mutex.new
       @options = options.dup
     end
@@ -180,7 +216,7 @@ module Lumberjack
     # @return [Lumberjack::LogEntry, nil] The most recent log entry, or nil
     #   if no entries have been captured yet
     def last_entry
-      @buffer.last
+      @lock.synchronize { @buffer.last }
     end
 
     # Clear all captured log entries from the buffer. This method is useful
@@ -189,7 +225,7 @@ module Lumberjack
     #
     # @return [void]
     def clear
-      @buffer = []
+      @lock.synchronize { @buffer = [] }
       nil
     end
 
@@ -230,6 +266,9 @@ module Lumberjack
     #   { user: { id: value } }). Values can be exact matches or test framework matchers
     # @option options [String, Regexp, Object] :progname Pattern to match against
     #   the program name that generated the log entry
+    # @option options [Lumberjack::EntryFormatter, Lumberjack::Logger] :formatter
+    #   Formatter used to format filter values when a raw comparison fails. Defaults
+    #   to the device {#entry_formatter}.
     #
     # @return [Boolean] True if any captured entries match all specified criteria,
     #   false otherwise
@@ -281,6 +320,9 @@ module Lumberjack
     #   log entry attributes. Supports nested matching using dot notation
     # @param progname [String, Regexp, Object, nil] Pattern to match against
     #   the program name that generated the log entry
+    # @param formatter [Lumberjack::EntryFormatter, Lumberjack::Logger, nil] Formatter
+    #   used to format filter values when a raw comparison fails. Defaults to the
+    #   device {#entry_formatter}.
     #
     # @return [Lumberjack::LogEntry, nil] The first matching log entry, or nil
     #   if no entries match the specified criteria
@@ -305,8 +347,14 @@ module Lumberjack
     #     attributes: {"request.endpoint" => "/users", "response.status" => 200}
     #   )
     #   expect(api_entry.attributes["request.endpoint"]).to eq("/users")
-    def match(message: nil, severity: nil, attributes: nil, progname: nil)
-      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
+    def match(message: nil, severity: nil, attributes: nil, progname: nil, formatter: nil)
+      matcher = LogEntryMatcher.new(
+        message: message,
+        severity: severity,
+        attributes: attributes,
+        progname: progname,
+        formatter: formatter || entry_formatter
+      )
       entries.detect { |entry| matcher.match?(entry) }
     end
 
@@ -327,10 +375,19 @@ module Lumberjack
     #   log entry attributes. Supports nested matching using dot notation
     # @param progname [String, Regexp, Object, nil] Pattern to match against
     #   the program name that generated the log entry
+    # @param formatter [Lumberjack::EntryFormatter, Lumberjack::Logger, nil] Formatter
+    #   used to format filter values when a raw comparison fails. Defaults to the
+    #   device {#entry_formatter}.
     # @return [Lumberjack::LogEntry, nil] The closest matching log entry, or nil
     #   if no entries meet the minimum score threshold
-    def closest_match(message: nil, severity: nil, attributes: nil, progname: nil)
-      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
+    def closest_match(message: nil, severity: nil, attributes: nil, progname: nil, formatter: nil)
+      matcher = LogEntryMatcher.new(
+        message: message,
+        severity: severity,
+        attributes: attributes,
+        progname: progname,
+        formatter: formatter || entry_formatter
+      )
       matcher.closest(entries)
     end
   end