lumberjack 1.2.7 → 1.4.2

data/lib/lumberjack/utils.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Lumberjack
+  module Utils
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    NON_SLUGGABLE_PATTERN = /[^A-Za-z0-9_.-]+/.freeze
+    private_constant :NON_SLUGGABLE_PATTERN
+
+    @deprecations = nil
+    @deprecations_lock = nil
+    @hostname = UNDEFINED
+
+    class << self
+      # Print warning when deprecated methods are called the first time. This can be disabled
+      # by setting the environment variable `LUMBERJACK_NO_DEPRECATION_WARNINGS` to "true".
+      # You can see every usage of a deprecated method along with a full stack trace by setting
+      # the environment variable `VERBOSE_LUMBERJACK_DEPRECATION_WARNING` to "true".
+      #
+      # @param method [String] The name of the deprecated method.
+      # @param message [String] Optional message to include in the warning.
+      # @yield The block to execute after the warning.
+      def deprecated(method, message)
+        @deprecations_lock ||= Mutex.new
+        unless @deprecations&.include?(method)
+          @deprecations_lock.synchronize do
+            @deprecations ||= {}
+            unless @deprecations.include?(method)
+              trace = caller[3..-1]
+              unless ENV["VERBOSE_LUMBERJACK_DEPRECATION_WARNING"] == "true"
+                trace = [trace.first]
+                @deprecations[method] = true
+              end
+              message = "DEPRECATION WARNING: #{message} Called from #{trace.join("\n")}"
+              warn(message) unless ENV["LUMBERJACK_NO_DEPRECATION_WARNINGS"] == "true"
+            end
+          end
+        end
+
+        yield
+      end
+
+      # Get the hostname of the machine. The returned value will be in UTF-8 encoding.
+      #
+      # @return [String] The hostname of the machine.
+      def hostname
+        if @hostname.equal?(UNDEFINED)
+          @hostname = force_utf8(Socket.gethostname)
+        end
+        @hostname
+      end
+
+      # Set the hostname to a specific value. If this is not specified, it will use the system hostname.
+      #
+      # @param hostname [String]
+      # @return [void]
+      def hostname=(hostname)
+        @hostname = force_utf8(hostname)
+      end
+
+      # Generate a global process ID that includes the hostname and process ID.
+      #
+      # @return [String] The global process ID.
+      def global_pid
+        if hostname
+          "#{hostname}-#{Process.pid}"
+        else
+          Process.pid.to_s
+        end
+      end
+
+      # Generate a global thread ID that includes the global process ID and the thread name.
+      #
+      # @return [String] The global thread ID.
+      def global_thread_id
+        "#{global_pid}-#{thread_name}"
+      end
+
+      # Get the name of a thread. The value will be based on the thread's name if it exists.
+      # Otherwise a unique id is generated based on the thread's object id. Only alphanumeric
+      # characters, underscores, dashes, and periods are kept in thread name.
+      #
+      # @param thread [Thread] The thread to get the name for. Defaults to the current thread.
+      # @return [String] The name of the thread.
+      def thread_name(thread = Thread.current)
+        thread.name ? slugify(thread.name) : thread.object_id.to_s(36)
+      end
+
+      # Force encode a string to UTF-8. Any invalid byte sequences will be
+      # ignored and replaced with an empty string.
+      #
+      # @param str [String] The string to encode.
+      # @return [String] The UTF-8 encoded string.
+      def force_utf8(str)
+        return nil if str.nil?
+
+        str.dup.force_encoding("ASCII-8BIT").encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+      end
+
+      # Flatten a tag hash to a single level hash with dot notation for nested keys.
+      #
+      # @param tag_hash [Hash] The hash to flatten.
+      # @return [Hash<String, Object>] The flattened hash.
+      # @example
+      #   expand_tags(user: {id: 123, name: "Alice"}, action: "login")})
+      #   # => {"user.id" => 123, "user.name" => "Alice", "action" => "login"}
+      def flatten_tags(tag_hash)
+        return {} unless tag_hash.is_a?(Hash)
+
+        flatten_hash_recursive(tag_hash)
+      end
+
+      # Expand a hash of tags that may contain nested hashes or dot notation keys. Dot notation tags
+      # will be expanded into nested hashes.
+      #
+      # @param tags [Hash] The hash of tags to expand.
+      # @return [Hash] The expanded hash with dot notation keys.
+      #
+      # @example
+      #   expand_tags({"user.id" => 123, "user.name" => "Alice", "action" => "login"})
+      #   # => {"user" => {"id" => 123, "name" => "Alice"}, "action" => "login"}
+      def expand_tags(tags)
+        return {} unless tags.is_a?(Hash)
+
+        expand_dot_notation_hash(tags)
+      end
+
+      private
+
+      def flatten_hash_recursive(hash, prefix = nil)
+        hash.each_with_object({}) do |(key, value), result|
+          full_key = prefix ? "#{prefix}.#{key}" : key.to_s
+          if value.is_a?(Hash)
+            result.merge!(flatten_hash_recursive(value, full_key))
+          else
+            result[full_key] = value
+          end
+        end
+      end
+
+      def slugify(str)
+        return nil if str.nil?
+
+        str = str.gsub(NON_SLUGGABLE_PATTERN, "-")
+        str.delete_prefix!("-")
+        str.chomp!("-")
+        str
+      end
+
+      def expand_dot_notation_hash(hash, expanded = {})
+        return hash unless hash.is_a?(Hash)
+
+        hash.each do |key, value|
+          key = key.to_s
+          if key.include?(".")
+            main_key, sub_key = key.split(".", 2)
+            main_key_hash = expanded[main_key]
+            unless main_key_hash.is_a?(Hash)
+              main_key_hash = {}
+              expanded[main_key] = main_key_hash
+            end
+            expand_dot_notation_hash({sub_key => value}, main_key_hash)
+          elsif value.is_a?(Hash)
+            key_hash = expanded[key]
+            unless key_hash.is_a?(Hash)
+              key_hash = {}
+              expanded[key] = key_hash
+            end
+            expand_dot_notation_hash(value, key_hash)
+          else
+            expanded[key] = value
+          end
+        end
+
+        expanded
+      end
+    end
+  end
+end

