cogger 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 590801ee49ce6abe0d7d22d1d66732a10e41e384eb5018394b1f9de0c4ae1b4e
-  data.tar.gz: 6707a9761a959c480f2ae2aa629b5c826248322880e428f92d3ce9b625e2fd26
+  metadata.gz: e943adc7eaeab019242b860b3c66da64e24c52cfe756c242d3b92de480586503
+  data.tar.gz: ad0f47de612ca8fde2eff91593e32e5ed7cfaad13f77b62b6c3aebcbe18a9bc6
 SHA512:
-  metadata.gz: 3972438237dafd8409de8cc2ae0a9e8eec351cd10f60fced84691b2b13998d3fec29a2403adf495a28a732d65c66ebc825f53d2f76b990966bcfa4d70ef629db
-  data.tar.gz: 3ab12b7c97dedd47ec5630db725093ba7f15679640ce20afbf6ca396a4655e2e5a837b26021750f54a93ba38b885acd7f0face409cb76e309877b472695b34db
+  metadata.gz: 52c552fcb5ae45c4893bb84e427691504d49b987904734e81ce68b3dac889544f30c040e547d7a99d17c18429c732651a63b7628d11c00de6ba506985ea7c493
+  data.tar.gz: 4d7d3c410af6800bbcc6c2d35d969d06e5752c9a326010e55c8049ba91e5657aa808a04cb82cbaf294f077630a61c01ff4dcbed156abf54696a017cd59955a00

data/README.adoc

@@ -2,10 +2,11 @@
 :toclevels: 5
 :figure-caption!:
 
-:tone_link: link:https://alchemists.io/projects/tone[Tone]
+:format_link: link:https://ruby-doc.org/3.2.2/format_specifications_rdoc.html[String Format Specification]
 :logger_link: link:https://rubyapi.org/o/s?q=Logger[Logger]
-:format_link: link:https://ruby-doc.org/3.2.1/format_specifications_rdoc.html[Format Specification]
 :pattern_matching_link: link:https://alchemists.io/articles/ruby_pattern_matching[pattern matching]
+:rack_link: link:https://github.com/rack/rack[Rack]
+:tone_link: link:https://alchemists.io/projects/tone[Tone]
 
 = Cogger
 
@@ -23,6 +24,7 @@ toc::[]
 * 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.
+* Provides {rack_link} middleware for HTTP request logging.
 
 == Screenshots
 
@@ -44,7 +46,7 @@ image::https://alchemists.io/images/projects/cogger/screenshots/detail.png[Detai
 
 *JSON*
 
-image::https://alchemists.io/images/projects/cogger/screenshots/json.png[JSON,width=962,height=297]
+image::https://alchemists.io/images/projects/cogger/screenshots/json.png[JSON,width=1002,height=290]
 
 *Rack*
 
@@ -156,51 +158,32 @@ logger = Cogger.new id: :demo,
                     suffix: "%Y"
 ----
 
-=== Inspection
+=== Levels
 
