cogger 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d529b8e4d8dd9fc3197a9e693e17cfcfc9cdadc4a5910f560a0bb50c5b0a5a02
-  data.tar.gz: 652d74a7778cc22c4219c8051b5dfd24691ed959bdb2108f678282ed279cec41
+  metadata.gz: 5f8bcb6e5db91a1e5216dba5864806aead97bd32a9d8fcda1d59a4b22beb079c
+  data.tar.gz: a21a6b830568388316d651204f93f9209ba4694b00e6760a677c81224d1e1a3f
 SHA512:
-  metadata.gz: 5cff486456ad103849b33360e4e660bb0837626e92a5debca5380977804ad877100878dbd2b8abc4e89840caa0e20445df24883ac79890feac8a8fc367ca7985
-  data.tar.gz: 841a17616a1aa5fb1ed1c7848d8b2f9237926993cf911910e12fe00b4d7c7b991a86bcc36ac404b976eadd006903a4e65dd94bef96113a296dcf82575ed88200
+  metadata.gz: ae3d73862e4cbb63a98223023e77cde2b58cf53a4a5b6a94b7e972215629f47a81b956d196c20384386b31d6833ed33689943e01fb4fb4b60957c98794cfc381
+  data.tar.gz: 6d73ec6858638127a168388b23821e77abf7f196a49af51e184ba496084f81295316c148d4d7417d1d3e4b700cc079bc66695b392accc62be47d7cd6e23f3b45

data/README.adoc

@@ -21,6 +21,7 @@ toc::[]
 * Provides customizable templates which leverage the native {format_link}.
 * Provides customizable formatters for simple, color, JSON, and/or custom output.
 * Provides multiple streams so you can log the same information to several outputs at once.
+* Provides global and individual log entry tagging.
 * Provides filtering of sensitive information.
 
 == Screenshots
@@ -128,6 +129,7 @@ When creating a new logger, you can configure behavior via the following attribu
 * `io`: The input/output stream. This can be `STDOUT/$stdout`, a file/path, or `nil`. Default: `$stdout`.
 * `level`: The severity level you want to log at. Can be `:debug`, `:info`, `:warn`, `:error`, `:fatal`, or `:unknown`. Default: `:info`.
 * `formatter`: The formatter to use for formatting your log output. Default: `Cogger::Formatter::Color`. See the _Formatters_ section for more info.
+* `tags`: Global tagging for _every_ log entry which _must_ be an array of objects you wish to use for tagging purposes.
 * `mode`: The binary mode which determines if your logs should be written in binary mode or not. Can be `true` or `false` and is identical to the `binmode` functionality found in the {logger_link} class. Default: `false`.
 * `age`: The rotation age of your log. This only applies when logging to a file. This is equivalent to the `shift_age` as found with the {logger_link} class. Default: `0`.
 * `size`: The rotation size of your log. This only applies when logging to a file. This is equivalent to the `shift_size` as found with the {logger_link} class. Default: `1,048,576` (i.e. 1 MB).
@@ -144,6 +146,8 @@ logger = Cogger.new
 logger = Cogger.new id: :demo,
                     io: "demo.log",
                     level: :debug,
+                    formatter: :json,
+                    tags: %w[DEMO DB],
                     mode: false,
                     age: 5,
                     size: 1_000,
