contextual_logger 1.2.0.pre.1 → 1.3.0.dg.pre.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5ee8cad9d62ca2d8aeec81f2626b56b4aa6b1db2c6b626518a4708d590ddb4c
-  data.tar.gz: 71be08f271be68de04f942abfa301a2a5ec54be54d0399bb01db8bcf52a07037
+  metadata.gz: 96fa2fd042325883674d751a6b2443c23e9e6b195f9f15ade2826832c6557735
+  data.tar.gz: 180923158cdaac1c7cd63755ca93e4cda42aaf48bab442b21981264a255a5765
 SHA512:
-  metadata.gz: 2b455d41a46223ea9c6e2583a7d03d81940743215c4eb1dd5977d6ffc8f8ffcb618ce27a3b975fed211987b592e0cfdbc1e691ceef155641764c5d8938da0679
-  data.tar.gz: 6600b357b1dc7b25ee8e746f17280a7e74ac184b38a03340f48e835659259135321a0c0ff0d7c387a7b06b9804b82ad63f8b76a911790a6fb5c2f99a61c0cfdc
+  metadata.gz: 66081a0a05dded370cf77b2e60b2c20884e8993a362bf6be4674b3c4b0c95d4811c208b8b6ab64ea99495fc7ca05b16ba9ef779cb39f4169620a06eac0c12fce
+  data.tar.gz: 04d1997d713eec2231a08e2085728db8ef438268835b4ac6e3eb866ec01c7d5df0447677de127c286236aa0485d4e233b36214234aa661cd0c30c6fe52eaaef8

data/lib/contextual_logger/context.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  module Context
+    EMPTY_CONTEXT = {}.freeze
+
+    def thread_context_key_for_logger_instance
+      # We include the object_id here to make these thread/fiber locals unique per logger instance.
+      @thread_context_key_for_logger_instance ||= "ContextualLogger::Context.context_for_#{object_id}".to_sym
+    end
+
+    def current_context_override
+      Thread.current[thread_context_key_for_logger_instance]
+    end
+
+    def current_context_override=(context_override)
+      ContextualLogger.global_context_lock_message ||= "ContextualLogger::Context.current_context_override set for #{self.class.name} #{object_id}: #{context_override.inspect}"
+      Thread.current[thread_context_key_for_logger_instance] = context_override.freeze
+    end
+  end
+end

data/lib/contextual_logger/context_handler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  class ContextHandler
+    def initialize(instance, previous_context_override)
+      @instance = instance
+      @previous_context_override = previous_context_override
+    end
+
+    def reset!
+      @instance.current_context_override = @previous_context_override
+    end
+  end
+end

data/lib/contextual_logger/global_context_lock_message.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  class << self
+    attr_accessor :global_context_lock_message # nil or a string indicating what locked the global context
+  end
+
+  class GlobalContextIsLocked < StandardError
+  end
+end

data/lib/contextual_logger/logger_with_context.rb

@@ -6,6 +6,13 @@ module ContextualLogger
   # A logger that deep_merges additional context and then delegates to the given logger.
   # Keeps it own log level (called override_level) that may be set independently of the logger it delegates to.
   # If override_level is non-nil, it takes precedence; if it is nil (the default), then it delegates to the logger.
+  #
+  # Context Precedence:
+  # 1. inline **context passed to the logger method
+  # 2. `with_context` overrides on this LoggerWithContext object
+  # 3. context passed to this LoggerWithContext constructor
+  # 4. `with_context` overrides on the logger passed to this constructor
+  # 5. `global_context` set on the logger passed to this constructor
   class LoggerWithContext
     include LoggerMixin
 
@@ -16,7 +23,13 @@ module ContextualLogger
       @logger = logger
       self.level = level
       @context = normalize_context(context)
-      @merged_context_cache = {}  # so we don't have to merge every time
+    end
+
+    # TODO: It's a (small) bug that the global_context is memoized at this point. There's a chance that the @logger.current_context
+    # changes after this because of an enclosing @logger.with_context block. If that happens, we'll miss that extra context.
+    # The tradeoff is that we don't want to keep calling deep_merge.
+    def global_context
+      @global_context ||= @logger.current_context.deep_merge(@context) # this will include any with_context overrides on the `logger`
     end
 
     def level
