lumberjack 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b76516c0e871b68e2834d0517dd219eefd0985fd55894c48e8e8c4fa9e71be8
-  data.tar.gz: 2516f75995e1ca98a7d0daabf5ea71b1a3a2e4593966a955bac9bc66dea5827e
+  metadata.gz: 140e49b15017aa81ca85a2e42a9de896b09938b5f9dd437a8f2917f821831d3d
+  data.tar.gz: fe95870efcfb98d6831833e4125a74817f93c718969febcdba81e0b3b6e149a1
 SHA512:
-  metadata.gz: a6df7a99b4b8bba7a694cdcb45053185b7f2d40bb18af18af354e0188eba00b2f04156536e0844c0ddc74e38e3661821e60b357d4eef8928a3de6bd2bf0af1da
-  data.tar.gz: ad698517a3a54969c582d6cb839c218894a89b301c137bf2bdc08889777d50343ca4ccaf26d4a40ae96bfd3601790481267729e15eadc4d8f2cc7abbc687fd06
+  metadata.gz: ba5adc8a3633df76fb78960ed06b266336c829d72ac48df5092dc5eb6fea4061ba4bb738c54aafbc2cedb23b6e638871992363120f0c323a916976e757d4bf0b
+  data.tar.gz: e23288af3a076eead23bad85f885f4928d5aae4592cef341e6fd4f27ee9e65c6c8464e20c09b6d7a1522512ca70057027a9f40c0201bfa8b4400a6af139b4c3a

data/ARCHITECTURE.md