@@ -174,7 +178,7 @@ Templates are used by all formatters and adhere to {format_link} as used by `Ker
 - Use of _reference by name_ is required which means `%<demo>s` is allowed but `%{demo}` is not. This is because _reference by name_ is required for regular expressions and/or {pattern_matching_link}.
 - Use of the `n$` flag is prohibited because this isn't compatible with the above.
 
-In addition to the above, the {format_link} is further enhanced with the use of _universal_ and _individual_ directives which are primarily used by the _color_ formatter but might prove useful for other formatters. Example:
+In addition to the above, the {format_link} is further enhanced with the use of _universal_ and _individual_ directives which are primarily used by the _color_ formatter but can prove useful for other formatters. Example:
 
 [source,ruby]
 ----
@@ -213,7 +217,7 @@ At this point, you might have gathered that there are specific keys you can use
 
 This also means if you pass in these same keys as a log event (example: `logger.info id: :bad, at: Time.now, severity: :bogus`) they will be ignored.
 
-The last key (or keys) is variable and customizable to your needs which is the log event message. Here a couple of examples to illustrate:
+The last key (or keys) is variable and customizable to your needs which is the log event message. The only special key is the `tags` key which is explained later. Here a couple of examples to illustrate:
 
 [source,ruby]
 ----
@@ -247,35 +251,38 @@ Cogger.emojis
 # }
 ----
 
-To add an emoji, use:
+The `:emoji` formatter is the default formatter which provides dynamic rendering of emojis based on severity level. Example:
 
 [source,ruby]
 ----
-Cogger.add_emoji(:tada, "🎉")
-      .add_emoji :favorite, "❇️"
+logger = Cogger.new
+logger.info "Demo"
+
+# 🟢 Demo
 ----
 
-By default, the `:emoji` formatter provides dynamic rendering of emojis based on severity level. Example:
+To add one or more emojis, you can chain messages together when registering them:
 
 [source,ruby]
 ----
-logger = Cogger.new formatter: :emoji
-logger.info "demo"
-
-# 🟢 demo
+Cogger.add_emoji(:tada, "🎉")
+      .add_emoji :favorite, "❇️"
 ----
 
-If you wanted to use a specific emoji, you could use the color formatter with a specific template:
+If you always want to use the _same_ emoji, you could use the emoji formatter with a specific template:
 
 [source,ruby]
 ----
-logger = Cogger.new formatter: Cogger::Formatters::Color.new("%<emoji:tada>s %<message:dynamic>s")
-logger.info "demo"
+logger = Cogger.new formatter: Cogger::Formatters::Emoji.new("%<emoji:tada>s %<message:dynamic>s")
 
-# 🎉 demo
+logger.info "Demo"
+logger.warn "Demo"
+
+# 🎉 Demo
+# 🎉 Demo
 ----
 
-Keep in mind that using a specific, non-dynamic, emoji will _always_ display no matter the current severity level.
+As you can see, using a specific and non-dynamic emoji will _always_ display regardless of the current severity level.
 
 === Aliases
 
@@ -300,7 +307,7 @@ Aliases are a powerful way to customize your colors and use short syntax in your
 "%<message:haze>"
 ----
 
-Check out the {tone_link} documentation for further examples.
+💡 These aliases are used by the color and emoji formatters but check out the {tone_link} documentation and _Formatters_ section below for further examples.
 
 === Formatters
 
@@ -320,8 +327,8 @@ Cogger.formatters
 #     "[%<id>s] [%<severity>s] [%<at>s] %<message>s"
 #   ],
 #    :emoji => [
-#     Cogger::Formatters::Color < Object,
-#     "%<emoji:dynamic>s% <message:dynamic>s"
+#     Cogger::Formatters::Emoji < Cogger::Formatters::Color,
+#     nil
 #   ],
 #     :json => [
 #     Cogger::Formatters::JSON < Object,
@@ -342,10 +349,10 @@ You can add a formatter by providing a key, class, and _optional_ template. If a
 
 [source,ruby]
 ----
-# Add
+# Registration
 Cogger.add_formatter :basic, Cogger::Formatters::Simple, "%<severity>s %<message>s"
 
-# Get
+# Usage
 Cogger.get_formatter :basic
 # [Cogger::Formatters::Simple, "%<severity>s %<message>s"]
 ----
@@ -375,18 +382,14 @@ logger = Cogger.new formatter: :rack
 
 ==== Color
 
-The color formatter is enabled by default and is the equivalent of initializing with either of the following:
+The color formatter allows you to have color coded logs and can be configured as follows:
 
 [source,ruby]
 ----
-logger = Cogger.new
-logger = Cogger.new formatter: Cogger::Formatters::Color.new
-logger = Cogger.new formatter: Cogger::Formatters::Color.new("%<message:dynamic>s")
+logger = Cogger.new formatter: :color
 ----
 
-All three of the above examples are identical so you can start to see how different formatters can be used and customized further. Please refer back to the _Templates_ section on how to customize this formatter with more sophisticated templates.
-
-In addition to template customization, you can customize your color aliases as well. Default colors are provided by {tone_link} which are _aliased_ by log level:
+Please refer back to the _Templates_ section on how to customize this formatter with more sophisticated templates. In addition to template customization, you can customize your color aliases as well. Default colors are provided by {tone_link} which are _aliased_ by log level:
 
 [source,ruby]
 ----
@@ -417,11 +420,56 @@ Once an alias is added, it can be immediately applied via the template of your f
 logger = Cogger.new formatter: Cogger::Formatters::Color.new("<mystery>%<message>s</mystery>")
 ----
 
-ℹ️ Much like the simple formatter, any leading or trailing whitespace is automatically after the template has been formatted.
+ℹ️ Much like the simple formatter, any leading or trailing whitespace is automatically removed after the template has been formatted.
+
+==== Emoji
+
+The emoji formatter is enabled by default and is the equivalent of initializing with either of the following:
+
+[source,ruby]
+----
+logger = Cogger.new
+logger = Cogger.new formatter: :emoji
+logger = Cogger.new formatter: Cogger::Formatters::Emoji.new("%<emoji:dynamic>s %<message:dynamic>s")
+----
+
+All of the above examples are identical so you can see how different formatters can be used and customized further. The default emojis are registered as follows:
+
+[source,ruby]
+----
+Cogger.emojis
+
+# {
+#   :debug => "🔎",
+#    :info => "🟢",
+#    :warn => "⚠️ ",
+#   :error => "🛑",
+#   :fatal => "🔥",
+#     :any => "⚫️"
+# }
+----
+
+This allows an emoji to be dynamically applied based on log severity. You can add or modify aliases as follows:
+
+[source,ruby]
+----
+Cogger.add_emoji :warn, "🟡"
+----
+
+Once an alias is added/updated, it can be immediately applied via the template of your formatter. Example:
+
+[source,ruby]
+----
+logger = Cogger.new
+logger.warn "Demo"
+# 🟡 Demo
+----
+
+ℹ️ Much like the simple and color formatters, any leading or trailing whitespace is automatically removed after the template has been formatted.
 
 ==== JSON
 
-This formatter is similar in behavior to the _simple_ formatter except the template allows you to order the layout of your keys only. All other information is ignored. To use:
+This formatter is similar in behavior to the _simple_ formatter except the template allows you to _order_ the layout of your keys. All other information is ignored. To use:
 
 [source,ruby]
 ----
@@ -440,18 +488,31 @@ logger.info verb: "GET", path: "/"
 
 Your template can be a full or partial match of keys. If no keys match what is defined in the template, then the original order of the keys will be used instead.
 
-==== Original
+==== Native
 
-Should you wish to use the original formatter as provided by original/native {logger_link}, you can get that behavior by specifying it as your preferred formatter. Example:
+Should you wish to use the native formatter as provided by original/native {logger_link}, it will work but not in the manner expected. Example:
 
 [source,ruby]
 ----
 require "logger"
 
 logger = Cogger.new formatter: Logger::Formatter.new
-logger.info "demo"
+logger.info "Demo"
+
+# I, [2023-10-15T14:32:55.061777 #72801]  INFO -- console: #<data Cogger::Entry id="console", severity=:info, at=2023-10-15 14:32:55.061734 -0600, message="Demo", tags=[], payload={}>
+----
+
+While the above doesn't cause an error, you only get a dump of the `Cogger::Entry` which is not what you want. To replicate native {logger_link} functionality, you can do use the simple formatter as follows to produce the rough equivalent:
+
+[source,ruby]
+----
+formatter = Cogger::Formatters::Simple.new(
+  "%<severity>s, [%<at>s]  %<severity>s -- %<id>s: %<message>s"
+)
+logger = Cogger.new(formatter:)
+logger.info "Demo"
 
-# I, [2023-04-11T19:35:51.175733 #84790]  INFO -- console: demo
+# INFO, [2023-10-15 15:07:13 -0600]  INFO -- console: Demo
 ----
 
 ==== Custom
@@ -468,7 +529,7 @@ class MyFormatter
     @sanitizer = sanitizer
   end
 
-  def call(*entry) = "#{format template, sanitizer.call(*entry)}\n"
+  def call(*input) = "#{format template, sanitizer.call(*input)}\n"
 
   private
 
@@ -476,7 +537,70 @@ class MyFormatter
 end
 ----
 
-There is no restriction on what dependency you might want to initialize your custom formatter with but -- as a bare minimum -- you'll want to provide a default template and inject the sanitizer which sanitizes the raw log entry into a hash you can interact with in your implementation. The only other requirement is that you must implement `#call` which takes a log entry which is an array of positional arguments (i.e. `severity`, `at`, `id`, `message`) and answers back a formatted string. If you need more examples you can either read the link:https://rubyapi.org/o/logger/formatter#method-i-call[Logger::Formatter] documentation or look at any of the formatters provided within this gem.
+There is no restriction on what dependency you might want to initialize your custom formatter with but -- as a bare minimum -- you'll want to provide a default template and inject the sanitizer which sanitizes the raw input into a `Cogger::Entry` object you can interact with in your implementation. The only other requirement is that you must implement `#call` which takes a log entry which is an array of positional arguments (i.e. `severity`, `at`, `id`, `entry`) and answers back a formatted string. If you need more examples you can look at any of the formatters provided within this gem.
+
+=== Tags
+
+Tags allow you to tag your messages at both a global and local (i.e. per message) level. For example, here's what tagging looks like when used globally:
+
+[source,ruby]
+----
+logger = Cogger.new tags: %w[WEB]
+logger.info "Demo"
+
+# 🟢 [WEB] Demo
+----
+
+Each tag is wrapped in brackets (i.e. `[]`) and you can use multiple tags:
+
+[source,ruby]
+----
+logger = Cogger.new tags: %w[WEB EXAMPLE]
+logger.info "Demo"
+
+# 🟢 [WEB] [EXAMPLE] Demo
+----
+
+You are not limited to string-based tags. Any object will work:
+
+
+[source,ruby]
+----
+logger = Cogger.new tags: ["ONE", :two, 3, {four: "FOUR"}, proc { "FIVE" }]
+logger.info "Demo"
+
+🟢 [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 thread ID, request ID, etc.
+
+In addition to global tags, you can use local tags per log message. Example:
+
+[source,ruby]
+----
+logger = Cogger.new
+logger.info "Demo", tags: ["ONE", :two, 3, {four: "FOUR"}, proc { "FIVE" }]
+
+🟢 [ONE] [two] [3] [FIVE] [four=FOUR] Demo
+----
+
+You can also combine global and local tags:
+
+[source,ruby]
+----
+logger = Cogger.new tags: ["ONE", :two]
+logger.info "Demo", tags: [3, proc { "FOUR" }]
+
+# 🟢 [ONE] [two] [3] [FOUR] Demo
+----
+
+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.
 
 === Filters
 
@@ -532,7 +656,7 @@ logger = Cogger.new
 logger.info "Demo."
 ----
 
-The above would log the `"Demo."` message to `$stdout` (i.e. the default stream), to the `tmp/demo.log` file, and to `/dev/null`. All of the attributes you would use to construct your default logger apply to any stream. This also means any custom template/formatter can be applied to your streams. Here's another example:
+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:
 
 [source,ruby]
 ----
@@ -542,6 +666,25 @@ logger.info "Demo."
 
 In this situation, you'd get colorized output to `$stdout` and JSON output to the `tmp/demo.log` file.
 
+There is a lot you can do with streams. For example, if you wanted to experiment with the same message formatted by multiple formatters, you could add a stream per format. Example:
+
+[source,ruby]
+----
+cogger = Cogger.new
+               .add_stream(formatter: :color)
+               .add_stream(formatter: :detail)
+               .add_stream(formatter: :json)
+               .add_stream(formatter: :simple)
+
+cogger.info "Demo"
+
+# 🟢 Demo
+# Demo
+# [console] [INFO] [2023-10-15 15:17:27 -0600] Demo
+# {"id":"console","severity":"INFO","at":"2023-10-15 15:17:27 -0600","message":"Demo"}
+# Demo
+----
+
 === Defaults
 
 Should you ever need quick access to the defaults, you can use:

data/cogger.gemspec

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

data/lib/cogger/configuration.rb

@@ -9,20 +9,24 @@ module Cogger
     :io,
     :level,
     :formatter,
+    :tags,
     :mode,
     :age,
     :size,
     :suffix,
+    :entry,
     :logger
   ) do
     def initialize id: Program.call,
                    io: $stdout,
                    level: Logger.const_get(ENV.fetch("LOG_LEVEL", "INFO")),
