cogger 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 051cbeb63381e6680f86fd1b73a1e6648d6ecc1befc37824d0425cbb12d0fb63
-  data.tar.gz: 8772b28a29157d2f023096eaf40ba28c252888e3430e5ddc673ade49888b7da2
+  metadata.gz: 394c25bd5359cd226784df811d32eca048dbef8aac78e886009259c3ceb5ab7c
+  data.tar.gz: 6f803583d161c300ac94ab8ca9b2d8187d17b2e389c23a9883cf3fe827cd5bbc
 SHA512:
-  metadata.gz: 4b290ebea636e3744c68dd07c1cd37bd310fa3c99600a8b7a32ed93dcdcc651559ff718fcfe43446c7bad91772ba25eb4bb60bfe0ff9f2c6f85d8158dc58c9c1
-  data.tar.gz: 163afc50ba9118ab76f2ff75f351b4d2b60992b29f317bbfab218e310ada42890fec1e5cfed6993bde0421d67126b65038adbe7b81791f062c07ae82e32c3143
+  metadata.gz: cab259078b7c9e07de8091cbe94a1f890a704dda85dedda0201293b9e2c3d50c357ceafb6d1d6723aae56e1923088fc1be7ae81ae5304f13d6723c6ffb5a8420
+  data.tar.gz: 1ecb68b40b4daa2e56ed50b43f1952cdcb5b4d99ffc7b3990809be0e86321baffb7cc30119afef60bcc373c9df086fc71e035a9bbeba598d0feb864d98c620ce

data/README.adoc

@@ -142,6 +142,34 @@ logger = Cogger.new id: :demo,
                     suffix: "%Y"
 ----
 
+=== Identity
+
+Your logger's identity defaults to `$PROGRAM_NAME` -- as mentioned earlier -- but can be customized during initialization. Example:
+
+[source,ruby]
+----
+logger = Cogger.new id: :demo
+logger.info "A demonstration."
+
+# 🟢 [demo] A demonstration.
+----
+
+You can also customize the identity by passing in an ID per log entry. Example:
+
+[source,ruby]
+----
+logger = Cogger.new
+
+logger.info "A demonstration.", id: :other
+# 🟢 [other] A demonstration.
+
+logger.info(id: :other) { "A demonstration." }
+# 🟢 [other] A demonstration.
+
+logger.info { {id: :other, message: "A demonstration."} }
+# 🟢 [other] A demonstration.
+----
+
 === Levels
 
 Supported levels can be obtained via `Cogger::LEVELS`. Example:
@@ -165,7 +193,26 @@ The above adheres to {rfc_3339_link} and can be customized -- as mentioned earli
 
 [source,ruby]
 ----
-Cogger.new datetime_format: "%Y-%m-%d"
+logger = Cogger.new formatter: :json, datetime_format: "%Y-%m-%d"
+logger.info "A demonstration."
+
+# {"id":"console","level":"INFO","at":"2026-06-28","message":"A demonstration."}
+----
+
+You can also customize the date/time format by passing in an date/time format per log entry. Example:
+
+[source,ruby]
+----
+logger = Cogger.new formatter: :json
+
+logger.info "A demonstration.", datetime_format: "%Y-%m-%d"
+# {"id":"console","level":"INFO","at":"2026-06-28","message":"A demonstration."}
+
+logger.info(datetime_format: "%Y-%m-%d") { "A demonstration." }
+# {"id":"console","level":"INFO","at":"2026-06-28","message":"A demonstration."}
+
+logger.info { {datetime_format: "%Y-%m-%d", message: "A demonstration."} }
+# {"id":"console","level":"INFO","at":"2026-06-28","message":"A demonstration."}
 ----
 
 === Environment
@@ -192,18 +239,25 @@ Each instance can be mutated using the following messages:
 ----
 logger = Cogger.new io: StringIO.new
 
-logger.close                                       # nil
-logger.reopen                                      # Logger
-logger.debug!                                      # 0
-logger.info!                                       # 1
-logger.warn!                                       # 2
-logger.error!                                      # 3
-logger.fatal!                                      # 4
-logger.formatter = Cogger::Formatters::Simple.new  # Cogger::Formatters::Simple
-logger.level = Logger::WARN                        # 2
+logger.close                 # nil
+logger.reopen                # Logger
+logger.debug!                # 0
+logger.info!                 # 1
+logger.warn!                 # 2
+logger.error!                # 3
+logger.fatal!                # 4
+logger.formatter = :simple   # :simple
+logger.level = Logger::WARN  # 2
 ----
 