@@ -402,191 +402,3 @@ sequenceDiagram
     %% Context Cleanup
     Note over Logger,Context: Context automatically cleaned up when block exits
 ```
-
-## Key Design Patterns
-
-### 1. **Layered Architecture**
-- Clear separation between logging interface, processing, and output
-- Each layer has well-defined responsibilities and interfaces
-- Enables independent testing and component replacement
-
-### 2. **Strategy Pattern**
-- Devices implement pluggable output strategies
-- Formatters provide pluggable formatting strategies
-- Templates enable customizable output formatting
-
-### 3. **Composite Pattern**
-- MultiDevice composes multiple output devices
-- AttributeFormatter composes class and attribute formatters
-- Context inherits from parent contexts
-
-### 4. **Chain of Responsibility**
-- Formatting pipeline processes entries through multiple stages
-- Context resolution follows inheritance chain
-- Attribute merging follows precedence rules
-
-### 5. **Facade Pattern**
-- Logger provides simplified interface to complex subsystem
-- ContextLogger abstracts context management complexity
-- Utils module provides common functionality access
-
-## Performance Characteristics
-
-### **Memory Management**
-- Immutable LogEntry objects prevent accidental modification
-- Context inheritance minimizes memory duplication
-- Attribute compaction removes empty values automatically
-
-### **Thread Safety**
-- Fiber-local storage for context isolation (contexts are fiber-scoped)
-- Mutex-protected device operations where needed
-- Immutable data structures prevent race conditions
-- FiberLocals module manages per-fiber state
-
-### **Lazy Evaluation**
-- Block-based message generation for expensive operations
-- Conditional formatting based on log levels
-- On-demand context resolution
-
-### **Efficient Routing**
-- Level checking before entry creation
-- Direct device writing without intermediate buffers
-- Optimized formatter selection for common types
-
-## Extension Points
-
-The framework provides several extension points for customization:
-
-### **Custom Devices**
-```ruby
-class DatabaseDevice < Lumberjack::Device
-  def initialize(connection)
-    @connection = connection
-  end
-
-  def write(entry)
-    @connection.execute(
-      "INSERT INTO logs (timestamp, level, message, attributes) VALUES (?, ?, ?, ?)",
-      entry.time,
-      entry.severity_label,
-      entry.message,
-      JSON.generate(entry.attributes || {})
-    )
-  end
-
-  def flush
-    # Database connections typically auto-flush
-  end
-
-  def close
-    @connection.close
-  end
-end
-```
-
-### **Custom Formatters**
-```ruby
-class JsonFormatter
-  def call(obj)
-    JSON.generate(obj)
-  end
-end
-
-logger.formatter.format_class(Hash, JsonFormatter.new)
-```
-
-### **Custom Templates**
-```ruby
-json_template = ->(entry) do
-  JSON.generate(
-    timestamp: entry.time.iso8601,
-    level: entry.severity_label,
-    message: entry.message,
-    attributes: entry.attributes
-  )
-end
-
-device = Lumberjack::Device::Writer.new(STDOUT, template: json_template)
-```
-
-## Integration Patterns
-
-### **Web Application Integration**
-```ruby
-# Rack middleware for request context
-use Lumberjack::Rack::Context do |env|
-  {
-    request_id: env["HTTP_X_REQUEST_ID"],
-    user_id: env["warden"]&.user&.id
-  }
-end
-```
-
-### **Component Isolation**
-```ruby
-# Component-specific loggers
-class UserService
-  def initialize(logger)
-    @logger = logger.fork(progname: "UserService")
-    @logger.tag!(component: "user_service", version: "1.2.3")
-  end
-end
-```
-
-### **Testing Integration**
-```ruby
-# Test environment setup
-logger = Lumberjack::Logger.new(:test)
-logger.info("Test message", user_id: 123)
-expect(logger.device).to include(
-  severity: :info,
-  message: "Test message",
-  attributes: {user_id: 123}
-)
-```
-
-## Configuration Best Practices
-
-### **Production Configuration**
-```ruby
-logger = Lumberjack::Logger.new("/var/log/app.log", shift_age: 10, shift_size: "50M", level: :info) do |config|
-  # Structured attribute formatting
-  config.formatter.format_attribute_name("password") { |value| "[REDACTED]" }
-  config.formatter.format_class(Time, :iso8601)
-end
-```
-
-### **Development Configuration**
-```ruby
-logger = Lumberjack::Logger.new(STDOUT, level: :debug, template: "[{{time}} {{severity}}] {{message}} {{attributes}}") do |config|
-  # Pretty-print complex objects
-  config.formatter.format_class(Hash, :pretty_print)
-  config.formatter.format_class(Array, :pretty_print)
-end
-```
-
-### **Multi-Environment Setup**
-```ruby
-file_device = Lumberjack::Device::LogFile.new("/var/log/app.log")
-console_device = Lumberjack::Device::Writer.new(STDOUT)
-error_device = Lumberjack::Device::Writer.new(STDERR)
-
-multi_device = Lumberjack::Device::Multi.new(
-  file_device,
-  Rails.env.development? ? console_device : nil
-).compact
-
-logger = Lumberjack::Logger.new(multi_device)
-```
-
-This architecture enables Lumberjack to provide a powerful, flexible logging solution that scales from simple applications to complex, multi-component systems while maintaining excellent performance and developer experience.
-
-## Version Notes
-
-This documentation reflects the current Lumberjack architecture. Note that:
-
-- Template syntax has evolved from `:placeholder` to `{{placeholder}}` format (old syntax is deprecated)
-- Some method names have changed over versions (e.g., `tag_formatter` is now `attribute_formatter`)
-- Configuration options have been streamlined to use keyword arguments
-- Fiber-local storage is used for context isolation rather than thread-local storage
-- The `EntryFormatter` class provides the primary formatting interface, with `format()` being the main method and `call()` for Logger compatibility

data/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.0.3
+
+### Added
+
+- Added `isolation_level` to loggers. By default this is set to `:fiber` which isolates logger contexts to the current fiber. That is each fiber will get its own context stack and starting a new fiber will start with a clean context. Setting `isolation_level` to `:thread` will isolate contexts to the current thread instead. This is useful if your application does not share fibers between threads and you want to maintain context across fibers in the same thread.
+
 ## 2.0.2
 
 ### Changed

data/README.md

@@ -22,6 +22,7 @@ The philosophy behind the library is to promote use of structured logging with t
      - [Context Blocks](#context-blocks)
      - [Nested Context Blocks](#nested-context-blocks)
      - [Forking Loggers](#forking-loggers)
+     - [Isolation Level](#isolation-level)
    - [Structured Logging With Attributes](#structured-logging-with-attributes)
      - [Basic Attribute Logging](#basic-attribute-logging)
      - [Adding attributes to the logger](#adding-attributes-to-the-logger)
@@ -113,6 +114,18 @@ main_logger.info("Main logger info")       # Includes only version attribute
 main_logger.debug("Main logger debug info") # Not logged since level is :info
 ```
 