data/lib/lumberjack.rb

@@ -1,27 +1,29 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
-require 'rbconfig'
-require 'time'
-require 'thread'
-require 'securerandom'
-require 'logger'
+require "rbconfig"
+require "time"
+require "securerandom"
+require "logger"
+require "fiber"
 
 module Lumberjack
-  LINE_SEPARATOR = (RbConfig::CONFIG['host_os'].match(/mswin/i) ? "\r\n" : "\n")
+  LINE_SEPARATOR = ((RbConfig::CONFIG["host_os"] =~ /mswin/i) ? "\r\n" : "\n")
 
-  require_relative "lumberjack/severity.rb"
-  require_relative "lumberjack/formatter.rb"
+  require_relative "lumberjack/severity"
+  require_relative "lumberjack/formatter"
 
-  require_relative "lumberjack/context.rb"
-  require_relative "lumberjack/log_entry.rb"
-  require_relative "lumberjack/device.rb"
-  require_relative "lumberjack/logger.rb"
-  require_relative "lumberjack/tags.rb"
-  require_relative "lumberjack/tag_formatter.rb"
-  require_relative "lumberjack/tagged_logger_support.rb"
-  require_relative "lumberjack/tagged_logging.rb"
-  require_relative "lumberjack/template.rb"
-  require_relative "lumberjack/rack.rb"
+  require_relative "lumberjack/context"
+  require_relative "lumberjack/log_entry"
+  require_relative "lumberjack/device"
+  require_relative "lumberjack/logger"
+  require_relative "lumberjack/tags"
+  require_relative "lumberjack/tag_context"
+  require_relative "lumberjack/tag_formatter"
+  require_relative "lumberjack/tagged_logger_support"
+  require_relative "lumberjack/tagged_logging"
+  require_relative "lumberjack/template"
+  require_relative "lumberjack/rack"
+  require_relative "lumberjack/utils"
 
   class << self
     # Define a unit of work within a block. Within the block supplied to this
@@ -33,20 +35,30 @@ module Lumberjack
     #
     # For the common use case of treating a single web request as a unit of work, see the
     # Lumberjack::Rack::UnitOfWork class.
+    #
+    # @param id [String] The id for the unit of work.
+    # @return [void]
+    # @deprecated Use tags instead. This will be removed in version 2.0.
     def unit_of_work(id = nil)
-      id ||= SecureRandom.hex(6)
-      context do
-        context[:unit_of_work_id] = id
-        yield
+      Lumberjack::Utils.deprecated("Lumberjack.unit_of_work", "Lumberjack.unit_of_work will be removed in version 2.0. Use Lumberjack::Logger#tag(unit_of_work: id) instead.") do
+        id ||= SecureRandom.hex(6)
+        context do
+          context[:unit_of_work_id] = id
+          yield
+        end
       end
     end
 
     # Get the UniqueIdentifier for the current unit of work.
+    #
+    # @return [String, nil] The id for the current unit of work.
+    # @deprecated Use tags instead. This will be removed in version 2.0.
     def unit_of_work_id
       context[:unit_of_work_id]
     end
 
     # Contexts can be used to store tags that will be attached to all log entries in the block.
+    # The context will apply to all Lumberjack loggers that are used within the block.
     #
     # If this method is called with a block, it will set a logging context for the scope of a block.
     # If there is already a context in scope, a new one will be created that inherits
@@ -54,36 +66,53 @@ module Lumberjack
     #
     # Otherwise, it will return the current context. If one doesn't exist, it will return a new one
     # but that context will not be in any scope.
-    def context
+    #
+    # @return [Lumberjack::Context] The current context if called without a block.
+    def context(&block)
       current_context = Thread.current[:lumberjack_context]