-Each instance can be inspected via the `#inspect` message:
+Supported levels can be obtained via `Cogger::LEVELS`. Example:
 
 [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>"
+Cogger::LEVELS
+# ["debug", "info", "warn", "error", "fatal", "unknown"]
 ----
 
-You can also look at individual attributes:
+=== Environment
 
-[source,ruby]
-----
-logger = Cogger.new
+You can use your environment to define the desired default log level. The default log level is: `"info"`. Although, you can set the log level to any of the following:
 
-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
+[source,bash]
+----
+export LOG_LEVEL=debug
+export LOG_LEVEL=info
+export LOG_LEVEL=warn
+export LOG_LEVEL=error
+export LOG_LEVEL=fatal
+export LOG_LEVEL=unknown
 ----
 
+While downcase is preferred for the log level, you can use upcased values as well. If the `LOG_LEVEL` environment variable is not set, `Cogger` will fall back to `"info"` unless overwritten during initialization. Example: `Cogger.new level: :debug`. Otherwise, an invalid log level will result in an `ArgumentError`.
+
 === Mutations
 
 Each instance can be mutated using the following messages:
@@ -222,26 +205,9 @@ 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
-set the logging level to any of the following:
-
-[source,bash]
-----
-export LOG_LEVEL=DEBUG
-export LOG_LEVEL=INFO
-export LOG_LEVEL=WARN
-export LOG_LEVEL=ERROR
-export LOG_LEVEL=FATAL
-export LOG_LEVEL=UNKNOWN
-----
-
-By default, `Cogger` will automatically use whatever is set via the `LOG_LEVEL` environment variable unless overwritten during initialization.
-
 === Templates
 
-Templates are used by all formatters and adhere to {format_link} as used by `Kernel#format`. All specifiers, flags, width, and precision are supported except for the following restrictions:
+Templates are used by all formatters and adhere to the {format_link} as used by `Kernel#format`. All specifiers, flags, width, and precision are supported except for the following restrictions:
 
 - 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.
@@ -539,16 +505,16 @@ 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 template information is ignored, only the order of your template keys matters. Example:
+This formatter is similar in behavior to the _simple_ formatter except that date/time defaults to UTC, is formattted according to link:https://datatracker.ietf.org/doc/html/rfc3339[RFC 3339] using millisecond precision, and 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]
 ----
 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":"/"}
+logger.info verb: "GET", path: "/"
+# {"id":"console","severity":"INFO","at":"2023-12-10T18:42:32.844+00:00","verb":"GET","path":"/"}
 ----
 
 *Custom Order*
@@ -556,9 +522,9 @@ logger.info verb: "GET", path: "/"
 [source,ruby]
 ----
 logger = Cogger.new formatter: Cogger::Formatters::JSON.new("%<severity>s %<verb>s")
-logger.info verb: "GET", path: "/"
 
-# {"severity":"INFO","verb":"GET","id":"console","at":"2023-04-10 09:05:03 -0600","path":"/"}
+logger.info verb: "GET", path: "/"
+# {"severity":"INFO","verb":"GET","id":"console","at":"2023-12-10T18:43:03.805+00:00","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.
@@ -567,29 +533,29 @@ You can always supply a message as your first argument -- or specify it by using
 
 [source,ruby]
 ----
-logger = Cogger.new formatter: json
+logger = Cogger.new formatter: :json
 
 logger.info "Demo"
-# {"id":"console","severity":"INFO","at":"2023-10-18 19:38:55 -0600","message":"Demo"}
+# {"id":"console","severity":"INFO","at":"2023-12-10T18:43:42.029+00:00","message":"Demo"}
 
-logger.info messsage: "Demo"
-{"id":"console","severity":"INFO","at":"2023-10-18 19:39:19 -0600","messsage":"Demo"}
+logger.info message: "Demo"
+# {"id":"console","severity":"INFO","at":"2023-12-10T18:44:14.568+00:00","message":"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:
+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 output. 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",
+#   "at":"2023-12-10T18:44:32.723+00:00",
 #   "message":"Demo",
-#   "tags":["WEB","PRIMARY"],
+#   "tags":["WEB",
+#   "PRIMARY"],
 #   "service":"api",
 #   "demo":true
 # }
@@ -789,6 +755,89 @@ logger.info "Demo"
 # Demo
 ----
 
+=== Rack
+
+{rack_link} is _implicitly_ supported which means your middleware _must be_ Rack-based and _must require_ the Rack gem since `Cogger::Rack::Logger` doesn't _explicitly_ require Rack by default. If these requirements are met then, to add HTTP request logging, you only need to use it. Example:
+
+[source,ruby]
+----
+use Rails::Rack::Logger
+----
+
+Like any other {rack_link} middleware, `Rails::Rack::Logger` is initialized with your current application along with any custom options. Example:
+
+[source,ruby]
+----
+middleware = Cogger::Rack::Logger.new application
+middleware.call environment
+----
+
+The following defaults are supported:
+
+[source,ruby]
+----
+Cogger::Rack::Logger::DEFAULTS
+
+# {
+#   logger: Cogger.new(formatter: :json),
+#   timer: Cogger::Time::Span.new,
+#   :key_map => {
+#       :verb => "REQUEST_METHOD",
+#         :ip => "REMOTE_ADDR",
+#       :path => "PATH_INFO",
+#     :params => "QUERY_STRING",
+#     :length => "CONTENT_LENGTH"
+#   }
+# }
+----
+
+The defaults can be customized. Example:
+
+[source,]
+----
+Cogger::Rack::Logger.new application, {logger: Cogger.new}
+----
+
+In the above example, we see `Cogger.new` overrides the default `Cogger.new(formatter: :json)`. In practice, you'll want to customize the logger and key map. Here's how each default is configured to be used:
+
+* `logger`: Defaults to JSON formatted logging but you'll want to pass in the same logger as globally configured for your application in order to reduce duplication and save on memory.
+* `timer`: The timer calculates the total duration of the request and defaults to nanosecond precision but you can swap this out with your own timer if desired. When providing your own timer, the only requirement is that the timer respond to the `#call` message with a block.
+* `key_map`: The key map is used to map the HTTP Headers to keys (i.e. tags) used in the log output. You can use the existing key map, provide your own, or use a hybrid.
+
+Once this middleware is configured and used within your application, you'll start seeing the following kinds of log entries (depending on your specific settings and tags used):
+
+[source,json]
+----
+{
+  "id":"demo",
+  "severity":"INFO",
+  "at":"2023-12-10T22:37:06.341+00:00",
+  "verb":"GET",
+  "ip":"127.0.0.1",
+  "path":"/dashboard",
+  "status":200,
+  "duration":83,
+  "unit":"ms"
+}
+----
+
+*Rails*
+
+To build upon the above -- and if using the Rails framework -- you could configure your application as follows:
+
+[source,ruby]
+----
+# demo/config/application.rb
+module Demo
+  class Application < Rails::Application
+    config.logger = Cogger.new id: "demo", formatter: :json,
+    config.middleware.swap Rails::Rack::Logger, Cogger::Rack::Logger, {logger: config.logger}
+  end
+end
+----
+
+The above defines `Cogger` as the default logger for the entire application, ensures `Cogger::Rack::Logger` is configured to use it and swaps itself with the default `Rails::Rack::Logger` so you don't have two pieces of middleware logging the same HTTP requests.
+
 === Defaults
 
 Should you ever need quick access to the defaults, you can use:
@@ -800,6 +849,51 @@ Cogger.defaults
 
 This is primarily meant for display/inspection purposes, though.
 
+=== 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
+----
+
 === Testing
 
 When testing, you might find it convenient to rewind and read from the stream you are writing too (i.e. `IO`, `StringIO`, `File`). For instance, here is an example where I inject the default logger into my `Demo` class and then, for testing purposes, create a new logger to be injected which only logs to `StringIO` so I can buffer and read for test verification:
@@ -852,7 +946,7 @@ You can also use the IRB console for direct access to all objects:
 bin/console
 ----
 
-Lastly, there is a `bin/show` script which displays multiple log formats for quick visual reference. This is the same script used to generate the screenshots shown at the top of this document.
+Lastly, there is a `bin/demo` script which displays multiple log formats for quick visual reference. This is the same script used to generate the screenshots shown at the top of this document.
 
 == Tests
 

data/cogger.gemspec

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

data/lib/cogger/configuration.rb

@@ -20,7 +20,7 @@ module Cogger
   ) do
     def initialize id: Program.call,
                    io: $stdout,