+#### Isolation Level
+
+By default each fiber will have its own logging context. This is useful in asynchronous applications where multiple fibers may be running concurrently. You can change the isolation level to `:thread` if you want each thread to have its own logging context instead.
+
+```ruby
+Lumberjack.isolation_level = :thread # Set isolation level globally
+
+logger = Lumberjack::Logger.new(STDOUT, isolation_level: :thread) # Set isolation level per logger
+```
+
+Fiber isolation is the safest behavior since it completely isolates local contexts. However, in applications where threads are the main unit of work and fibers are never shared across threads, thread isolation may be more appropriate. Otherwise you can end up with the logger losing the context block when switching fibers within the same thread.
+
 ### Structured Logging With Attributes
 
 Lumberjack extends standard logging with **attributes** (structured key-value pairs) that add context and metadata to your log entries. This enables powerful filtering, searching, and analytics capabilities.

data/VERSION

@@ -1 +1 @@
-2.0.2
+2.0.3

data/lib/lumberjack/context_locals.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # Provides isolated fiber or thread local storage for thread-safe data access.
+  module ContextLocals
+    # Lightweight structure to hold context-local data.
+    #
+    # @api private
+    class Data
+      attr_accessor :context, :logging, :cleared
+
+      def initialize(copy = nil)
+        @context = copy&.context
+        @logging = copy&.logging
+        @cleared = copy&.cleared
+      end
+    end
+
+    # Set the isolation level for context locals.
+    #
+    # @param value [Symbol] The isolation level, either :fiber or :thread.
+    # @return [void]
+    def isolation_level=(value)
+      value = value&.to_sym
+      value = :fiber unless [:fiber, :thread].include?(value)
+      @isolation_level = value
+    end
+
+    # Get the isolation level for context locals.
+    #
+    # @return [Symbol] The isolation level, either :fiber or :thread.
+    def isolation_level
+      @isolation_level ||= :fiber
+    end
+
+    private
+
+    def new_context_locals(&block)
+      init_context_locals! unless defined?(@context_locals)
+
+      if isolation_level == :fiber
+        set_context_locals(&block)
+      else
+        set_context_locals_thread_id do
+          set_context_locals(&block)
+        end
+      end
+    end
+
+    def set_context_locals(&block)
+      scope_id = context_locals_scope_id
+      current = @context_locals[scope_id] if scope_id
+      data = Data.new(current)
+
+      begin
+        @context_locals_mutex.synchronize do
+          @context_locals[scope_id] = data
+        end
+        yield data
+      ensure
+        @context_locals_mutex.synchronize do
+          if current.nil?
+            @context_locals.delete(scope_id)
+          else
+            @context_locals[scope_id] = current
+          end
+        end
+      end
+    end
+
+    def current_context_locals
+      return nil unless defined?(@context_locals)
+
+      @context_locals[context_locals_scope_id]
+    end
+
+    # Initialize the context locals storage and mutex.
+    def init_context_locals!
+      @context_locals ||= {}
+      @context_locals_mutex ||= Mutex.new
+      @isolation_level ||= Lumberjack.isolation_level
+    end
+
+    def context_locals_scope_id
+      if isolation_level == :fiber
+        Fiber.current.object_id
+      else
+        Thread.current.thread_variable_get(:lumberjack_context_locals_thread_id)
+      end
+    end
+
+    # Create a consistent thread ID for context locals. We can't use Thread.current.object_id
+    # directly because it may change during execution (e.g., in JRuby when threads are
+    # migrated between native threads). Instead we store a unique ID in a thread variable.
+    def set_context_locals_thread_id
+      thread_id = Thread.current.thread_variable_get(:lumberjack_context_locals_thread_id)
+      return yield if thread_id
+
+      thread_id = Object.new.object_id
+      begin
+        Thread.current.thread_variable_set(:lumberjack_context_locals_thread_id, thread_id)
+        yield
+      ensure
+        Thread.current.thread_variable_set(:lumberjack_context_locals_thread_id, nil)
+      end
+    end
+  end
+end

data/lib/lumberjack/context_logger.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "fiber_locals"
+require_relative "context_locals"
 require_relative "io_compatibility"
 require_relative "severity"
 
@@ -26,7 +26,7 @@ module Lumberjack
 
     class << self
       def included(base)
