cogger 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d529b8e4d8dd9fc3197a9e693e17cfcfc9cdadc4a5910f560a0bb50c5b0a5a02
-  data.tar.gz: 652d74a7778cc22c4219c8051b5dfd24691ed959bdb2108f678282ed279cec41
+  metadata.gz: 57f5049812c9af7fd2f1f936ac37c85562fad47517f6b3d2ccd2e34e2d1ee691
+  data.tar.gz: 2ecc0b1bd9e9cc37c85ee9f8db19c936b47d65a71b4723631f96debcdbd4b23e
 SHA512:
-  metadata.gz: 5cff486456ad103849b33360e4e660bb0837626e92a5debca5380977804ad877100878dbd2b8abc4e89840caa0e20445df24883ac79890feac8a8fc367ca7985
-  data.tar.gz: 841a17616a1aa5fb1ed1c7848d8b2f9237926993cf911910e12fe00b4d7c7b991a86bcc36ac404b976eadd006903a4e65dd94bef96113a296dcf82575ed88200
+  metadata.gz: 4318c120bb3182a8a0740025b1528a6643b876b3d0ff71e3b875304484b4da5df44af044d474e2d93cacd1807487560063ac5e4d8499ef514a42c1c5644573a6
+  data.tar.gz: 7018412ed2a90da5e9fc31931e203d76767f405ff1559644570382891ccdb412c19c30eb2bb86f56f52be4e624f2938decb8f00c5fbf50feaf11735cf2e9f8bc

data/README.adoc

@@ -21,33 +21,34 @@ 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
 
 *Emoji*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/emoji.png[Emoji,width=204,height=251]
+image::https://alchemists.io/images/projects/cogger/screenshots/emoji.png[Emoji,width=234,height=293]
 
 *Color*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/color.png[Color,width=181,height=247]
+image::https://alchemists.io/images/projects/cogger/screenshots/color.png[Color,width=202,height=288]
 
 *Simple*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/simple.png[Simple,width=274,height=253]
+image::https://alchemists.io/images/projects/cogger/screenshots/simple.png[Simple,width=288,height=253]
 
 *Detail*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/detail.png[Detail,width=476,height=256]
+image::https://alchemists.io/images/projects/cogger/screenshots/detail.png[Detail,width=611,height=284]
 
 *JSON*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/json.png[JSON,width=929,height=256]
+image::https://alchemists.io/images/projects/cogger/screenshots/json.png[JSON,width=962,height=297]
 
 *Rack*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/rack.png[Rack,width=656,height=252]
+image::https://alchemists.io/images/projects/cogger/screenshots/rack.png[Rack,width=883,height=282]
 
 == Requirements
 
@@ -92,7 +93,7 @@ All interaction is provided by `Cogger` which can be used as follows:
 [source,ruby]
 ----
 logger = Cogger.new
-logger.info "demo"   # "demo"
+logger.info "Demo"  # "Demo"
 ----
 
 If you set your logging level to `debug`, you can walk through each level:
@@ -102,22 +103,24 @@ If you set your logging level to `debug`, you can walk through each level:
 logger = Cogger.new level: :debug
 
 # Without blocks.
-logger.debug "demo"        # "demo"
-logger.info "demo"         # "demo"
-logger.warn "demo"         # "demo"
-logger.error "demo"        # "demo"
-logger.fatal "demo"        # "demo"
-logger.unknown "demo"      # "demo"
-logger.any "demo"          # "demo"
+logger.debug "Demo"                  # "🔎 Demo"
+logger.info "Demo"                   # "🟢 Demo"
+logger.warn "Demo"                   # "⚠️ Demo"
+logger.error "Demo"                  # "🛑 Demo"
+logger.fatal "Demo"                  # "🔥 Demo"
+logger.unknown "Demo"                # "⚫️ Demo"
+logger.any "Demo"                    # "⚫️ Demo"
+logger.add Logger::INFO, "Demo"      # "🟢 Demo"
 
 # With blocks.
