lumberjack 1.3.4 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db9d72af596912080ab89e900718d2dc1a4d27dda1eb8320d540fa096325b209
-  data.tar.gz: 0737c0a2bde27fa687af82a6ac65f8ede65abdbe175462bc8c39e515569d3a23
+  metadata.gz: c72bca9355bd37fb691a06a4cea4a341b6905b7b5c15429d41061b2b0afd3813
+  data.tar.gz: 49a18195fadf1de9b2cf43e3ce95c1f5e49d3d81dd4384a722e8f685187f6bbc
 SHA512:
-  metadata.gz: 941b206a2ffcb38760669f04658f9a52ec6eee063e2d76505db7c29c0a2f6b7e2d481fdffa0c88ee6eadc189fcb416e89b0e8490d8eea8513ededefd2ccef21b
-  data.tar.gz: fa95906ee0eb896b77eb33958223831a4b8f8c43b6f1a84a21df93388ee7f37c974c0fb0bdbc1bda1e9836af00d26aed0c11576409bcb153a3cd7dab3e4373c1
+  metadata.gz: 5d58e6244cad6396bf702759c05a130e279d4def0d7bee491817b373fbee79420fa0df776264485e7387657a7dd28bab7e4690b7b0a677d878b98f611432a7f7
+  data.tar.gz: d2c2c8f1765230b39df298c68c89bad1db520acbaabfee7da7381d75336de91ff9c3f709e501683fb2502f6b5f7b61eef89c8814f13fda6c2235c3ac43ef5959

data/CHANGELOG.md

@@ -4,6 +4,18 @@ 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).
 
+## 1.4.0
+
+### Changed
+
+- Tags are consistently flattened internally to dot notation keys. This makes tag handling more consistent when using nested hashes as tag values. This changes how nested tags are merged, though. Now when new nested tags are set they will be merged into the existing tags rather than replacing them entirely. So `logger.tag(foo: {bar: "baz"})` will now merge the `foo.bar` tag into the existing tags rather than replacing the entire `foo` tag.
+- The `Lumberjack::Logger#context` method can now be called without a block. When called with a block it sets up a new tag context for the block. When called without a block, it returns the current tag context in a `Lumberjack::TagContext` object which can be used to add tags to the current context.
+- Tags in `Lumberjack::LogEntry` are now always stored as a hash of flattened keys. This means that when tags are set on a log entry, they will be automatically flattened to dot notation keys. The `tag` method will return a hash of sub-tags if the tag name is a tag prefix.
+
+### Added
+
+- Added `Lumberjack::LogEntry#nested_tags` method to return the tags as a nested hash structure.
+
 ## 1.3.4
 
 ### Added

data/README.md

