contextual_logger 0.9.0 → 0.12.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f52753d4acdf8c75e8c94154a8002490e88ccc0201bf6623d6b47a2c65791f
-  data.tar.gz: 304de20b917e9c4078dc83ce96867f44af03d9adbf95e18091e3987e17cabcaa
+  metadata.gz: c2ef105e4dfaf32e5e215d83e05ac6ba4f5c67a32cb11e214598a668b4afd34e
+  data.tar.gz: d8fa3b949bf2880a1992f6bce1fcfd6b6b59ec4aa46340d9752c8b27fc7dd6cc
 SHA512:
-  metadata.gz: 5b3e5489d812a5dc8885a43f92d631a3d99ce3d1a5f7cb631ed16b2457cc2793f4c9ec72d91c09121db047cb83eac3f807db2a722e2481bfc4a39cf85cd12970
-  data.tar.gz: 78e344d513e2c04ccfa545cc492a514af7d90bf06c335ee80629c10be87339db3004e3fa9d9c801c327d3b4af6af7eec48ece482e05519da7b55cd1a052bd480
+  metadata.gz: 3df6d16bf7ffc7cc36bb0f95103222f1791a228ee4e1034ef883261bdaa10ac5d16c57fafa6cdd58d524fee2ebec5c86fab5b2dcc3df05eaf2d35acea1f00eed
+  data.tar.gz: e1db9f65be3eb35690cea59ceee623188b40f03377b7a467d12d2644ed8a957246afb70a43eb736a639d541ecdf093d7832f909b0878d1e87c41d889e9be44ea

data/lib/contextual_logger.rb

@@ -5,8 +5,19 @@ 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/registry'
 
 module ContextualLogger
+  LOG_LEVEL_NAMES_TO_SEVERITY =
+  {
+    debug:  Logger::Severity::DEBUG,
+    info:   Logger::Severity::INFO,
+    warn:   Logger::Severity::WARN,
+    error:  Logger::Severity::ERROR,
+    fatal:  Logger::Severity::FATAL,
+    unknown: Logger::Severity::UNKNOWN
+  }.freeze
+
   class << self
     def new(logger)
       logger.extend(LoggerMixin)
@@ -17,22 +28,8 @@ module ContextualLogger
       if log_level.is_a?(Integer) && (Logger::Severity::DEBUG..Logger::Severity::UNKNOWN).include?(log_level)
         log_level
       else
-        case log_level.to_s.downcase
-        when 'debug'
-          Logger::Severity::DEBUG
-        when 'info'
-          Logger::Severity::INFO
-        when 'warn'
-          Logger::Severity::WARN
-        when 'error'
-          Logger::Severity::ERROR
-        when 'fatal'
-          Logger::Severity::FATAL
-        when 'unknown'
-          Logger::Severity::UNKNOWN
-        else
+        LOG_LEVEL_NAMES_TO_SEVERITY[log_level.to_s.downcase.to_sym] or
           raise ArgumentError, "invalid log level: #{log_level.inspect}"
-        end
       end
     end
 
@@ -49,12 +46,22 @@ module ContextualLogger
   module LoggerMixin
     delegate :register_secret, to: :redactor
 
+    def register_context(&block)
+      block or raise ArgumentError, 'Block of context definitions was not passed'
+      @context_registry = Context::Registry.new(&block)
+    end
+
     def global_context=(context)
-      Context::Handler.new(context).set!
+      Context::Handler.new(context_registry.format(context)).set!
     end
 
     def with_context(context)
-      context_handler = Context::Handler.new(current_context_for_thread.deep_merge(context))
+      context_handler = Context::Handler.new(
+        current_context_for_thread.deep_merge(
+          context_registry.format(context)
+        )
+      )
+
       context_handler.set!
       if block_given?
         begin
@@ -72,47 +79,56 @@ module ContextualLogger
       Context::Handler.current_context
     end
 