-                   level: Logger.const_get(ENV.fetch("LOG_LEVEL", "INFO")),
+                   level: Level.call,
                    formatter: Formatters::Emoji.new,
                    tags: Core::EMPTY_ARRAY,
                    mode: false,

data/lib/cogger/entry.rb

@@ -6,8 +6,9 @@ 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),
+      new id: payload.delete(:id) || Program.call,
           severity: (payload.delete(:severity) || "INFO").upcase,
+          at: payload.delete(:at) || ::Time.now,
           message: (block_given? ? yield : message),
           tags: Array(payload.delete(:tags)),
           payload:
@@ -26,7 +27,7 @@ module Cogger
 
     def initialize id: Program.call,
                    severity: "INFO",
-                   at: Time.now,
+                   at: ::Time.now,
                    message: nil,
                    tags: [],
                    payload: Core::EMPTY_HASH

data/lib/cogger/formatters/json.rb

@@ -18,6 +18,7 @@ module Cogger
 
       def call(*input)
         attributes = sanitizer.call(*input).tagged_attributes.tap(&:compact!)
+        format_date_time attributes
 
         return "#{attributes.to_json}\n" if positions.empty?
 
@@ -27,6 +28,11 @@ module Cogger
       private
 
       attr_reader :positions, :sanitizer