@@ -50,7 +50,7 @@ logger.info("request completed", duration: elapsed_time, status: response.status
 You can also specify tags on a logger that will be included with every log message.
 
 ```ruby
-logger.tag(host: Socket.gethostname)
+logger.tag_globally(host: Socket.gethostname.force_encoding("UTF-8"))
 ```
 
 You can specify tags that will only be applied to the logger in a block as well.
@@ -64,22 +64,37 @@ end
 logger.info("there") # Will not include the `thread_id` or `count` tag
 ```
 
+The block opens up a new tag context. The context applies only within a block and only for the currently executing thread. You can also open up a new context block without specifying any tags and then add tags to the context within the block.
+
+```ruby
+logger.context do # When a block is given to `context`, it opens a new empty tag context.
+  # `context` can be called without a block, to get an TagContext object for manipulating tags.
+  logger.context.tag(user_id: current_user.id, username: current_user.username)
+  logger.context["user_role"] = current_user.role # You can also use hash syntax to set tags.
+  logger.info("user logged in") # Will include the `user_id`, `username`, and `user_role` tags.
+end
+logger.info("no user") # Will not include the tags
+```
+
 You can also set tags to `Proc` objects that will be evaluated when creating a log entry.
 
 ```ruby
-logger.tag(thread_id: lambda { Thread.current.object_id })
+logger.tag_globally(thread_id: lambda { Thread.current.object_id })
+
 Thread.new do
   logger.info("inside thread") # Will include the `thread_id` tag with id of the spawned thread
 end
+
 logger.info("outside thread") # Will include the `thread_id` tag with id of the main thread
 ```
 
-Finally, you can specify a logging context with tags that apply within a block to all loggers.
+Finally, you can specify a global logging context that applies to all loggers.
 
 ```ruby
 Lumberjack.context do
-  Lumberjack.tag(request_id: SecureRandom.hex)
+  Lumberjack.tag(request_id: SecureRandom.hex) # add a global context tag
   logger.info("begin request") # Will include the `request_id` tag
+  event_logger.info("http.request") # Will also include the `request_id` tag
 end
 logger.info("no requests") # Will not include the `request_id` tag
 ```
@@ -134,7 +149,7 @@ When combined with structured output devices (like [`lumberjack_json_device`](ht
 
 #### Compatibility with ActiveSupport::TaggedLogging
 
-`Lumberjack::Logger` version 1.1.2 or greater is compatible with `ActiveSupport::TaggedLogging`. This is so that other code that expects to have a logger that responds to the `tagged` method will work. Any tags added with the `tagged` method will be appended to an array in the "tagged" tag.
+`Lumberjack::Logger` is compatible with `ActiveSupport::TaggedLogging`. This is so that other code that expects to have a logger that responds to the `tagged` method will work. Any tags added with the `tagged` method will be appended to an array in the "tagged" tag.
 
 ```ruby
 logger.tagged("foo", "bar=1", "other") do
@@ -199,6 +214,7 @@ There are several built in classes you can add as formatters. You can use a symb
 - `:pretty_print` - `Lumberjack::Formatter::PrettyPrintFormatter` - returns the pretty print format of the object.
 - `:id` - `Lumberjack::Formatter::IdFormatter` - returns a hash of the object with keys for the id attribute and class.
 - `:structured` - `Lumberjack::Formatter::StructuredFormatter` - crawls the object and applies the formatter recursively to Enumerable objects found in it (arrays, hashes, etc.).
+- `:truncate` - `Lumberjack::Formatter::TruncateFormatter` - truncates long strings to a specified length.
 
 To define your own formatter, either provide a block or an object that responds to `call` with a single argument.
 
@@ -260,7 +276,7 @@ logger.tag_formatter.add("user.username", &:upcase)
 
 #### Templates
 
-If you use the built-in `Lumberjack::Writer` derived devices, you can also customize the Template used to format the LogEntry.
+If you use the built-in `Lumberjack::Device::Writer` derived devices, you can also customize the Template used to format the LogEntry.
 
 See `Lumberjack::Template` for a complete list of macros you can use in the template. You can also use a block that receives a `Lumberjack::LogEntry` as a template.
 
@@ -286,7 +302,7 @@ The logger has hooks for devices that support buffering to potentially increase
 
 You can use the `:flush_seconds` option on the logger to periodically flush the log. This is usually a good idea so you can more easily debug hung processes. Without periodic flushing, a process that hangs may never write anything to the log because the messages are sitting in a buffer. By turning on periodic flushing, the logged messages will be written which can greatly aid in debugging the problem.
 
-The built in stream based logging devices use an internal buffer. The size of the buffer (in bytes) can be set with the `:buffer_size` options when initializing a logger. The default behavior is to not to buffer.
+The built in stream based logging devices use an internal buffer. The size of the buffer (in bytes) can be set with the `:buffer_size` options when initializing a logger. The default behavior is to not buffer.
 
 ```ruby
   # Set buffer to flush after 8K has been written to the log.
@@ -361,7 +377,7 @@ To change the log message format to output JSON, you could use this code:
   config.logger = Lumberjack::Logger.new(log_file_path, :template => lambda{|e| JSON.dump(time: e.time, level: e.severity_label, message: e.message)})
 ```
 
-To send log messages to syslog instead of to a file, you could use this (require the lumberjack_syslog_device gem):
+To send log messages to syslog instead of to a file, you could use this (requires the lumberjack_syslog_device gem):
 
 ```ruby
   config.logger = Lumberjack::Logger.new(Lumberjack::SyslogDevice.new)

data/VERSION

@@ -1 +1 @@
-1.3.4
+1.4.0

data/lib/lumberjack/context.rb

@@ -9,6 +9,7 @@ module Lumberjack
     def initialize(parent_context = nil)
       @tags = {}
       @tags.merge!(parent_context.tags) if parent_context
+      @tag_context = TagContext.new(@tags)
     end
 
     # Set tags on the context.
@@ -16,9 +17,7 @@ module Lumberjack
     # @param tags [Hash] The tags to set.
     # @return [void]
     def tag(tags)
-      tags.each do |key, value|
-        @tags[key.to_s] = value
-      end
+      @tag_context.tag(tags)
     end
 
     # Get a context tag.
@@ -26,7 +25,7 @@ module Lumberjack
     # @param key [String, Symbol] The tag key.
     # @return [Object] The tag value.
     def [](key)
-      @tags[key.to_s]
+      @tag_context[key]
     end
 
     # Set a context tag.
@@ -35,7 +34,15 @@ module Lumberjack
     # @param value [Object] The tag value.
     # @return [void]
     def []=(key, value)
-      @tags[key.to_s] = value
+      @tag_context[key] = value
+    end
+
+    # Remove tags from the context.
+    #
+    # @param keys [Array<String, Symbol>] The tag keys to remove.
+    # @return [void]
+    def delete(*keys)
+      @tag_context.delete(*keys)
     end
 
     # Clear all the context data.

data/lib/lumberjack/log_entry.rb

@@ -64,11 +64,28 @@ module Lumberjack
     end
 
     # Return the tag with the specified name.
+    #
+    # @param name [String, Symbol] The tag name.
+    # @return [Object, nil] The tag value or nil if the tag does not exist.
     def tag(name)
-      tags[name.to_s] if tags
+      TagContext.new(tags)[name]
+    end
+
+    # Helper method to expand the tags into a nested structure. Tags with dots in the name
+    # will be expanded into nested hashes.
+    #
+    # @return [Hash] The tags expanded into a nested structure.
+    #
+    # @example
+    #   entry = Lumberjack::LogEntry.new(Time.now, Logger::INFO, "test", "app", 1500, "a.b.c" => 1, "a.b.d" => 2)
+    #   entry.nested_tags # => {"a" => {"b" => {"c" => 1, "d" => 2}}}
+    def nested_tags
+      Utils.expand_tags(tags)
     end
 
     # Return true if the log entry has no message and no tags.
+    #
+    # @return [Boolean] True if the log entry is empty, false otherwise.
     def empty?
       (message.nil? || message == "") && (tags.nil? || tags.empty?)
     end

data/lib/lumberjack/logger.rb

@@ -223,6 +223,7 @@ module Lumberjack
         end
 
         progname ||= self.progname
+        message_tags = Utils.flatten_tags(message_tags) if message_tags
 
         current_tags = self.tags
         tags = nil unless tags.is_a?(Hash)
@@ -507,16 +508,16 @@ module Lumberjack
     # @param [Hash] tags The tags to set.
     # @return [void]
     def tag(tags, &block)
-      tags = Tags.stringify_keys(tags)
       thread_tags = thread_local_value(:lumberjack_logger_tags)
       if block
-        merged_tags = (thread_tags ? thread_tags.merge(tags) : tags.dup)
+        merged_tags = (thread_tags ? thread_tags.dup : {})
+        TagContext.new(merged_tags).tag(tags)
         push_thread_local_value(:lumberjack_logger_tags, merged_tags, &block)
       elsif thread_tags
-        thread_tags.merge!(tags)
+        TagContext.new(thread_tags).tag(tags)
         nil
       else
-        Lumberjack::Utils.deprecated("Lumberjack::Logger#tag", "Lumberjack::Logger#tag must be called with a block or inside a context block. In version 2.0 it will no longer be used for setting global tags. Use Lumberjack::Logger#tag_globally instead.") do
+        Utils.deprecated("Lumberjack::Logger#tag", "Lumberjack::Logger#tag must be called with a block or inside a context block. In version 2.0 it will no longer be used for setting global tags. Use Lumberjack::Logger#tag_globally instead.") do
           tag_globally(tags)
         end
       end
@@ -525,10 +526,21 @@ module Lumberjack
     # Set up a context block for the logger. All tags added within the block will be cleared when
     # the block exits.
     #
+    # @param [Proc] block The block to execute with the tag context.
+    # @return [TagContext] If no block is passed, then a Lumberjack::TagContext is returned that can be used
+    #   to interact with the tags (add, remove, etc.).
+    # @yield [TagContext] If a block is passed, it will be yielded a TagContext object that can be used to
+    #   add or remove tags within the context.
     def context(&block)
-      thread_tags = thread_local_value(:lumberjack_logger_tags)&.dup
-      thread_tags ||= {}
-      push_thread_local_value(:lumberjack_logger_tags, thread_tags, &block)
+      if block
+        thread_tags = thread_local_value(:lumberjack_logger_tags)&.dup
+        thread_tags ||= {}
+        push_thread_local_value(:lumberjack_logger_tags, thread_tags) do
+          block.call(TagContext.new(thread_tags))
+        end
+      else
+        TagContext.new(thread_local_value(:lumberjack_logger_tags) || {})
+      end
     end
 
     # Add global tags to the logger that will appear on all log entries.
@@ -536,24 +548,19 @@ module Lumberjack
     # @param [Hash] tags The tags to set.
     # @return [void]
     def tag_globally(tags)
-      tags = Tags.stringify_keys(tags)
-      @tags.merge!(tags)
+      TagContext.new(@tags).tag(tags)
       nil
     end
 
-    # Remove a tag from the current tag context. If this is called inside a block to a
-    # call to `tag`, the tags will only be removed for the duration of that block. Otherwise
-    # they will be removed from the global tags.
+    # Remove a tag from the current tag context. If this is called inside a tag context,
+    # the tags will only be removed for the duration of that block. Otherwise they will be removed
+    # from the global tags.
     #
     # @param [Array<String, Symbol>] tag_names The tags to remove.
     # @return [void]
     def remove_tag(*tag_names)
-      thread_tags = thread_local_value(:lumberjack_logger_tags)
-      if thread_tags
-        tag_names.each { |name| thread_tags.delete(name.to_s) }
-      else
-        tag_names.each { |name| @tags.delete(name.to_s) }
-      end
+      tags = thread_local_value(:lumberjack_logger_tags) || @tags
+      TagContext.new(tags).delete(*tag_names)
     end
 
     # Return all tags in scope on the logger including global tags set on the Lumberjack
@@ -575,24 +582,8 @@ module Lumberjack
     # @param [String, Symbol] name The name of the tag to get.
     # @return [Object, nil] The value of the tag or nil if the tag does not exist.
     def tag_value(name)
-      all_tags = tags
-      return nil if tags.empty?
-
       name = name.join(".") if name.is_a?(Array)
-      name = name.to_s
-      return all_tags[name] if all_tags.include?(name)
-
-      flattened_tags = Lumberjack::Utils.flatten_tags(all_tags)
-      return flattened_tags[name] if flattened_tags.include?(name)
-
-      flattened_tags.keys.select { |key| key.include?(".") }.each do |key|
-        parts = key.split(".")
-        while (subkey = parts.pop)
-          flattened_tags[parts.join(".")] = {subkey => flattened_tags[(parts + [subkey]).join(".")]}
-        end
-      end
-
-      flattened_tags[name]
+      TagContext.new(tags)[name]
     end
 
     # Remove all tags on the current logger and logging context within a block.
@@ -653,15 +644,12 @@ module Lumberjack
     # Merge a tags hash into an existing tags hash.
     def merge_tags(current_tags, tags)
       if current_tags.nil? || current_tags.empty?
-        tags = Tags.stringify_keys(tags) unless tags.nil?
+        tags
+      elsif tags.nil?
+        current_tags
       else
-        tags = if tags.nil?
-          current_tags.dup
-        else
-          current_tags.merge(Tags.stringify_keys(tags))
-        end
+        current_tags.merge(tags)
       end
-      tags
     end
 
     # Set a local value for a thread tied to this object.

data/lib/lumberjack/tag_context.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # A tag context provides an interface for manipulating a tag hash.
+  class TagContext
+    def initialize(tags)
+      @tags = tags
+    end
+
+    # Merge new tags into the context tags. Tag values will be flattened using dot notation
+    # on the keys. So `{ a: { b: 'c' } }` will become `{ 'a.b' => 'c' }`.
+    #
+    # If a block is given, then the tags will only be added for the duration of the block.
+    #
+    # @param tags [Hash] The tags to set.
+    # @return [void]
+    def tag(tags)
+      @tags.merge!(Utils.flatten_tags(tags))
+    end
+
+    # Get a tag value.
+    #
+    # @param name [String, Symbol] The tag key.
+    # @return [Object] The tag value.
+    def [](name)
+      return nil if @tags.empty?
+
+      name = name.to_s
+      return @tags[name] if @tags.include?(name)
+
+      # Check for partial matches in dot notation and return the hash representing the partial match.
+      prefix_key = "#{name}."
+      matching_tags = {}
+      @tags.each do |key, value|
+        if key.start_with?(prefix_key)
+          # Remove the prefix to get the relative key
+          relative_key = key[prefix_key.length..-1]
+          matching_tags[relative_key] = value
+        end
+      end
+
+      return nil if matching_tags.empty?
+      matching_tags
+    end
+
+    # Set a tag value.
+    #
+    # @param name [String, Symbol] The tag name.
+    # @param value [Object] The tag value.
+    # @return [void]
+    def []=(name, value)
+      if value.is_a?(Hash)
+        @tags.merge!(Utils.flatten_tags(name => value))
+      else
+        @tags[name.to_s] = value
+      end
+    end
+
+    # Remove tags from the context.
+    #
+    # @param names [Array<String, Symbol>] The tag names to remove.
+    # @return [void]
+    def delete(*names)
+      names.each do |name|
+        prefix_key = "#{name}."
+        @tags.delete_if { |k, _| k == name.to_s || k.start_with?(prefix_key) }
+      end
+      nil
+    end
+
+    # Return a copy of the tags as a hash.
+    #
+    # @return [Hash]
+    def to_h
+      @tags.dup
+    end
+  end
+end

data/lib/lumberjack/utils.rb

@@ -110,15 +110,7 @@ module Lumberjack
       def flatten_tags(tag_hash)
         return {} unless tag_hash.is_a?(Hash)
 
-        tag_hash.each_with_object({}) do |(key, value), result|
-          if value.is_a?(Hash)
-            value.each do |sub_key, sub_value|
-              result["#{key}.#{sub_key}"] = sub_value
-            end
-          else
-            result[key.to_s] = value
-          end
-        end
+        flatten_hash_recursive(tag_hash)
       end
 
       # Expand a hash of tags that may contain nested hashes or dot notation keys. Dot notation tags
@@ -138,6 +130,17 @@ module Lumberjack
 
       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?
 

data/lib/lumberjack.rb

@@ -17,6 +17,7 @@ module Lumberjack
   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"
@@ -57,6 +58,7 @@ module Lumberjack
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  version: 1.4.0
 platform: ruby
 authors:
 - Brian Durand
@@ -68,6 +68,7 @@ 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