-    def debug(message = nil, context = {})
-      add(Logger::Severity::DEBUG, message.nil? && block_given? ? yield : message, **context)
-    end
-
-    def info(message = nil, context = {})
-      add(Logger::Severity::INFO, message.nil? && block_given? ? yield : message, **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`,
+    # in order to be compatible with classic implementations like in the plain ::Logger and
+    # ActiveSupport::Logger.broadcast.
 
-    def warn(message = nil, context = {})
-      add(Logger::Severity::WARN, message.nil? && block_given? ? yield : message, **context)
-    end
+    # Note that we can't yield before `add` because `add` might skip it based on log_level. And we can't check
+    # log_level here because we might be running in ActiveSupport::Logging.broadcast which has multiple
+    # loggers, each with their own log_level.
 
-    def error(message = nil, context = {})
-      add(Logger::Severity::ERROR, message.nil? && block_given? ? yield : message, **context)
-    end
-
-    def fatal(message = nil, context = {})
-      add(Logger::Severity::FATAL, message.nil? && block_given? ? yield : message, **context)
-    end
-
-    def unknown(message = nil, context = {})
-      add(Logger::Severity::UNKNOWN, message.nil? && block_given? ? yield : message, **context)
+    LOG_LEVEL_NAMES_TO_SEVERITY.each do |method_name, log_level|
+      class_eval(<<~EOS, __FILE__, __LINE__ + 1)
+        def #{method_name}(arg = nil, **context, &block)
+          if context.empty?
+            add(#{log_level}, nil, arg, &block)
+          else
+            if arg.nil?
+              add(#{log_level}, nil, context, &block)
+            elsif block
+              add(#{log_level}, nil, context.merge(progname: arg), &block)
+            else
+              add(#{log_level}, arg, context)
+            end
+          end
+        end
+      EOS
     end
 
     def log_level_enabled?(severity)
       severity >= level
     end
 
-    def add(init_severity, message = nil, init_progname = nil, **context)   # Ruby will prefer to match hashes up to last ** argument
-      severity = init_severity || UNKNOWN
+    # 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
+      severity = arg_severity || UNKNOWN
       if log_level_enabled?(severity)
-        progname = init_progname || @progname
-        if message.nil?
+        if arg1.nil?
           if block_given?
             message = yield
+            progname = arg2 || context.delete(:progname) || @progname
           else
-            message = init_progname
+            message = arg2
             progname = @progname
           end
+        else
+          message = arg1
+          progname = arg2 || @progname
         end
-        write_entry_to_log(severity, Time.now, progname, message, context: current_context_for_thread.deep_merge(context))
+        write_entry_to_log(severity, Time.now, progname, message, context: current_context_for_thread.deep_merge(context_registry.format(context)))
       end
 
       true
@@ -128,27 +144,36 @@ module ContextualLogger
 
     private
 
+    def context_registry
+      @context_registry ||= Context::Registry.new do
+        strict false
+        raise_on_missing_definition false
+      end
+    end
+
     def redactor
       @redactor ||= Redactor.new
     end
 
     def format_message(severity, timestamp, progname, message, context: {})
+      normalized_message = ContextualLogger.normalize_message(message)
+      normalized_progname = ContextualLogger.normalize_message(progname) unless progname.nil?
       if @formatter
-        @formatter.call(severity, timestamp, progname, { message: ContextualLogger.normalize_message(message), **context })
+        @formatter.call(severity, timestamp, normalized_progname, { message: normalized_message }.merge!(context))
       else
-        "#{basic_json_log_entry(severity, timestamp, progname, message, context: context)}\n"
+        "#{basic_json_log_entry(severity, timestamp, normalized_progname, normalized_message, context: context)}\n"
       end
     end
 
-    def basic_json_log_entry(severity, timestamp, progname, message, context:)
+    def basic_json_log_entry(severity, timestamp, normalized_progname, normalized_message, context:)
       message_hash = {
-        message:   ContextualLogger.normalize_message(message),
+        message: normalized_progname ? "#{normalized_progname}: #{normalized_message}" : normalized_message,
         severity:  severity,
         timestamp: timestamp
       }
-      message_hash[:progname] = progname if progname
+      message_hash[:progname] = normalized_progname if normalized_progname
 
-      # using merge! instead of merge for speed of operation
+      # merge! is faster and OK here since message_hash is still local only to this method
       message_hash.merge!(context).to_json
     end
   end

data/lib/contextual_logger/context/handler.rb

@@ -7,8 +7,10 @@ module ContextualLogger
 
       attr_reader :previous_context, :context
 
-      def self.current_context
-        Thread.current[THREAD_CONTEXT_NAMESPACE] || {}
+      class << self
+        def current_context
+          Thread.current[THREAD_CONTEXT_NAMESPACE] || {}
+        end
       end
 
       def initialize(context, previous_context: nil)

data/lib/contextual_logger/context/registry.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'registry_types/string'
+require_relative 'registry_types/boolean'
+require_relative 'registry_types/number'
+require_relative 'registry_types/date'
+require_relative 'registry_types/hash'
+
+# This class is responsible for holding the registered context shape that will
+# be used by the LoggerMixin to make sure that the context matches the shape
+# defined
+
+# logger.configure_context do
+#   strict false
+#
+#   string test_string
+#   integer test_integer
+#   hash :test_hash do
+#     string :test_string_in_hash
+#     date :date_time_in_hash
+#   end
+# end
+
+module ContextualLogger
+  module Context
+    class Registry < RegistryTypes::Hash
+      class DuplicateDefinitionError < StandardError; end
+      class MissingDefinitionError < StandardError; end
+
+      def initialize(&definitions)
+        @strict                        = true
+        @raise_on_missing_definition = true
+
+        super
+      end
+
+      def strict?
+        @strict
+      end
+
+      def raise_on_missing_definition?
+        @raise_on_missing_definition
+      end
+
+      def format(context)
+        if strict?
+          super(context, raise_on_missing_definition?)
+        else
+          context
+        end
+      end
+
+      alias context_shape to_h
+
+      def to_h
+        {
+          strict: @strict,
+          context_shape: context_shape
+        }
+      end
+
+      private
+
+      def strict(value)
+        @strict = value
+      end
+
+      def raise_on_missing_definition(value)
+        @raise_on_missing_definition = value
+      end
+    end
+  end
+end

data/lib/contextual_logger/context/registry_types/boolean.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  module Context
+    module RegistryTypes
+      class Boolean
+        attr_reader :formatter
+
+        def initialize(formatter: nil)
+          @formatter = formatter || ->(value) { value ? true : false }
+        end
+
+        def to_h
+          { type: :boolean, formatter: formatter }
+        end
+
+        def format(value)
+          case formatter
+          when Proc
+            formatter.call(value)
+          else
+            value.send(formatter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contextual_logger/context/registry_types/date.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  module Context
+    module RegistryTypes
+      class Date
+        attr_reader :formatter
+
+        def initialize(formatter: nil)
+          @formatter = formatter || ->(value) { value.iso8601(6) }
+        end
+
+        def to_h
+          { type: :date, formatter: formatter }
+        end
+
+        def format(value)
+          case formatter
+          when Proc
+            formatter.call(value)
+          else
+            value.send(formatter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contextual_logger/context/registry_types/hash.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'string'
+require_relative 'boolean'
+require_relative 'number'
+require_relative 'date'
+
+module ContextualLogger
+  module Context
+    module RegistryTypes
+      class Hash
+        def initialize(&definitions)
+          @definitions = {}
+
+          run(&definitions)
+        end
+
+        def to_h
+          @definitions.reduce({}) do |shape_hash, (key, value)|
+            shape_hash.merge(key => value.to_h)
+          end
+        end
+
+        def format(context, raise_on_missing_definition)
+          context.reduce({}) do |formatted_context, (key, value)|
+            if (definition = @definitions[key])
+              formatted_context[key] = if definition.is_a?(RegistryTypes::Hash)
+                                         definition.format(value, raise_on_missing_definition)
+                                       else
+                                         definition.format(value)
+                                       end
+            elsif raise_on_missing_definition
+              raise Registry::MissingDefinitionError, "Attempting to apply context #{key} that is missing a definition in the registry"
+            end
+
+            formatted_context
+          end
+        end
+
+        private
+
+        def string(context_key, formatter: nil)
+          dedup(context_key, :string)
+          @definitions[context_key] = RegistryTypes::String.new(formatter: formatter)
+        end
+
+        def boolean(context_key, formatter: nil)
+          dedup(context_key, :boolean)
+          @definitions[context_key] = RegistryTypes::Boolean.new(formatter: formatter)
+        end
+
+        def number(context_key, formatter: nil)
+          dedup(context_key, :number)
+          @definitions[context_key] = RegistryTypes::Number.new(formatter: formatter)
+        end
+
+        def date(context_key, formatter: nil)
+          dedup(context_key, :date)
+          @definitions[context_key] = RegistryTypes::Date.new(formatter: formatter)
+        end
+
+        def hash(context_key, &definitions)
+          dedup(context_key, :hash)
+          @definitions[context_key] = RegistryTypes::Hash.new(&definitions)
+        end
+
+        def run(&definitions)
+          instance_eval(&definitions)
+        end
+
+        def dedup(key, type)
+          @definitions.include?(key) and
+            raise Registry::DuplicateDefinitionError, "Defining duplicate entry #{key} previously as #{@definitions[key]} and now as #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/contextual_logger/context/registry_types/number.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  module Context
+    module RegistryTypes
+      class Number
+        attr_reader :formatter
+
+        def initialize(formatter: nil)
+          @formatter = formatter || :to_i
+        end
+
+        def to_h
+          { type: :number, formatter: formatter }
+        end
+
+        def format(value)
+          case formatter
+          when Proc
+            formatter.call(value)
+          else
+            value.send(formatter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contextual_logger/context/registry_types/string.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ContextualLogger
+  module Context
+    module RegistryTypes
+      class String
+        attr_reader :formatter
+
+        def initialize(formatter: nil)
+          @formatter = formatter || :to_s
+        end
+
+        def to_h
+          { type: :string, formatter: formatter }
+        end
+
+        def format(value)
+          case formatter
+          when Proc
+            formatter.call(value)
+          else
+            value.send(formatter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/contextual_logger/logger_with_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/hash/keys'
+
 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.
@@ -13,7 +15,7 @@ module ContextualLogger
       logger.is_a?(LoggerMixin) or raise ArgumentError, "logger must include ContextualLogger::LoggerMixin (got #{logger.inspect})"
       @logger = logger
       self.level = level
-      @context = context
+      @context = normalize_context(context)
       @merged_context_cache = {}  # so we don't have to merge every time
     end
 
@@ -36,6 +38,29 @@ module ContextualLogger
       @logger.write_entry_to_log(severity, timestamp, progname, message, context: merged_context)
     end
 
+    private
+
+    def normalize_context(context)
+      if warn_on_string_keys(context)
+        context.deep_symbolize_keys
+      else
+        context
+      end
+    end
+
+    def warn_on_string_keys(context)
+      if deep_key_has_string?(context)
+        ActiveSupport::Deprecation.warn('Context keys must use symbols not strings. This will be asserted as of contextual_logger v1.0.0')
+      end
+    end
+
+    def deep_key_has_string?(hash)
+      hash.any? do |key, value|
+        key.is_a?(String) ||
+          (value.is_a?(Hash) && deep_key_has_string?(value))
+      end
+    end
+
     class << self
       def for_log_source(logger, log_source, level: nil)
         new(logger, { log_source: log_source }, level: level)

data/lib/contextual_logger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ContextualLogger
-  VERSION = '0.9.0'
+  VERSION = '0.12.0.pre.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contextual_logger
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.12.0.pre.1
 platform: ruby
 authors:
 - James Ebentier
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-17 00:00:00.000000000 Z
+date: 2020-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -46,6 +46,12 @@ extra_rdoc_files: []
 files:
 - lib/contextual_logger.rb
 - lib/contextual_logger/context/handler.rb
+- lib/contextual_logger/context/registry.rb
+- lib/contextual_logger/context/registry_types/boolean.rb
+- lib/contextual_logger/context/registry_types/date.rb
+- lib/contextual_logger/context/registry_types/hash.rb
+- lib/contextual_logger/context/registry_types/number.rb
+- lib/contextual_logger/context/registry_types/string.rb
 - lib/contextual_logger/logger_with_context.rb
 - lib/contextual_logger/overrides/active_support/tagged_logging/formatter.rb
 - lib/contextual_logger/redactor.rb
@@ -56,7 +62,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/Invoca/contextual_logger
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,12 +73,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.0.3
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Add context to your logger
 test_files: []