-                   formatter: Formatters::Color.new,
+                   formatter: Formatters::Emoji.new,
+                   tags: [],
                    mode: false,
                    age: 0,
                    size: 1_048_576,
                    suffix: "%Y-%m-%d",
+                   entry: Entry,
                    logger: Logger
       super
     end
@@ -40,9 +44,9 @@ module Cogger
 
     def inspect
       "#<#{self.class} @id=#{id}, @io=#{io.class}, @level=#{level}, " \
-      "@formatter=#{formatter.class}, " \
+      "@formatter=#{formatter.class}, @tags=#{tags.inspect}, " \
       "@mode=#{mode}, @age=#{age}, @size=#{size}, @suffix=#{suffix.inspect}, " \
-      "@logger=#{logger}>"
+      "@entry=#{entry}, @logger=#{logger}>"
     end
   end
 end

data/lib/cogger/entry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Cogger
+  # Defines a log entry which can be formatted for output.
+  Entry = Data.define :id, :severity, :at, :message, :tags, :payload do
+    def self.for(message = nil, **payload)
+      new id: (payload.delete(:id) || Program.call),
+          severity: (payload.delete(:severity) || "INFO").upcase,
+          message: (block_given? ? yield : message),
+          tags: Array(payload.delete(:tags)),
+          payload:
+    end
+
+    def self.for_crash message, error, id:
+      new id:,
+          severity: "FATAL",
+          message:,
+          payload: {
+            error_message: error.message,
+            error_class: error.class,
+            backtrace: error.backtrace
+          }
+    end
+
+    def initialize id: Program.call,
+                   severity: "INFO",
+                   at: Time.now,
+                   message: nil,
+                   tags: [],
+                   payload: {}
+      super
+    end
+
+    def attributes = {id:, severity:, at:, message:, **payload}
+
+    def tagged_attributes tagger: Tag
+      computed_tags = tagger.for(*tags)
+
+      return attributes if computed_tags.empty?
+
+      {id:, severity:, at:, message:, tags: computed_tags.to_a, **payload}
+    end
+
+    def tagged tagger: Tag
+      attributes.tap do |pairs|
+        computed_tags = tagger.for(*tags)
+        pairs[:message] = "#{computed_tags} #{pairs[:message]}" unless computed_tags.empty?
+      end
+    end
+  end
+end