+
+      # :reek:UtilityFunction
+      def format_date_time attributes
+        attributes[:at] = attributes[:at].utc.strftime "%Y-%m-%dT%H:%M:%S.%L%:z"
+      end
     end
   end
 end

data/lib/cogger/level.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "logger"
+require "refinements/arrays"
+
+# Loads log level from environment.
+module Cogger
+  using Refinements::Arrays
+
+  Level = lambda do |logger = Logger, environment: ENV, allowed: LEVELS|
+    value = String environment.fetch("LOG_LEVEL", "INFO")
+
+    return logger.const_get value.upcase if allowed.include? value.downcase
+
+    fail ArgumentError, %(Invalid log level: #{value.inspect}. Use: #{allowed.to_usage "or"}.)
+  end
+end

data/lib/cogger/rack/logger.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "core"
+
+module Cogger
+  module Rack
+    # Middlware for enriched logging based on the incoming request.
+    class Logger
+      DEFAULTS = {
+        logger: Cogger.new(formatter: :json),
+        timer: Cogger::Time::Span.new,
+        key_map: {
+          verb: "REQUEST_METHOD",
+          ip: "REMOTE_ADDR",
+          path: "PATH_INFO",
+          params: "QUERY_STRING",
+          length: "CONTENT_LENGTH"
+        }
+      }.freeze
+
+      def initialize application, options = Core::EMPTY_HASH, defaults: DEFAULTS
+        configuration = defaults.merge options
+
+        @application = application
+        @logger = configuration.fetch :logger
+        @timer = configuration.fetch :timer
+        @key_map = configuration.fetch :key_map
+      end
+
+      def call environment
+        request = ::Rack::Request.new environment
+        (status, headers, body), duration, unit = timer.call { application.call environment }
+
+        logger.info tags: [tags_for(request), {status:, duration:, unit:}]
+
+        [status, headers, body]
+      end
+
+      private
+
+      attr_reader :application, :logger, :timer, :key_map
+
+      def tags_for request
+        key_map.each_key.with_object({}) do |tag, collection|
+          key = key_map.fetch tag, tag
+          collection[String(tag).downcase] = request.get_header key
+        end
+      end
+    end
+  end
+end

data/lib/cogger/time/clock.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Cogger
+  module Time
+    # An adapter for acquiring current time.
+    Clock = -> id = Process::CLOCK_MONOTONIC, unit: :nanosecond { Process.clock_gettime id, unit }
+  end
+end

data/lib/cogger/time/range.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Cogger
+  module Time
+    RANGE = {
+      nanoseconds: ...1_000,
+      microseconds: 1_000...1_000_000,
+      milliseconds: 1_000_000...1_000_000_000,
+      seconds: 1_000_000_000...60_000_000_000,
+      minutes: 60_000_000_000...
+    }.freeze
+  end
+end

data/lib/cogger/time/span.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Cogger
+  module Time
+    # Measures duration of a process with nanosecond precision.
+    class Span
+      def initialize clock = Clock, unit: Unit, range: RANGE
+        @clock = clock
+        @unit = unit
+        @range = range
+      end
+
+      def call
+        start = current
+        result = yield
+        span = current - start
+
+        [result, duration(span), unit.call(span)]
+      end
+
+      private
+
+      attr_reader :clock, :unit, :range
+
+      def duration value
+        case value
+          when nanoseconds then value
+          when microseconds then value / microseconds.min
+          when milliseconds then value / milliseconds.min
+          when seconds then value / seconds.min
+          else value / minutes.min
+        end
+      end
+
+      def current = clock.call
+
+      def nanoseconds
+        @nanoseconds ||= range.fetch __method__
+      end
+
+      def microseconds
+        @microseconds ||= range.fetch __method__
+      end
+
+      def milliseconds
+        @milliseconds ||= range.fetch __method__
+      end
+
+      def seconds
+        @seconds ||= range.fetch __method__
+      end
+
+      def minutes
+        @minutes ||= range.fetch __method__
+      end
+    end
+  end
+end

data/lib/cogger/time/unit.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cogger
+  module Time
+    # Provides unit of measure for duration.
+    # rubocop:disable Style/MethodCallWithArgsParentheses
+    Unit = lambda do |duration, range: RANGE|
+      case duration
+        when range.fetch(:nanoseconds) then "ns"
+        when range.fetch(:microseconds) then "µs"
+        when range.fetch(:milliseconds) then "ms"
+        when range.fetch(:seconds) then "s"
+        else "m"
+      end
+    end
+    # rubocop:enable Style/MethodCallWithArgsParentheses
+  end
+end

data/lib/cogger.rb

@@ -3,7 +3,7 @@
 require "zeitwerk"
 
 Zeitwerk::Loader.new.then do |loader|
-  loader.inflector.inflect "json" => "JSON"
+  loader.inflector.inflect "json" => "JSON", "range" => "RANGE"
   loader.tag = File.basename __FILE__, ".rb"
   loader.push_dir __dir__
   loader.setup
@@ -13,6 +13,8 @@ end
 module Cogger
   extend Registry
 
+  LEVELS = %w[debug info warn error fatal unknown].freeze
+
   def self.loader registry = Zeitwerk::Registry
     @loader ||= registry.loaders.find { |loader| loader.tag == File.basename(__FILE__, ".rb") }
   end

data.tar.gz.sig

@@ -1,4 +1,2 @@
-�1a̫�6i�=6JrS��W��.�Y0��_�4��_������gk
"�N���	Z���K�V���$cէ�����H~�qv|��P(�k�8��r�9�
-
����պ�T%����a�UK�:�ח��M��B��٨捼��x9ʉc�*�z���x�ޑ�
-0�ê�\�aFp��VO�R���;��$�2�ǚ��D��^6�Eh����O�/Gjx�B+enS`ڟ톦�,�K�a��IR�=<-����'\�f_�n��W^꓉EL�H�
-�qj��$Z%�
+)�_��S����q�¦�=��r��B}u��<k8���Y�]גq��hnA��IY�1�^e�b�C4%�����-���ϣ�*
+���

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cogger
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2023-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: core
@@ -120,9 +120,15 @@ files:
 - lib/cogger/formatters/processors/color.rb
 - lib/cogger/formatters/simple.rb
 - lib/cogger/hub.rb
+- lib/cogger/level.rb
 - lib/cogger/program.rb
+- lib/cogger/rack/logger.rb
 - lib/cogger/registry.rb
 - lib/cogger/tag.rb
+- lib/cogger/time/clock.rb
+- lib/cogger/time/range.rb
+- lib/cogger/time/span.rb
+- lib/cogger/time/unit.rb
 homepage: https://alchemists.io/projects/cogger
 licenses:
 - Hippocratic-2.1