cogger 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 051cbeb63381e6680f86fd1b73a1e6648d6ecc1befc37824d0425cbb12d0fb63
-  data.tar.gz: 8772b28a29157d2f023096eaf40ba28c252888e3430e5ddc673ade49888b7da2
+  metadata.gz: d3dd4c51c4410b817ca889b3c06abf51fcab7e6e91f5746caed31d1bf45f3eb7
+  data.tar.gz: aa1f55995d710f2147071f4eaf9709e625c1fdd809d255860a3113ea6d742064
 SHA512:
-  metadata.gz: 4b290ebea636e3744c68dd07c1cd37bd310fa3c99600a8b7a32ed93dcdcc651559ff718fcfe43446c7bad91772ba25eb4bb60bfe0ff9f2c6f85d8158dc58c9c1
-  data.tar.gz: 163afc50ba9118ab76f2ff75f351b4d2b60992b29f317bbfab218e310ada42890fec1e5cfed6993bde0421d67126b65038adbe7b81791f062c07ae82e32c3143
+  metadata.gz: 61b318f30b68581323296d09159df52721d5a4e7554ada7d7d6ac09416016d26dee20b83630aa708ddc1b02e43966ab0e1e98b3fb08c2243a769a840a7853f04
+  data.tar.gz: 4731b4c644c505603098c41b0f0ca5a3aa81b0d81c175dfe37c914cdbb5b06fb57619f4f1f154007dfafb331263262646ae50338db9eff930084b78072697209

checksums.yaml.gz.sig

@@ -1 +1,2 @@
-;&S4L���^y ,Ҫ��R�GQ���pQ�7l�hG��t�Ie
�	P�'|��*p_��:��.�#ZV4�9O��s�_����E���6y�  }g���T���T�`Q�8f+��[
+���v������I+„"�:o���lW"ݺ�:C[�eI����T��aUN�,ɞ�jp�C�A�"Z�E��	��[̠x�}��9��غȍ���3?�V�V"����Y�_ҊBx��^aL��u�/O�j6\���п*�I���j�kԲ���/J���.!���q1���ĺ*����kh���O�����dt�������/D,��
+�`U�� \LaW��O�[�9BJ

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
@@ -876,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:
@@ -886,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:
@@ -896,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.
@@ -908,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:
@@ -918,16 +965,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.4.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/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

@@ -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.4.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: []