-        base.include(FiberLocals) unless base.include?(FiberLocals)
+        base.include(ContextLocals) unless base.include?(ContextLocals)
         base.include(IOCompatibility) unless base.include?(IOCompatibility)
       end
     end
@@ -408,7 +408,7 @@ module Lumberjack
 
       new_context = Context.new(current_context)
       new_context.parent = local_context
-      fiber_locals do |locals|
+      new_context_locals do |locals|
         locals.context = new_context
         block.call(new_context)
       end
@@ -448,6 +448,7 @@ module Lumberjack
       logger.level = level if level
       logger.progname = progname if progname
       logger.tag!(attributes) if attributes
+      logger.isolation_level = isolation_level
       logger
     end
 
@@ -494,7 +495,7 @@ module Lumberjack
     #
     # @return [void]
     def clear_attributes(&block)
-      fiber_locals do |locals|
+      new_context_locals do |locals|
         locals.cleared = true
         context do |ctx|
           ctx.clear_attributes
@@ -529,7 +530,7 @@ module Lumberjack
     end
 
     def local_context
-      fiber_local&.context
+      current_context_locals&.context
     end
 
     def default_context
@@ -594,7 +595,7 @@ module Lumberjack
     def merge_all_attributes
       attributes = nil
 
-      unless fiber_local&.cleared
+      unless current_context_locals&.cleared
         global_context_attributes = Lumberjack.context_attributes
         if global_context_attributes && !global_context_attributes.empty?
           attributes ||= {}

data/lib/lumberjack/forked_logger.rb

@@ -65,7 +65,8 @@ module Lumberjack
     # @param logger [Lumberjack::ContextLogger, #add_entry] The parent logger to forward entries to.
     #   Must respond to either +add_entry+ (for Lumberjack loggers) or standard Logger methods.
     def initialize(logger)
-      init_fiber_locals!
+      init_context_locals!
+      self.isolation_level = logger.isolation_level if logger.respond_to?(:isolation_level)
       @parent_logger = logger
       @context = Context.new
       @context.level ||= logger.level

data/lib/lumberjack/logger.rb

@@ -94,7 +94,7 @@ module Lumberjack
     def initialize(logdev, shift_age = 0, shift_size = 1048576,
       level: DEBUG, progname: nil, formatter: nil, datetime_format: nil,
       binmode: false, shift_period_suffix: "%Y%m%d", **kwargs)
-      init_fiber_locals!
+      init_context_locals!
 
       if shift_age.is_a?(Hash)
         Lumberjack::Utils.deprecated("Logger.new(options)", "Passing a Hash as the second argument to Logger.new is deprecated and will be removed in version 2.1; use keyword arguments instead.")
@@ -106,6 +106,8 @@ module Lumberjack
         kwargs = options.merge(kwargs)
       end
 
+      self.isolation_level = kwargs.delete(:isolation_level) || Lumberjack.isolation_level
+
       # Include standard args that affect devices with the optional kwargs which may
       # contain device specific options.
       device_options = kwargs.merge(shift_age: shift_age, shift_size: size_with_units(shift_size), binmode: binmode, shift_period_suffix: shift_period_suffix)
@@ -398,14 +400,14 @@ module Lumberjack
       return false unless device
 
       # Prevent infinite recursion if logging is attempted from within a logging call.
-      if fiber_local&.logging
+      if current_context_locals&.logging
         log_to_stderr(severity, message)
         return false
       end
 
       severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
 
-      fiber_locals do |locals|
+      new_context_locals do |locals|
         locals.logging = true # protection from infinite loops
 
         time = Time.now

data/lib/lumberjack.rb

@@ -42,7 +42,7 @@ module Lumberjack
   require_relative "lumberjack/attributes_helper"
   require_relative "lumberjack/context"
   require_relative "lumberjack/context_logger"
-  require_relative "lumberjack/fiber_locals"
+  require_relative "lumberjack/context_locals"
   require_relative "lumberjack/io_compatibility"
   require_relative "lumberjack/log_entry"
   require_relative "lumberjack/log_entry_matcher"
@@ -68,6 +68,9 @@ module Lumberjack
   @global_contexts_mutex = Mutex.new
   @deprecation_mode = nil
   @raise_logger_errors = false