@@ -29,10 +42,10 @@ module ContextualLogger
 
     def write_entry_to_log(severity, timestamp, progname, message, context:)
       merged_context =
-        if @merged_context_cache.size >= 1000 # keep this cache memory use finite
-          @merged_context_cache[context] || @context.deep_merge(context)
+        if context.any?
+          current_context.deep_merge(context)
         else
-          @merged_context_cache[context] ||= @context.deep_merge(context)
+          current_context
         end
 
       @logger.write_entry_to_log(severity, timestamp, progname, message, context: merged_context)

data/lib/contextual_logger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextualLogger
-  VERSION = '1.2.0.pre.1'
+  VERSION = '1.3.0.dg.pre.0'
 end

data/lib/contextual_logger.rb

@@ -4,7 +4,9 @@ require 'active_support'
 require 'active_support/core_ext/module/delegation'
 require 'json'
 require_relative './contextual_logger/redactor'
-require_relative './contextual_logger/context/handler'
+require_relative './contextual_logger/context'
+require_relative './contextual_logger/context_handler'
+require_relative './contextual_logger/global_context_lock_message'
 
 module ContextualLogger
   LOG_LEVEL_NAMES_TO_SEVERITY =
@@ -17,6 +19,9 @@ module ContextualLogger
     unknown: Logger::Severity::UNKNOWN
   }.freeze
 
+  class LambdaAlreadyDefinedError < StandardError
+  end
+
   class << self
     def new(logger)
       logger.extend(LoggerMixin)
@@ -42,16 +47,57 @@ module ContextualLogger
     end
   end
 
+  # Context Precedence when this is mixed into a logger:
+  # 1. inline **context passed to the logger method
+  # 2. `with_context` overrides on the logger object
+  # 3. `global_context` set on the logger passed to this constructor
   module LoggerMixin
+    include Context
+
     delegate :register_secret, :register_secret_regex, to: :redactor
 
+    def global_context
+      @global_context ||= Context::EMPTY_CONTEXT
+    end
+
+    def add_global_context_lambda(field, lambda)
+      if field.blank?
+        raise ArgumentError, "The field cannot be empty"
+      end
+
+      unless lambda.respond_to?(:call)
+        raise ArgumentError, "A lambda must respond to the :call method"
+      end
+
+      if global_context_lambdas[field]
+        raise ::ContextualLogger::LambdaAlreadyDefinedError, "A lambda for `#{field}` is already defined"
+      end
+
+      @global_context_lambdas[field] = lambda
+    end
+
+    def global_context_lambdas
+      @global_context_lambdas ||= {}
+    end
+
     def global_context=(context)
-      Context::Handler.new(context).set!
+      if (global_context_lock_message = ::ContextualLogger.global_context_lock_message)
+        raise ::ContextualLogger::GlobalContextIsLocked, global_context_lock_message
+      end
+      @global_context = context.freeze
+    end
+
+    def current_context
+      current_context_override || global_context
     end
 
-    def with_context(context)
-      context_handler = Context::Handler.new(current_context_for_thread.deep_merge(context))
-      context_handler.set!
+    # TODO: Deprecate current_context_for_thread in v2.0.
+    alias current_context_for_thread current_context
+
+    def with_context(stacked_context)
+      context_handler = ContextHandler.new(self, current_context_override)
+      self.current_context_override = deep_merge_with_current_context(stacked_context)
+
       if block_given?
         begin
           yield
@@ -59,15 +105,11 @@ module ContextualLogger
           context_handler.reset!
         end
       else
-        # If no block given, the context handler is returned to the caller so they can handle reset! themselves.
+        # If no block given, return context handler to the caller so they can call reset! themselves.
         context_handler
       end
     end
 