-logger.debug { "demo" }    # "demo"
-logger.info { "demo" }     # "demo"
-logger.warn { "demo" }     # "demo"
-logger.error { "demo" }    # "demo"
-logger.fatal { "demo" }    # "demo"
-logger.unknown { "demo" }  # "demo"
-logger.any { "demo" }      # "demo"
+logger.debug { "Demo" }              # "🔎 Demo"
+logger.info { "Demo" }               # "🟢 Demo"
+logger.warn { "Demo" }               # "⚠️ Demo"
+logger.error { "Demo" }              # "🛑 Demo"
+logger.fatal { "Demo" }              # "🔥 Demo"
+logger.unknown { "Demo" }            # "⚫️ Demo"
+logger.any { "Demo" }                # "⚫️ Demo"
+logger.add(Logger::INFO) { "Demo" }  # "🟢 Demo"
 ----
 
 === Initialization
@@ -128,6 +131,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,12 +148,80 @@ 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,
                     suffix: "%Y"
 ----
 
+=== Inspection
+
+Each instance can be inspected via the `#inspect` message:
+
+[source,ruby]
+----
+logger = Cogger.new
+logger.inspect
+
+# "#<Cogger::Hub @id=console,
+#                @io=IO,
+#                @level=1,
+#                @formatter=Cogger::Formatters::Emoji,
+#                @tags=[],
+#                @mode=false,
+#                @age=0,
+#                @size=1048576,
+#                @suffix=\"%Y-%m-%d\",
+#                @entry=Cogger::Entry,
+#                @logger=Logger>"
+----
+
+You can also look at individual attributes:
+
+[source,ruby]
+----
+logger = Cogger.new
+
+logger.id      # "console"
+logger.io      # #<IO:<STDOUT>>
+logger.tags    # []
+logger.mode    # false
+logger.age     # 0
+logger.size    # 1048576
+logger.suffix  # "%Y-%m-%d"
+
+logger.level      # 1
+logger.formatter  # Cogger::Formatters::Emoji
+logger.debug?     # false
+logger.info?      # true
+logger.warn?      # true
+logger.error?     # true
+logger.fatal?     # true
+----
+
+=== Mutations
+
+Each instance can be mutated using the following messages:
+
+[source,ruby]
+----
+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
+----
+
+Please see the {logger_link} documentation for more information.
+
 === Environment
 
 The default log level is `INFO` but can be customized via your environment. For instance, you could
@@ -174,7 +246,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 +285,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 +319,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 +375,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 +395,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 +417,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"]
 ----
@@ -354,8 +429,10 @@ Symbols or strings can be used interchangeably when adding/getting formatters. A
 
 [source,ruby]
 ----
-Cogger::Formatters::Simple::TEMPLATE
-# "%<message>s"
+Cogger::Formatters::Color::TEMPLATE   # "%<message:dynamic>s"
+Cogger::Formatters::Emoji::TEMPLATE   # "%<emoji:dynamic>s %<message:dynamic>s"
+Cogger::Formatters::JSON::TEMPLATE    # nil
+Cogger::Formatters::Simple::TEMPLATE  # "%<message>s"
 ----
 
 💡 When you find yourself customizing any of the default formatters, you can reduce typing by adding your custom configuration to the registry and then referring to it via it's associated key when initializing a new logger.
@@ -375,18 +452,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,21 +490,71 @@ 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 template information is ignored, only the order of your template keys matters. Example:
+
+*Default Order*
 
 [source,ruby]
 ----
-# Default order
 logger = Cogger.new formatter: :json
 logger.info verb: "GET", path: "/"
 
 # {"id":"console","severity":"INFO","at":"2023-04-10 09:03:55 -0600","verb":"GET","path":"/"}
+----
 
-# Custom order
+*Custom Order*
+
+[source,ruby]
+----
 logger = Cogger.new formatter: Cogger::Formatters::JSON.new("%<severity>s %<verb>s")
 logger.info verb: "GET", path: "/"
 
