cogger 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c81fa9c3fdd3ce5ef1db012304946e95dd84c5c9087f5a82b6029f507f278c51
-  data.tar.gz: fb40393d822afe21906b559bca98bdf602875b2d78ca38a843a58ad34154d4f6
+  metadata.gz: d3dd4c51c4410b817ca889b3c06abf51fcab7e6e91f5746caed31d1bf45f3eb7
+  data.tar.gz: aa1f55995d710f2147071f4eaf9709e625c1fdd809d255860a3113ea6d742064
 SHA512:
-  metadata.gz: 1975f4568ca48b1d0f6851a66d255b43cc57c79849ab6edafc621f2705ffbe6ae116aad3cc76d024ab67cd5b17d431795fddda0de9083062876192176fe71d3a
-  data.tar.gz: 7f0c08112e4510dd7120e5e2c4ecd8cb98a3a35fa13087ebd6252e9367d81574a46e44365697637a3b4bc2e9de9c6823b897ff8ecc1d13d06aef002ec947dd55
+  metadata.gz: 61b318f30b68581323296d09159df52721d5a4e7554ada7d7d6ac09416016d26dee20b83630aa708ddc1b02e43966ab0e1e98b3fb08c2243a769a840a7853f04
+  data.tar.gz: 4731b4c644c505603098c41b0f0ca5a3aa81b0d81c175dfe37c914cdbb5b06fb57619f4f1f154007dfafb331263262646ae50338db9eff930084b78072697209

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
@@ -182,7 +229,7 @@ export LOG_LEVEL=fatal
 export LOG_LEVEL=unknown
 ----
 
-While downcase is preferred for each log level value, you can use upcased values as well. If the `LOG_LEVEL` environment variable is not set, `Cogger` will fall back to `"info"` unless overwritten during initialization. Example: `Cogger.new level: :debug`. Otherwise, an invalid log level will result in an `ArgumentError`.
+While lower case is preferred for each log level value, you can use upper case values as well. If the `LOG_LEVEL` environment variable is not set, `Cogger` will fall back to `"info"` unless overwritten during initialization. Example: `Cogger.new level: :debug`. Otherwise, an invalid log level will result in an `ArgumentError`.
 
 === Mutations
 
@@ -457,7 +504,7 @@ Additional keys as provided by your message hash and/or tags can be customized a
 Template keys, emojis, and elements do have a few restrictions:
 
 * Use the special `emoji` key to provide dynamic or specific emoji logging.
-* Use the special `tags` key to provide tagged logging. More information on tags can be found later in this document.
+* Use the special `tags` key to provide tagged logging. For more information, the _Tags_ section below.
 * Avoid supplying the same keys as the default keys. Example: `logger.info id: :bad, at: Time.now, level: :bogus`. This is because these keys will be ignored. In other words, you can't _override_ the default keys.
 * Avoid wrapping keys and/or emojis in elements because nesting isn't supported and can lead to strange output. Example: `<green>%<emoji:error>s %<id:dynamic>s</green>`.
 * Avoid wrapping elements within elements because nesting isn't supported and can lead to strange output. Example: `<dynamic><cyan>%<message>s</cyan></dynamic>`.
@@ -757,8 +804,7 @@ logger.info "Demo", tags: ["WEB", "PRIMARY", {service: :api, demo: true}]
 #   "level":"INFO",
 #   "at":"2023-12-10T18:44:32.723+00:00",
 #   "message":"Demo",
-#   "tags":["WEB",
-#   "PRIMARY"],
+#   "tags":["WEB", "PRIMARY"],
 #   "service":"api",
 #   "demo":true
 # }
@@ -877,7 +923,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:
@@ -887,7 +933,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:
@@ -897,7 +943,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.
@@ -909,7 +955,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:
@@ -919,16 +965,34 @@ 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
 
@@ -970,14 +1034,25 @@ You can add multiple log streams (outputs) by using:
 
 [source,ruby]
 ----
+require "stringio"
+
+buffer = StringIO.new
 logger = Cogger.new
+               .add_stream(io: buffer)
                .add_stream(io: "tmp/demo.log")
                .add_stream(io: nil)
 
 logger.info "Demo."
 ----
 
-The above would log the `"Demo."` message to `$stdout` -- the default stream -- to the `tmp/demo.log` file, and to `/dev/null`. All attributes used to construct your default logger apply to all additional streams unless customized further. This means any custom template/formatter can be applied to your streams. Example:
+The above would log `"Demo."` to:
+
+* To `$stdout` (the default stream which is your console).
+* To the StringIO `buffer` where you can use `buffer.string` to view content.
+* To the `tmp/demo.log` file where you can use `cat tmp/demo.log` to view content.
+* To `/dev/null` which immediately ignores all writes.
+
+All attributes used to construct your default logger apply to all additional streams unless customized further. This means any custom template/formatter can be applied to your streams. Example:
 
 [source,ruby]
 ----

data/cogger.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "cogger"
-  spec.version = "2.2.0"
+  spec.version = "2.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/cogger"
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "logger", "~> 1.7"
   spec.add_dependency "refinements", "~> 14.0"
   spec.add_dependency "tone", "~> 3.0"
-  spec.add_dependency "zeitwerk", "~> 2.7"
+  spec.add_dependency "zeitwerk", "~> 2.8"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
   spec.files = Dir["*.gemspec", "lib/**/*"]

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/json.rb

@@ -17,7 +17,8 @@ module Cogger
 
       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

@@ -16,7 +16,8 @@ module Cogger
 
       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/hub.rb

@@ -101,22 +101,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/tag.rb

@@ -5,35 +5,45 @@ require "refinements/hash"
 
 module Cogger
   # Models a tag which may consist of an array and/or hash.
-  Tag = Data.define :singles, :pairs do
+  Tag = Data.define :singles, :pairs, :exclusions do
     using Refinements::Hash
 
-    def self.for(*bag)
-      bag.each.with_object new do |item, tag|
+    def self.for(*bag) = new(**reduce(bag))
+
+    def self.reduce bag
+      bag.each.with_object({singles: [], pairs: {}}) do |item, all|
         value = item.is_a?(Proc) ? item.call : item
-        value.is_a?(Hash) ? tag.pairs.merge!(value) : tag.singles.append(value)
+        value.is_a?(Hash) ? all[:pairs].merge!(value) : all[:singles].append(value)
       end
     end
 
-    def initialize singles: [], pairs: {}
-      super
+    private_class_method :reduce
+
+    def initialize singles: [], pairs: {}, exclusions: %w[id level at message]
+      filtered_pairs = pairs.reject { |key, _| exclusions.include? key.to_s }
+
+      super singles:, pairs: filtered_pairs, exclusions:
     end
 
     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.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -97,14 +97,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
 email:
 - brooke@alchemists.io
 executables: []
@@ -175,7 +175,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A customizable and feature rich logger.
 test_files: []