cogger 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f8bcb6e5db91a1e5216dba5864806aead97bd32a9d8fcda1d59a4b22beb079c
-  data.tar.gz: a21a6b830568388316d651204f93f9209ba4694b00e6760a677c81224d1e1a3f
+  metadata.gz: 57f5049812c9af7fd2f1f936ac37c85562fad47517f6b3d2ccd2e34e2d1ee691
+  data.tar.gz: 2ecc0b1bd9e9cc37c85ee9f8db19c936b47d65a71b4723631f96debcdbd4b23e
 SHA512:
-  metadata.gz: ae3d73862e4cbb63a98223023e77cde2b58cf53a4a5b6a94b7e972215629f47a81b956d196c20384386b31d6833ed33689943e01fb4fb4b60957c98794cfc381
-  data.tar.gz: 6d73ec6858638127a168388b23821e77abf7f196a49af51e184ba496084f81295316c148d4d7417d1d3e4b700cc079bc66695b392accc62be47d7cd6e23f3b45
+  metadata.gz: 4318c120bb3182a8a0740025b1528a6643b876b3d0ff71e3b875304484b4da5df44af044d474e2d93cacd1807487560063ac5e4d8499ef514a42c1c5644573a6
+  data.tar.gz: 7018412ed2a90da5e9fc31931e203d76767f405ff1559644570382891ccdb412c19c30eb2bb86f56f52be4e624f2938decb8f00c5fbf50feaf11735cf2e9f8bc

data/README.adoc

@@ -28,27 +28,27 @@ toc::[]
 
 *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
 
@@ -93,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:
@@ -103,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
@@ -154,6 +156,72 @@ logger = Cogger.new id: :demo,
                     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
@@ -361,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.
@@ -469,17 +539,22 @@ logger.warn "Demo"
 
 ==== JSON
 
-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:
+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: "/"
 
@@ -488,9 +563,43 @@ 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.
 
+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 native formatter as provided by original/native {logger_link}, it will work but not in the manner expected. 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]
 ----
@@ -569,10 +678,10 @@ 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"
 
-🟢 [ONE] [two] [3] [FIVE] [four=FOUR] 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.
+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:
 
@@ -581,7 +690,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" }]
 
-🟢 [ONE] [two] [3] [FIVE] [four=FOUR] Demo
+# 🟢 [ONE] [two] [3] [FIVE] [four=FOUR] Demo
 ----
 
 You can also combine global and local tags:
@@ -604,43 +713,38 @@ As you can see, tags are highly versatile. That said, the following guidelines a
 
 === Filters
 
-Filters allow you to mask sensitive information you don't want showing up in your logs. Here are the defaults:
+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
-
-# [
-#   :_csrf,
-#   :password,
-#   :password_confirmation
-# ]
+Cogger.filters  # #<Set: {}>
 ----
 
-To add additional filters, use:
+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
@@ -670,13 +774,13 @@ There is a lot you can do with streams. For example, if you wanted to experiment
 
 [source,ruby]
 ----
-cogger = Cogger.new
+logger = Cogger.new
                .add_stream(formatter: :color)
                .add_stream(formatter: :detail)
                .add_stream(formatter: :json)
                .add_stream(formatter: :simple)
 
-cogger.info "Demo"
+logger.info "Demo"
 
 # 🟢 Demo
 # Demo

data/cogger.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "cogger"
-  spec.version = "0.12.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
@@ -21,7 +22,7 @@ module Cogger
                    io: $stdout,
                    level: Logger.const_get(ENV.fetch("LOG_LEVEL", "INFO")),
                    formatter: Formatters::Emoji.new,
-                   tags: [],
+                   tags: Core::EMPTY_ARRAY,
                    mode: false,
                    age: 0,
                    size: 1_048_576,

data/lib/cogger/entry.rb

@@ -1,5 +1,7 @@
 # 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
@@ -27,7 +29,7 @@ module Cogger
                    at: Time.now,
                    message: nil,
                    tags: [],
-                   payload: {}
+                   payload: Core::EMPTY_HASH
       super
     end
 
@@ -38,7 +40,7 @@ module Cogger
 
       return attributes if computed_tags.empty?
 
-      {id:, severity:, at:, message:, tags: computed_tags.to_a, **payload}
+      {id:, severity:, at:, message:, **computed_tags.to_h, **payload}
     end
 
     def tagged tagger: Tag

data/lib/cogger/formatters/json.rb

@@ -1,22 +1,26 @@
 # 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
-        @positions = parser.call(template).last.keys
+        @positions = template ? parser.call(template).last.keys : Core::EMPTY_ARRAY
         @sanitizer = sanitizer
       end
 
       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
 

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

@@ -33,6 +33,8 @@ module Cogger
       level=
     ] => :primary
 
+    delegate %i[id io tags mode age size suffix] => :configuration
+
     def initialize(registry: Cogger, model: Configuration, **attributes)
       @registry = registry
       @configuration = model[**find_formatter(attributes)]
@@ -59,6 +61,10 @@ module Cogger
 
     def any(message = nil, **payload, &) = log(__method__, message, **payload, &)
 
+    def add(severity, message = nil, **payload, &)
+      log(Logger::SEV_LABEL.fetch(severity, "ANY").downcase, message, **payload, &)
+    end
+
     alias unknown any
 
     def reread = primary.reread
@@ -82,7 +88,7 @@ module Cogger
       )
     end
 
-    def log(severity, message, **payload, &)
+    def log(severity, message = nil, **payload, &)
       dispatch(severity, message, **payload, &)
     rescue StandardError => error
       crash message, error

data/lib/cogger/registry.rb

@@ -18,9 +18,6 @@ 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,

data/lib/cogger/tag.rb

@@ -1,8 +1,13 @@
 # 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
@@ -16,14 +21,9 @@ module Cogger
 
     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_h = empty? ? Core::EMPTY_HASH : {tags: singles.to_a, **pairs}.tap(&:compress!)
 
-    def to_s = empty? ? "" : "#{format_singles} #{format_pairs}".tap(&:strip!)
+    def to_s = empty? ? Core::EMPTY_STRING : "#{format_singles} #{format_pairs}".tap(&:strip!)
 
     private
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cogger
 version: !ruby/object:Gem::Version
-  version: 0.12.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-15 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
@@ -135,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.