@@ -440,18 +563,65 @@ 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
+You can always supply a message as your first argument -- or specify it by using the `:message` key -- but is removed if not supplied which is why the above doesn't print a message in the output. To illustrate, the following are equivalent:
+
+[source,ruby]
+----
+logger = Cogger.new formatter: json
+
+logger.info "Demo"
+# {"id":"console","severity":"INFO","at":"2023-10-18 19:38:55 -0600","message":"Demo"}
+
+logger.info messsage: "Demo"
+{"id":"console","severity":"INFO","at":"2023-10-18 19:39:19 -0600","messsage":"Demo"}
+----
+
+When tags are provided, the `:tags` key will appear in the output depending on whether you are using _single tags_. If hash tags are used, they'll show up as additional attributes in the outout. Here's an example where a mix of single and hash keys are used:
+
+[source,ruby]
+----
+logger = Cogger.new formatter: :json
+
+logger.info "Demo", tags: ["WEB", "PRIMARY", {service: :api, demo: true}]
+
+# {
+#   "id":"console",
+#   "severity":"INFO",
+#   "at":"2023-10-18 19:47:11 -0600",
+#   "message":"Demo",
+#   "tags":["WEB","PRIMARY"],
+#   "service":"api",
+#   "demo":true
+# }
+----
+
+Notice, with the above, that the single tags of `WEB` and `PRIMARY` show up in the `tags` array while the `:service` and `:demo` keys show up at the top level of the hash. Since the `:tags`, `:service`, `:demo` keys are normal keys, like any key in your JSON output, this means you can use a custom template to arrange the order of these keys if you don't like the default.
+
+==== 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 you might expect. 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={}>
+----
 
-# I, [2023-04-11T19:35:51.175733 #84790]  INFO -- console: demo
+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"
+
+# INFO, [2023-10-15 15:07:13 -0600]  INFO -- console: Demo
 ----
 
 ==== Custom
@@ -468,7 +638,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,47 +646,105 @@ 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.
 
-=== Filters
+=== Tags
 
-Filters allow you to mask sensitive information you don't want showing up in your logs. Here are the defaults:
+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]
 ----
-Cogger.filters
+logger = Cogger.new tags: %w[WEB]
+logger.info "Demo"
 
-# [
-#   :_csrf,
-#   :password,
-#   :password_confirmation
-# ]
+# 🟢 [WEB] Demo
 ----
 
-To add additional filters, use:
+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 process ID, thread ID, and so forth.
+
+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
+
+Filters allow you to mask sensitive information you don't want showing up in your logs. The default is an empty set:
+
+[source,ruby]
+----
+Cogger.filters  # #<Set: {}>
+----
+
+To add filters, use:
 
 [source,ruby]
 ----
 Cogger.add_filter(:login)
       .add_filter "email"
 
-# [
-#   :_csrf,
-#   :password,
-#   :password_confirmation,
-#   :login,
-#   :email
-# ]
+Cogger.filters  # #<Set: {:login, :email}>
 ----
 
 Symbols and strings can be used interchangeably but are stored as symbols since symbols are used when filtering log entries. Once your filters are in place, you can immediately see their effects:
 
 [source,ruby]
 ----
+Cogger.add_filter :password
 logger = Cogger.new formatter: :json
 logger.info login: "jayne", password: "secret"
 
-# {"id":"console","severity":"INFO","at":"2023-04-09 17:33:00 -0600","login":"[FILTERED]","password":"[FILTERED]"}
+# {
+#   "id":"console",
+#   "severity":"INFO",
+#   "at":"2023-10-18 19:21:40 -0600",
+#   "login":"jayne",
+#   "password":"[FILTERED]"
+# }
 ----
 
 === Streams
@@ -532,7 +760,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 +770,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]
+----
+logger = Cogger.new
+               .add_stream(formatter: :color)
+               .add_stream(formatter: :detail)
+               .add_stream(formatter: :json)
+               .add_stream(formatter: :simple)
+
+logger.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.13.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/cogger"
@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = "~> 3.2"
+  spec.add_dependency "core", "~> 0.1"
   spec.add_dependency "refinements", "~> 11.0"
   spec.add_dependency "tone", "~> 0.3"
   spec.add_dependency "zeitwerk", "~> 2.6"