data/lib/cogger/formatters/color.rb

@@ -11,8 +11,8 @@ module Cogger
         @processor = processor
       end
 
-      def call(*entry)
-        updated_template, attributes = processor.call(template, *entry)
+      def call(*input)
+        updated_template, attributes = processor.call(template, *input)
         "#{format(updated_template, **attributes).tap(&:strip!)}\n"
       end
 

data/lib/cogger/formatters/crash.rb

@@ -16,8 +16,8 @@ module Cogger
         @processor = processor
       end
 
-      def call(*entry)
-        updated_template, attributes = processor.call(template, *entry)
+      def call(*input)
+        updated_template, attributes = processor.call(template, *input)
         attributes[:backtrace] = %(  #{attributes[:backtrace].join "\n  "})
         "#{format(updated_template, **attributes)}\n"
       end

data/lib/cogger/formatters/emoji.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Cogger
+  module Formatters
+    # Formats by emoji and color.
+    class Emoji < Color
+      TEMPLATE = "%<emoji:dynamic>s %<message:dynamic>s"
+
+      def initialize(template = TEMPLATE, ...)
+        super
+      end
+    end
+  end
+end

data/lib/cogger/formatters/json.rb

@@ -10,21 +10,19 @@ module Cogger
 
       def initialize template = TEMPLATE,
                      parser: Parsers::Individual.new,
-                     sanitizer: Kit::Sanitizer.new
-        @template = template
-        @parser = parser
+                     sanitizer: Kit::Sanitizer
+        @positions = parser.call(template).last.keys
         @sanitizer = sanitizer
       end
 
-      def call(*entry)
-        positions = parser.call(template).last.keys
-        attributes = sanitizer.call(*entry).tap(&:compact!)
+      def call(*input)
+        attributes = sanitizer.call(*input).tagged_attributes.tap(&:compact!)
         "#{attributes.slice(*positions).merge!(attributes.except(*positions)).to_json}\n"
       end
 
       private
 
-      attr_reader :template, :parser, :sanitizer
+      attr_reader :positions, :sanitizer
     end
   end
 end

data/lib/cogger/formatters/kit/sanitizer.rb

@@ -3,34 +3,13 @@
 module Cogger
   module Formatters
     module Kit
-      # Transforms a positional log entry into a hash entry for template parsing and formatting.
-      class Sanitizer
-        def initialize filters: Cogger.filters
-          @filters = filters
-        end
+      # Ensures log entry is filtered of sensitive data.
+      Sanitizer = lambda do |*input, filters: Cogger.filters|
+        *, entry = input
+        payload = entry.payload
 
-        # :reek:FeatureEnvy
-        def call(*entry)
-          severity, at, id, message = entry
-
-          attributes = if message.is_a? Hash
-                         {id:, severity:, at:, message: nil, **message.except(:id, :severity, :at)}
-                       else
-                         {id:, severity:, at:, message:}
-                       end
-
-          filter attributes
-        end
-
-        private
-
-        attr_reader :filters
-
-        # :reek:FeatureEnvy
-        def filter attributes
-          filters.each { |key| attributes[key] = "[FILTERED]" if attributes.key? key }
-          attributes
-        end
+        filters.each { |key| payload[key] = "[FILTERED]" if payload.key? key }
+        entry
       end
     end
   end

data/lib/cogger/formatters/parsers/individual.rb

@@ -45,7 +45,7 @@ module Cogger
         # :reek:FeatureEnvy
         # :reek:TooManyStatements
         def sanitize_and_extract template, attributes
-          template.dup.gsub pattern do
+          template.gsub pattern do
             captures = Regexp.last_match.named_captures
             attributes[captures["key"].to_sym] = captures["directive"]
 

data/lib/cogger/formatters/processors/color.rb

@@ -8,15 +8,15 @@ module Cogger
       # Processes emojis and colors.
       class Color
         def initialize parser: Parsers::Dynamic.new,
-                       kit: {sanitizer: Kit::Sanitizer.new, colorizer: Kit::Colorizer},
+                       kit: {sanitizer: Kit::Sanitizer, colorizer: Kit::Colorizer},
                        registry: Cogger
           @parser = parser
           @kit = kit
           @registry = registry
         end
 
-        def call(template, *entry)
-          attributes = sanitizer.call(*entry)
+        def call(template, *input)
+          attributes = sanitizer.call(*input).tagged
 
           case parser.call template
             in [String => body, String => style] then universal body, style, **attributes

data/lib/cogger/formatters/simple.rb

@@ -6,12 +6,12 @@ module Cogger
     class Simple
       TEMPLATE = "%<message>s"
 
-      def initialize template = TEMPLATE, sanitizer: Kit::Sanitizer.new
+      def initialize template = TEMPLATE, sanitizer: Kit::Sanitizer
         @template = template
         @sanitizer = sanitizer
       end
 
-      def call(*entry) = "#{format(template, sanitizer.call(*entry)).tap(&:strip!)}\n"
+      def call(*input) = "#{format(template, sanitizer.call(*input).tagged).tap(&:strip!)}\n"
 
       private
 

data/lib/cogger/hub.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "forwardable"
 require "logger"
 require "refinements/hashes"
 require "refinements/loggers"
@@ -8,12 +9,33 @@ module Cogger
   # Loads configuration and simultaneously sends messages to multiple streams.
   # :reek:TooManyInstanceVariables
   class Hub
+    extend Forwardable
+
     using Refinements::Loggers
     using Refinements::Hashes
 
-    def initialize(registry: Cogger, model: Configuration.new, **attributes)
+    delegate %i[
+      close
+      reopen
+      debug!
+      debug?
+      info!
+      info?
+      warn!
+      warn?
+      error!
+      error?
+      fatal!
+      fatal?
+      formatter
+      formatter=
+      level
+      level=
+    ] => :primary
+
+    def initialize(registry: Cogger, model: Configuration, **attributes)
       @registry = registry
-      @configuration = model.with(**find_formatter(attributes))
+      @configuration = model[**find_formatter(attributes)]
       @primary = configuration.to_logger
       @streams = [@primary]
       @mutex = Mutex.new
@@ -25,19 +47,19 @@ module Cogger
       self
     end
 
-    def debug(...) = log(__method__, ...)
+    def debug(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def info(...) = log(__method__, ...)
+    def info(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def warn(...) = log(__method__, ...)
+    def warn(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def error(...) = log(__method__, ...)
+    def error(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def fatal(...) = log(__method__, ...)
+    def fatal(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def unknown(...) = log(__method__, ...)
+    def any(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    alias any unknown
+    alias unknown any
 
     def reread = primary.reread
 
@@ -60,17 +82,30 @@ module Cogger
       )
     end
 
-    # :reek:TooManyStatements
-    def log(severity, message = nil, &)
-      mutex.synchronize { streams.each { |logger| logger.public_send(severity, message, &) } }
-      true
+    def log(severity, message, **payload, &)
+      dispatch(severity, message, **payload, &)
     rescue StandardError => error
-      configuration.with(id: "Cogger", io: $stdout, formatter: Formatters::Crash.new)
+      crash message, error
+    end
+
+    def dispatch(severity, message, **payload, &)
+      entry = configuration.entry.for(
+        message,
+        id: configuration.id,
+        severity:,
+        tags: configuration.tags + Array(payload.delete(:tags)),
+        **payload,
+        &
+      )
+
+      mutex.synchronize { streams.each { |logger| logger.public_send severity, entry } }
+      true
+    end
+
+    def crash message, error
+      configuration.with(id: :cogger, io: $stdout, formatter: Formatters::Crash.new)
                    .to_logger
-                   .fatal message:,
-                          error_message: error.message,
-                          error_class: error.class,
-                          backtrace: error.backtrace
+                   .fatal configuration.entry.for_crash(message, error, id: configuration.id)
       true
     end
   end

data/lib/cogger/registry.rb

@@ -27,11 +27,7 @@ module Cogger
                   Cogger::Formatters::Simple,
                   "[%<id>s] [%<severity>s] [%<at>s] %<message>s"
                 )
-                .add_formatter(
-                  :emoji,
-                  Cogger::Formatters::Color,
-                  "%<emoji:dynamic>s %<message:dynamic>s"
-                )
+                .add_formatter(:emoji, Cogger::Formatters::Emoji)
                 .add_formatter(:json, Cogger::Formatters::JSON)
                 .add_formatter(:simple, Cogger::Formatters::Simple)
                 .add_formatter :rack,

data/lib/cogger/tag.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Cogger
+  # Models a tag which may consist of an array and/or hash.
+  Tag = Data.define :singles, :pairs do
+    def self.for(*bag)
+      bag.each.with_object new do |item, tag|
+        value = item.is_a?(Proc) ? item.call : item
+        value.is_a?(Hash) ? tag.pairs.merge!(value) : tag.singles.append(value)
+      end
+    end
+
+    def initialize singles: [], pairs: {}
+      super
+    end
+
+    def empty? = singles.empty? && pairs.empty?
+
+    def to_a
+      return [] if empty?
+
+      pairs.map { |key, value| "#{key}=#{value}" }
+           .prepend(*singles.map(&:to_s))
+    end
+
+    def to_s = empty? ? "" : "#{format_singles} #{format_pairs}".tap(&:strip!)
+
+    private
+
+    def format_singles
+      singles.map { |value| "[#{value}]" }
+             .join " "
+    end
+
+    def format_pairs
+      pairs.map { |key, value| "[#{key}=#{value}]" }
+           .join(" ")
+    end
+  end
+end

data/lib/cogger.rb

@@ -15,10 +15,5 @@ module Cogger
 
   def self.loader(registry = Zeitwerk::Registry) = registry.loader_for __FILE__
 
-  def self.init(...)
-    warn "#{self}##{__method__} is deprecated, use `.new` instead.", category: :deprecated
-    Client.new(...)
-  end
-
   def self.new(...) = Hub.new(...)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cogger
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-10-01 00:00:00.000000000 Z
+date: 2023-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -92,10 +92,11 @@ files:
 - README.adoc
 - cogger.gemspec
 - lib/cogger.rb
-- lib/cogger/client.rb
 - lib/cogger/configuration.rb
+- lib/cogger/entry.rb
 - lib/cogger/formatters/color.rb
 - lib/cogger/formatters/crash.rb
+- lib/cogger/formatters/emoji.rb
 - lib/cogger/formatters/json.rb
 - lib/cogger/formatters/kit/colorizer.rb
 - lib/cogger/formatters/kit/sanitizer.rb
@@ -107,6 +108,7 @@ files:
 - lib/cogger/hub.rb
 - lib/cogger/program.rb
 - lib/cogger/registry.rb
+- lib/cogger/tag.rb
 homepage: https://alchemists.io/projects/cogger
 licenses:
 - Hippocratic-2.1

data/lib/cogger/client.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-require "forwardable"
-require "logger"
-require "refinements/loggers"
-require "tone"
-
-module Cogger
-  # Provides the primary client for colorized logging.
-  class Client
-    extend Forwardable
-
-    using Refinements::Loggers
-
-    delegate %i[formatter level progname debug info warn error fatal unknown] => :logger
-
-    # :reek:TooManyStatements
-    def initialize logger = Logger.new($stdout), color: Cogger.color, **attributes
-      warn "#{self.class}##{__method__} is deprecated, use `Cogger.new` instead.",
-           category: :deprecated
-
-      @logger = logger
-      @color = color
-      @attributes = attributes
-
-      configure
-      yield logger if block_given?
-    end
-
-    def any(...) = logger.unknown(...)
-
-    def reread = logger.reread
-
-    private
-
-    attr_reader :logger, :color, :attributes
-
-    # rubocop:disable Metrics/AbcSize
-    def configure
-      logger.datetime_format = attributes.fetch :datetime_format, logger.datetime_format
-      logger.level = attributes.fetch :level, default_level
-      logger.progname = attributes.fetch :progname, logger.progname
-      logger.formatter = attributes.fetch :formatter, default_formatter
-    end
-    # rubocop:enable Metrics/AbcSize
-
-    def default_level = logger.class.const_get ENV.fetch("LOG_LEVEL", "INFO")
-
-    def default_formatter
-      -> severity, _at, _name, message { "#{color[message, severity.downcase]}\n" }
-    end
-  end
-end