-Please see the {logger_link} documentation for more information.
+When setting the formatter, you can use a string, symbol, or instance. For example, the following are identical:
+
+[source,ruby]
+----
+logger.formatter = "simple"
+logger.formatter = :simple
+logger.formatter = Cogger::Formatters::Simple.new
+----
 
 === Emojis
 
@@ -876,7 +930,7 @@ Tags allow you to tag your messages at both a global and local (i.e. per message
 logger = Cogger.new tags: %w[WEB]
 logger.info "Demo"
 
-# 🟢 [console] [WEB] Demo
+# 🟢 [console] ["WEB"] Demo
 ----
 
 You can use multiple tags as well:
@@ -886,7 +940,7 @@ You can use multiple tags as well:
 logger = Cogger.new tags: %w[WEB EXAMPLE]
 logger.info "Demo"
 
-# 🟢 [console] [WEB] [EXAMPLE] Demo
+# 🟢 [console] ["WEB"] ["EXAMPLE"] Demo
 ----
 
 You are not limited to string-based tags. Any object will work:
@@ -896,7 +950,7 @@ You are not limited to string-based tags. Any object will work:
 logger = Cogger.new tags: ["ONE", :two, 3, {four: "FOUR"}, proc { "FIVE" }]
 logger.info "Demo"
 
-# 🟢 [console] [ONE] [two] [3] [FIVE] [four=FOUR] Demo
+# 🟢 [console] ["ONE"] [:two] [3] ["FIVE"] [four="FOUR"] Demo
 ----
 
 With the above, we have string, symbol, integer, hash, and proc tags. With hashes, you'll always get a the key/value pair formatted as: `key=value`. Procs/lambdas allow you to lazy evaluate your tag at time of logging which provides a powerful way to acquire the current process ID, thread ID, and so forth.
@@ -908,7 +962,7 @@ In addition to global tags, you can use local tags per log message. Example:
 logger = Cogger.new
 logger.info "Demo", tags: ["ONE", :two, 3, {four: "FOUR"}, proc { "FIVE" }]
 
-# 🟢 [console] [ONE] [two] [3] [FIVE] [four=FOUR] Demo
+# 🟢 [console] ["ONE"] [:two] [3] ["FIVE"] [four="FOUR"] Demo
 ----
 
 You can also combine global and local tags:
@@ -918,16 +972,33 @@ You can also combine global and local tags:
 logger = Cogger.new tags: ["ONE", :two]
 logger.info "Demo", tags: [3, proc { "FOUR" }]
 
-# 🟢 [console] [ONE] [two] [3] [FOUR] Demo
+# 🟢 [console] ["ONE"] [:two] [3] ["FOUR"] Demo
 ----
 
+When using blocks, use a hash inside the block instead of supplying the tags before using the block. Example:
+
+[source,ruby]
+----
+logger = Cogger.new level: :debug
+
+# No
+logger.debug(tags: ["ONE", :TWO]) { "Demo" }
+🔎 [console] ["ONE"] [:TWO] Demo
+
+# Yes
+logger.debug { {tags: ["ONE", :TWO], message: "Demo"} }
+🔎 [console] ["ONE"] [:TWO] Demo
+----
+
+This ensures your tags and associated message are only evaluated when the correct log level is accepted. This is especially important when dealing with tags that need additional evaluation like procs because you'll improve performance when the debug log level, in this example, isn't set.
+
 As you can see, tags are highly versatile. That said, the following guidelines are worth consideration when using them:
 
-* Prefer uppercase tag names to make them visually stand out.
-* Prefer short names, ideally 1-4 characters since long tags defeat the purpose of brevity.
-* Prefer consistent tag names by using tags that are not synonymous or ambiguous.
-* Prefer using tags by feature rather than things like environments. Examples: API, DB, MAILER.
-* Prefer the JSON formatter for structured metadata instead of tags. Logging JSON formatted messages with tags will work but sticking with a traditional hash, instead of tags, will probably serve you better.
+* Prefer uppercase tags to make them visually stand out.
+* Prefer short tags, ideally 1-4 characters since long tags defeat the purpose of brevity.
+* Prefer consistent tags by using tags that are not synonymous or ambiguous.
+* Prefer feature tags instead of environment tags. Examples: API, DB, MAILER.
+* Prefer the JSON formatter for structured metadata instead of tags. Logging JSON formatted messages with tags will work but sticking with a traditional hash, instead of tags, will serve you better.
 * Avoid using `id`, `level`, `at`, and/or `message` as hash keys since those are reserved keys and will be rejected if supplied.
 
 === Filters

data/cogger.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "cogger"
-  spec.version = "2.3.0"
+  spec.version = "2.5.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/cogger"

data/lib/cogger/entry.rb

@@ -30,7 +30,7 @@ module Cogger
 
     def self.sanitize! content, payload
       body = if content.is_a? Hash
-               content.delete(:message).tap { payload.merge! content }
+               content.delete(:message).tap { payload.merge! content.except(:level, :at) }
              else
                content
              end

data/lib/cogger/formatters/color.rb

@@ -12,7 +12,7 @@ module Cogger
         @parser = parser
       end
 
-      def call(*input)
+      def call *input
         *, entry = input
         attributes = sanitize entry, :tagged
 

data/lib/cogger/formatters/crash.rb

@@ -17,7 +17,7 @@ module Cogger
         @parser = parser
       end
 
-      def call(*input)
+      def call *input
         *, entry = input
         attributes = sanitize entry, :tagged
         attributes[:backtrace] = %(  #{attributes[:backtrace].join "\n  "})

data/lib/cogger/formatters/json.rb

@@ -15,9 +15,10 @@ module Cogger
         @parser = parser
       end
 
-      def call(*input)
+      def call *input
         *, entry = input
-        attributes = sanitize(entry, :tagged_attributes).tap(&:compact!)
+        attributes = sanitize entry, :tagged_attributes
+        attributes.delete :message unless attributes[:message]
 
         parser.call(template, attributes).to_json << NEW_LINE
       end

data/lib/cogger/formatters/property.rb

@@ -14,9 +14,10 @@ module Cogger
         @parser = parser
       end
 
-      def call(*input)
+      def call *input
         *, entry = input
-        attributes = sanitize(entry, :tagged_attributes).tap(&:compact!)
+        attributes = sanitize entry, :tagged_attributes
+        attributes.delete :message unless attributes[:message]
 
         concat(attributes).chop! << NEW_LINE
       end

data/lib/cogger/formatters/sanitizers/escape.rb

@@ -35,7 +35,7 @@ module Cogger
 
         attr_reader :pattern
 
-        def dump(value) = value.to_s.gsub(pattern, &:dump)
+        def dump(value) = value ? value.to_s.gsub(pattern, &:dump) : value.inspect
       end
     end
   end

data/lib/cogger/formatters/simple.rb

@@ -11,7 +11,7 @@ module Cogger
         @template = template
       end
 
-      def call(*input)
+      def call *input
         *, entry = input
         attributes = sanitize entry, :tagged
 

data/lib/cogger/hub.rb

@@ -6,7 +6,6 @@ require "refinements/hash"
 
 module Cogger
   # Loads configuration and simultaneously sends messages to multiple streams.
-  # :reek:TooManyMethods
   class Hub
     extend Forwardable
 
@@ -27,23 +26,22 @@ module Cogger
       fatal!
       fatal?
       formatter
-      formatter=
       level
       level=
     ] => :primary
 
     delegate %i[id io tags mode age size suffix] => :configuration
 
-    def initialize(registry: Cogger, model: Configuration, **attributes)
+    def initialize registry: Cogger, model: Configuration, **attributes
       @registry = registry
-      @configuration = model[**find_formatter(attributes)]
+      @configuration = model[**resolve_formatter(attributes)]
       @primary = configuration.to_logger
       @streams = [@primary]
     end
 
     def add_stream **attributes
       attributes[:id] = configuration.id
-      streams.append configuration.with(**find_formatter(attributes)).to_logger
+      streams.append configuration.with(**resolve_formatter(attributes)).to_logger
       self
     end
 
@@ -59,16 +57,20 @@ module Cogger
 
     def any(message = nil, **, &) = log(__method__, message, **, &)
 
-    def abort(message = nil, **payload, &block)
+    def abort message = nil, **payload, &block
       error(message, **payload, &block) if message || !payload.empty? || block
       exit false
     end
 
-    def panic(message = nil, **payload, &block)
+    def panic message = nil, **payload, &block
       fatal(message, **payload, &block) if message || !payload.empty? || block
       exit false
     end
 
+    def formatter= value
+      primary.formatter = find_or_use_formatter value
+    end
+
     def add(level, message = nil, **, &)
       log(Logger::SEV_LABEL.fetch(level, "ANY").downcase, message, **, &)
     end
@@ -85,13 +87,19 @@ module Cogger
 
     attr_reader :registry, :configuration, :primary, :streams
 
-    # :reek:FeatureEnvy
-    def find_formatter attributes
-      attributes.transform_value! :formatter do |value|
-        next value unless value.is_a?(Symbol) || value.is_a?(String)
+    def resolve_formatter attributes
+      attributes.transform_value!(:formatter) { |value| find_or_use_formatter value }
+    end
 
-        formatter, template = registry.get_formatter value
-        template ? formatter.new(template) : formatter.new
+    def find_or_use_formatter value
+      case value
+        when String, Symbol
+          formatter, template = registry.get_formatter value
+          template ? formatter.new(template) : formatter.new
+        when Formatters::Abstract then value
+        else fail TypeError,
+                  "Invalid formatter. Must be a string, symbol, or " \
+                  "subclass of Cogger::Formatters::Abstract."
       end
     end
 
@@ -101,22 +109,23 @@ module Cogger
       crash message, error
     end
 
-    # rubocop:todo Metrics/MethodLength
     def dispatch(level, message, **payload, &)
-      entry = configuration.entry.for(
+      entry = build_entry(level, message, payload, &)
+      configuration.mutex.synchronize { streams.each { |logger| logger.public_send level, entry } }
+      true
+    end
+
+    def build_entry(level, message, payload, &)
+      configuration.entry.for(
         message,
         id: configuration.id,
         level:,
-        tags: configuration.entag(payload.delete(:tags)),
+        tags: configuration.entag(payload[:tags]),
         datetime_format: configuration.datetime_format,
-        **payload,
+        **payload.except(:level, :at, :tags),
         &
       )
-
-      configuration.mutex.synchronize { streams.each { |logger| logger.public_send level, entry } }
-      true
     end
-    # rubocop:enable Metrics/MethodLength
 
     def crash message, error
       configuration.with(id: :cogger, io: $stdout, formatter: Formatters::Crash.new)

data/lib/cogger/registry.rb

@@ -39,14 +39,14 @@ module Cogger
                                "%<duration>s %<ip>s %<path>s %<length>s %<params>s"
     end
 
-    def add_alias(key, *styles)
+    def add_alias key, *styles
       color.add_alias(key, *styles)
       self
     end
 
     def aliases = color.aliases
 
-    def add_emojis(**attributes)
+    def add_emojis **attributes
       emojis.merge! attributes.symbolize_keys!
       self
     end
@@ -57,7 +57,7 @@ module Cogger
 
     def emojis = @emojis ||= {}
 
-    def add_filters(*keys)
+    def add_filters *keys
       filters.merge(keys.map(&:to_sym))
       self
     end

data/lib/cogger/tag.rb

@@ -27,19 +27,23 @@ module Cogger
 
     def empty? = singles.empty? && pairs.empty?
 
-    def to_h = empty? ? Core::EMPTY_HASH : {tags: singles.to_a, **pairs}.tap(&:compress!)
+    def to_h
+      return Core::EMPTY_HASH if empty?
+
+      singles.empty? ? pairs : {tags: singles.to_a, **pairs}
+    end
 
     def to_s = empty? ? Core::EMPTY_STRING : "#{format_singles} #{format_pairs}".tap(&:strip!)
 
     private
 
     def format_singles
-      singles.map { |value| "[#{value}]" }
+      singles.map { |value| "[#{value.inspect}]" }
              .join " "
     end
 
     def format_pairs
-      pairs.map { |key, value| "[#{key}=#{value}]" }
+      pairs.map { |key, value| "[#{key}=#{value.inspect}]" }
            .join(" ")
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cogger
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -175,7 +175,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A customizable and feature rich logger.
 test_files: []