data/lib/cogger/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "core"
 require "logger"
 
 module Cogger
@@ -9,20 +10,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: Core::EMPTY_ARRAY,
                    mode: false,
                    age: 0,
                    size: 1_048_576,
                    suffix: "%Y-%m-%d",
+                   entry: Entry,
                    logger: Logger
       super
     end
@@ -40,9 +45,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,53 @@
+# frozen_string_literal: true
+
+require "core"
+
+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: Core::EMPTY_HASH
+      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:, **computed_tags.to_h, **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

@@ -1,30 +1,32 @@
 # frozen_string_literal: true
 
+require "core"
 require "json"
 
 module Cogger
   module Formatters
     # Formats as JSON output.
     class JSON
-      TEMPLATE = "%<id>s %<severity>s %<at>s %<message>s"
+      TEMPLATE = nil
 
       def initialize template = TEMPLATE,
                      parser: Parsers::Individual.new,
-                     sanitizer: Kit::Sanitizer.new
-        @template = template
-        @parser = parser
+                     sanitizer: Kit::Sanitizer
+        @positions = template ? parser.call(template).last.keys : Core::EMPTY_ARRAY
         @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!)
+
+        return "#{attributes.to_json}\n" if positions.empty?
+
         "#{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/parsers/universal.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "core"
+
 module Cogger
   module Formatters
     module Parsers
@@ -32,7 +34,7 @@ module Cogger
         def call template
           return template unless template.match? pattern
 
-          [template.gsub(pattern, ""), template.match(pattern)[key]]
+          [template.gsub(pattern, Core::EMPTY_STRING), template.match(pattern)[key]]
         end
 
         private

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,35 @@ 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
+
+    delegate %i[id io tags mode age size suffix] => :configuration
+
+    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 +49,23 @@ module Cogger
       self
     end
 
-    def debug(...) = log(__method__, ...)
+    def debug(message = nil, **payload, &) = log(__method__, message, **payload, &)
+
+    def info(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def info(...) = log(__method__, ...)
+    def warn(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def warn(...) = log(__method__, ...)
+    def error(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def error(...) = log(__method__, ...)
+    def fatal(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def fatal(...) = log(__method__, ...)
+    def any(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
-    def unknown(...) = log(__method__, ...)
+    def add(severity, message = nil, **payload, &)
+      log(Logger::SEV_LABEL.fetch(severity, "ANY").downcase, message, **payload, &)
+    end
 
-    alias any unknown
+    alias unknown any
 
     def reread = primary.reread
 
@@ -60,17 +88,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 = nil, **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

@@ -18,20 +18,13 @@ module Cogger
                 .add_emoji(:error, "🛑")
                 .add_emoji(:fatal, "🔥")
                 .add_emoji(:any, "⚫️")
-                .add_filter(:_csrf)
-                .add_filter(:password)
-                .add_filter(:password_confirmation)
                 .add_formatter(:color, Cogger::Formatters::Color)
                 .add_formatter(
                   :detail,
                   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
+
+require "core"
+require "refinements/hashes"
+
+module Cogger
+  # Models a tag which may consist of an array and/or hash.
+  Tag = Data.define :singles, :pairs do
+    using Refinements::Hashes
+
+    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_h = empty? ? Core::EMPTY_HASH : {tags: singles.to_a, **pairs}.tap(&:compress!)
+
+    def to_s = empty? ? Core::EMPTY_STRING : "#{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.13.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,8 +35,22 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-10-01 00:00:00.000000000 Z
+date: 2023-10-19 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: refinements
   requirement: !ruby/object:Gem::Requirement
@@ -92,10 +106,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 +122,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
@@ -133,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.4.21
 signing_key:
 specification_version: 4
 summary: A customizable and feature rich logger.

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