-    def current_context_for_thread
-      Context::Handler.current_context
-    end
-
     # In the methods generated below, we assume that presence of context means new code that is
     # aware of ContextualLogger...and that that code never uses progname.
     # This is important because we only get 3 args total (not including &block) passed to `add`,
@@ -102,7 +144,7 @@ module ContextualLogger
 
     # Note that this interface needs to stay compatible with the underlying ::Logger#add interface,
     # which is: def add(severity, message = nil, progname = nil)
-    def add(arg_severity, arg1 = nil, arg2 = nil, **context)   # Ruby will prefer to match hashes up to last ** argument
+    def add(arg_severity, arg1 = nil, arg2 = nil, **context)   # Ruby will prefer to match hashes to last argument because of **
       severity = arg_severity || UNKNOWN
       if log_level_enabled?(severity)
         if arg1.nil?
@@ -117,7 +159,8 @@ module ContextualLogger
           message = arg1
           progname = arg2 || @progname
         end
-        write_entry_to_log(severity, Time.now, progname, message, context: current_context_for_thread.deep_merge(context))
+        full_context = evaluate_global_context_lambdas(deep_merge_with_current_context(context))
+        write_entry_to_log(severity, Time.now, progname, message, context: full_context)
       end
 
       true
@@ -141,7 +184,7 @@ module ContextualLogger
       normalized_message = ContextualLogger.normalize_message(message)
       normalized_progname = ContextualLogger.normalize_message(progname) unless progname.nil?
       if @formatter
-        @formatter.call(severity, timestamp, normalized_progname, { message: normalized_message }.merge!(context))
+        @formatter.call(severity, timestamp, normalized_progname, { message: normalized_message, **context })
       else
         "#{basic_json_log_entry(severity, timestamp, normalized_progname, normalized_message, context: context)}\n"
       end
@@ -151,12 +194,28 @@ module ContextualLogger
       message_hash = {
         message: normalized_progname ? "#{normalized_progname}: #{normalized_message}" : normalized_message,
         severity:  severity,
-        timestamp: timestamp
+        timestamp: timestamp,
+        **context
       }
       message_hash[:progname] = normalized_progname if normalized_progname
 
-      # merge! is faster and OK here since message_hash is still local only to this method
-      message_hash.merge!(context).to_json
+      message_hash.to_json
+    end
+
+    def deep_merge_with_current_context(stacked_context)
+      if stacked_context.any?
+        current_context.deep_merge(stacked_context)
+      else
+        current_context
+      end
+    end
+
+    def evaluate_global_context_lambdas(context)
+      if global_context_lambdas.empty?
+        context
+      else
+        global_context_lambdas.transform_values { |lambda| lambda.call }.merge(context)
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contextual_logger
 version: !ruby/object:Gem::Version
-  version: 1.2.0.pre.1
+  version: 1.3.0.dg.pre.0
 platform: ruby
 authors:
 - James Ebentier
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-09 00:00:00.000000000 Z
+date: 2023-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -45,7 +45,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/contextual_logger.rb
-- lib/contextual_logger/context/handler.rb
+- lib/contextual_logger/context.rb
+- lib/contextual_logger/context_handler.rb
+- lib/contextual_logger/global_context_lock_message.rb
 - lib/contextual_logger/logger_with_context.rb
 - lib/contextual_logger/overrides/active_support/tagged_logging/formatter.rb
 - lib/contextual_logger/redactor.rb

data/lib/contextual_logger/context/handler.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module ContextualLogger
-  module Context
-    class Handler
-      THREAD_CONTEXT_NAMESPACE = 'ContextualLoggerCurrentLoggingContext'
-
-      attr_reader :previous_context, :context
-
-      def self.current_context
-        Thread.current[THREAD_CONTEXT_NAMESPACE] || {}
-      end
-
-      def initialize(context, previous_context: nil)
-        @previous_context = previous_context || self.class.current_context
-        @context = context
-      end
-
-      def set!
-        Thread.current[THREAD_CONTEXT_NAMESPACE] = context
-      end
-
-      def reset!
-        Thread.current[THREAD_CONTEXT_NAMESPACE] = previous_context
-      end
-    end
-  end
-end