+  @isolation_level = :fiber
+
+  extend ContextLocals
 
   class << self
     # Contexts can be used to store attributes that will be attached to all log entries in the block.
@@ -104,21 +107,15 @@ module Lumberjack
     # @return [Object] The result of the block.
     # @api private
     def use_context(context, &block)
-      fiber_id = Fiber.current.object_id
-      ctx = @global_contexts[fiber_id]
-      begin
-        @global_contexts_mutex.synchronize do
-          @global_contexts[fiber_id] = (context || Context.new)
-        end
+      unless block_given?
+        raise ArgumentError, "A block must be provided to the context method"
+      end
+
+      new_context = Context.new(context)
+      new_context.parent = current_context
+      new_context_locals do |locals|
+        locals.context = new_context
         yield
-      ensure
-        @global_contexts_mutex.synchronize do
-          if ctx.nil?
-            @global_contexts.delete(fiber_id)
-          else
-            @global_contexts[fiber_id] = ctx
-          end
-        end
       end
     end
 
@@ -126,7 +123,7 @@ module Lumberjack
     #
     # @return [Boolean]
     def in_context?
-      !!@global_contexts[Fiber.current.object_id]
+      !current_context.nil?
     end
 
     def context?
@@ -142,6 +139,19 @@ module Lumberjack
       current_context&.attributes
     end
 
+    # Set the isolation level for global contexts to be either per fiber or per thread. Default is :fiber.
+    #
+    # @param value [Symbol] The isolation level, either :fiber or :thread.
+    # @return [void]
+    def isolation_level=(value)
+      value = value&.to_sym
+      value = :fiber unless [:fiber, :thread].include?(value)
+      @isolation_level = value
+    end
+
+    # @return [Symbol] The current isolation level.
+    attr_reader :isolation_level
+
     # Alias for context_attributes to provide API compatibility with version 1.x.
     # This method will eventually be removed.
     #
@@ -220,7 +230,7 @@ module Lumberjack
     private
 
     def current_context
-      @global_contexts[Fiber.current.object_id]
+      current_context_locals&.context
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Brian Durand
@@ -53,6 +53,7 @@ files:
 - lib/lumberjack/attribute_formatter.rb
 - lib/lumberjack/attributes_helper.rb
 - lib/lumberjack/context.rb
+- lib/lumberjack/context_locals.rb
 - lib/lumberjack/context_logger.rb
 - lib/lumberjack/device.rb
 - lib/lumberjack/device/buffer.rb
@@ -66,7 +67,6 @@ files:
 - lib/lumberjack/device/writer.rb
 - lib/lumberjack/device_registry.rb
 - lib/lumberjack/entry_formatter.rb
-- lib/lumberjack/fiber_locals.rb
 - lib/lumberjack/forked_logger.rb
 - lib/lumberjack/formatter.rb
 - lib/lumberjack/formatter/date_time_formatter.rb

data/lib/lumberjack/fiber_locals.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Lumberjack
-  # Provides isolated fiber-local storage for thread-safe data access.
-  module FiberLocals
-    # Lightweight structure to hold fiber-local data.
-    #
-    # @api private
-    class Data
-      attr_accessor :context, :logging, :cleared
-
-      def initialize(copy = nil)
-        @context = copy&.context
-        @logging = copy&.logging
-        @cleared = copy&.cleared
-      end
-    end
-
-    private
-
-    def fiber_locals(&block)
-      init_fiber_locals! unless defined?(@fiber_locals)
-
-      fiber_id = Fiber.current.object_id
-      current = @fiber_locals[fiber_id]
-      data = Data.new(current)
-      begin
-        @fiber_locals_mutex.synchronize do
-          @fiber_locals[fiber_id] = data
-        end
-        yield data
-      ensure
-        @fiber_locals_mutex.synchronize do
-          if current.nil?
-            @fiber_locals.delete(fiber_id)
-          else
-            @fiber_locals[fiber_id] = current
-          end
-        end
-      end
-    end
-
-    def fiber_local
-      return nil unless defined?(@fiber_locals)
-
-      @fiber_locals[Fiber.current.object_id]
-    end
-
-    # Initialize the fiber locals storage and mutex.
-    def init_fiber_locals!
-      @fiber_locals ||= {}
-      @fiber_locals_mutex ||= Mutex.new
-    end
-  end
-end