-      if block_given?
-        Thread.current[:lumberjack_context] = Context.new(current_context)
-        begin
-          yield
-        ensure
-          Thread.current[:lumberjack_context] = current_context
-        end
+      if block
+        use_context(Context.new(current_context), &block)
       else
         current_context || Context.new
       end
     end
-    
+
+    # Set the context to use within a block.
+    #
+    # @param [Lumberjack::Context] context The context to use within the block.
+    # @return [Object] The result of the block.
+    def use_context(context, &block)
+      current_context = Thread.current[:lumberjack_context]
+      begin
+        Thread.current[:lumberjack_context] = (context || Context.new)
+        yield
+      ensure
+        Thread.current[:lumberjack_context] = current_context
+      end
+    end
+
     # Return true if inside a context block.
+    #
+    # @return [Boolean]
     def context?
       !!Thread.current[:lumberjack_context]
     end
 
     # Return the tags from the current context or nil if there are no tags.
+    #
+    # @return [Hash, nil]
     def context_tags
       context = Thread.current[:lumberjack_context]
-      context.tags if context
+      context&.tags
     end
 
     # Set tags on the current context
+    #
+    # @param [Hash] tags The tags to set.
+    # @return [void]
     def tag(tags)
       context = Thread.current[:lumberjack_context]
-      context.tag(tags) if context
+      context&.tag(tags)
     end
-
   end
 end

data/lumberjack.gemspec

@@ -1,16 +1,22 @@
 Gem::Specification.new do |spec|
-  spec.name = 'lumberjack'
-  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
-  spec.authors = ['Brian Durand']
-  spec.email = ['bbdurand@gmail.com']
+  spec.name = "lumberjack"
+  spec.version = File.read(File.join(__dir__, "VERSION")).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
 
-  spec.summary = "A simple, powerful, and very fast logging utility that can be a drop in replacement for Logger or ActiveSupport::BufferedLogger."
+  spec.summary = "A simple, powerful, and fast logging utility with excellent structured logging support that can be a drop in replacement for the standard library Logger."
   spec.homepage = "https://github.com/bdurand/lumberjack"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  ignore_files = %w(
+  ignore_files = %w[
     .
     Appraisals
     Gemfile
@@ -18,17 +24,14 @@ Gem::Specification.new do |spec|
     Rakefile
     gemfiles/
     spec/
-  )
-  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject{ |f| ignore_files.any?{ |path| f.start_with?(path) } }
+  ]
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
   end
 
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '>= 2.3.0'
+  spec.required_ruby_version = ">= 2.5.0"
 
-  spec.add_development_dependency("rspec", ["~> 3.0"])
-  spec.add_development_dependency("timecop")
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "appraisal"
+  spec.add_development_dependency "bundler"
 end

metadata

@@ -1,59 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack
 version: !ruby/object:Gem::Version
-  version: 1.2.7
+  version: 1.4.2
 platform: ruby
 authors:
 - Brian Durand
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-30 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: timecop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: appraisal
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,13 +24,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT_LICENSE.txt
 - README.md
@@ -92,11 +51,16 @@ files:
 - lib/lumberjack/formatter/exception_formatter.rb
 - lib/lumberjack/formatter/id_formatter.rb
 - lib/lumberjack/formatter/inspect_formatter.rb
+- lib/lumberjack/formatter/multiply_formatter.rb
 - lib/lumberjack/formatter/object_formatter.rb
 - lib/lumberjack/formatter/pretty_print_formatter.rb
+- lib/lumberjack/formatter/redact_formatter.rb
+- lib/lumberjack/formatter/round_formatter.rb
 - lib/lumberjack/formatter/string_formatter.rb
 - lib/lumberjack/formatter/strip_formatter.rb
 - lib/lumberjack/formatter/structured_formatter.rb
+- lib/lumberjack/formatter/tagged_message.rb
+- lib/lumberjack/formatter/truncate_formatter.rb
 - lib/lumberjack/log_entry.rb
 - lib/lumberjack/logger.rb
 - lib/lumberjack/rack.rb
@@ -104,17 +68,22 @@ files:
 - lib/lumberjack/rack/request_id.rb
 - lib/lumberjack/rack/unit_of_work.rb
 - lib/lumberjack/severity.rb
+- lib/lumberjack/tag_context.rb
 - lib/lumberjack/tag_formatter.rb
 - lib/lumberjack/tagged_logger_support.rb
 - lib/lumberjack/tagged_logging.rb
 - lib/lumberjack/tags.rb
 - lib/lumberjack/template.rb
+- lib/lumberjack/utils.rb
 - lumberjack.gemspec
 homepage: https://github.com/bdurand/lumberjack
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/bdurand/lumberjack
+  source_code_uri: https://github.com/bdurand/lumberjack
+  changelog_uri: https://github.com/bdurand/lumberjack/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -122,16 +91,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
-summary: A simple, powerful, and very fast logging utility that can be a drop in replacement
-  for Logger or ActiveSupport::BufferedLogger.
+summary: A simple, powerful, and fast logging utility with excellent structured logging
+  support that can be a drop in replacement for the standard library Logger.
 test_files: []