hubbado-log 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c3427a0327c368a8e65bb9c42587ed49ea58714e70980b3a6050a82b1e3a81d
-  data.tar.gz: edccc3f0c39bcfb0eac7b2a43f6bad28843592c003e2ebf1f64f1cd057be7d5d
+  metadata.gz: 420feafe971a2416372391df56971288d2a8a6730d5b2a5b010370465fe0eecb
+  data.tar.gz: 1755fdec20e188020cc6b55431c5a6ccc5edeaec13d952430663e3eb9397685c
 SHA512:
-  metadata.gz: e2e70e3dc5f3b3b2085f954517802cf8a3c0489c51574f9f5b9f747d97f8b6cff563dbde54752b38f1a9f159141b79072c2fb8c9fef8e70f998f64f549b5ab1b
-  data.tar.gz: 8cfd3b8fc6b5ab56a7760a7543ffc3ad70bfbf7a89e020e3b3cc2d255fc3ec5123689d94dc130fef0e1dba08c8fd69f66130b08b056635c3bda0a0a3b51c5603
+  metadata.gz: d1195dd74d23e42ab83a6b93daba36cdd53b5311ee2a1dd19399f1090fe9c2fba4a2b9fe660489a2ba8c85816a3995e495979a7ea3b01c83693a5a2a7dfa0292
+  data.tar.gz: a4c8a344ae3c7297037890633fbec484f5d45114cbc2b1f76bdf15314d2b48a5b7b17ad35c6601a9f59720b6ea98c41b9c34676a1d01d5953bbba8ba5627271b

data/ChangeLog.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+# [1.2.0 - 2026-08-14]
+## Added
+- A `trace` level, below `debug`. Program flow — a line per iteration of a loop —
+  so that turning on the completion of secondary operations does not also turn on
+  a line per item in a set.
+
+# [1.1.0 - 2026-08-14]
+## Added
+- A level, below which a line reaches no handler. Set it with `config.level`, or
+  with the `LOG_LEVEL` environment variable, which defaults to `info` — so
+  `debug` is off unless it is asked for.
+
+## Changed
+- `Logger.new` takes a `level:` keyword. A logger built without one follows the
+  configuration.
+- `LOG_LEVEL` is shared with Eventide's log gem, which writes names this gem does
+  not know. A name that is not a severity leaves the level at `info` rather than
+  raising.
+
 # [1.0.1 - 2024-05-30]
 # Changed
 - Release to stop a SHA mismatch between our private github package repo and Ruby Gems

data/README.md

@@ -16,7 +16,41 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install hubbado-logger
+    $ gem install hubbado-log
+
+## Level
+
+A line below the level reaches no handler.
+
+```ruby
+Hubbado::Log.configuration do |config|
+  config.loggers = [MyStderrHandler]
+  config.level = :debug
+end
+```
+
+Without `config.level`, the level comes from the `LOG_LEVEL` environment variable:
+
+    $ LOG_LEVEL=debug ./my-command
+
+It defaults to `info`, so `debug` and `trace` are off until they are asked for.
+
+Levels, lowest first:
+
+| Level | What it records |
+|---|---|
+| `trace` | Most detailed tracing of program flow |
+| `debug` | Completion of a secondary operation of a class or utility, or other details |
+| `info` | Completion of the principal operation of a class or utility |
+| `warn` | Unexpected state that is not an error, or is recoverable, and that a developer or operator should examine |
+| `error` | Message logged just prior to raising an error |
+| `fatal` | Message recorded, when possible, as the process is terminating due to an error |
+ A single logger can
+name its own with `Hubbado::Log::Logger.new(subject, handlers, level: :debug)`.
+
+`LOG_LEVEL` is shared with Eventide's log gem, which writes names this gem does not
+know. A name that is not one of `debug`, `info`, `warn`, `error`, `fatal` or
+`unknown` leaves the level at `info` rather than raising.
 
 ## Development
 

data/hubbado-log.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "hubbado-log"
-  s.version = "1.0.1"
+  s.version = "1.2.0"
   s.summary = "Lightweight pluggable logging system"
 
   s.authors = ["Hubbado Devs"]

data/lib/hubbado/log/configuration.rb

@@ -1,10 +1,26 @@
 module Hubbado
   class Log
     class Configuration
+      # Tracing is off until somebody asks for it, which is what lets a debug line be written
+      # for a human watching one run without it also reaching every unattended log.
+      DEFAULT_LEVEL = :info
+
       attr_accessor :loggers
+      attr_reader :level
 
-      def initialize
+      def initialize(level: nil)
         @loggers = []
+        self.level = level || DEFAULT_LEVEL
+      end
+
+      # A name rather than a severity is answered with the default instead of an exception.
+      # The level is set from LOG_LEVEL, which Eventide's log gem owns across hubbado_saas and
+      # writes its own vocabulary into ("_min"): a variable this gem shares is not a variable
+      # it can refuse.
+      def level=(value)
+        named = value.to_s.downcase.to_sym
+
+        @level = SEVERITIES.key?(named) ? named : DEFAULT_LEVEL
       end
     end
   end

data/lib/hubbado/log/log.rb

@@ -2,10 +2,17 @@ module Hubbado
   class Log
     include Dependency
 
-    SEVERITIES = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4, unknown: 5 }.freeze
+    # Ordered, because the level compares against them. `trace` is program flow, a line per
+    # iteration; `debug` is the completion of a secondary operation, or a detail worth keeping;
+    # `info` is the completion of the principal operation of a class or utility.
+    SEVERITIES = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, unknown: 6 }.freeze
     STACKTRACE_SEVERITIES = %i[warn error fatal unknown].freeze
 
-    @config = Configuration.new
+    LEVEL_VARIABLE = "LOG_LEVEL".freeze
+
+    # The one place the environment is read. A command names its level here or not at all,
+    # and everything downstream is handed the value rather than the variable.
+    @config = Configuration.new(level: ENV[LEVEL_VARIABLE])
 
     class << self
       attr_reader :config

data/lib/hubbado/log/logger.rb

@@ -4,16 +4,26 @@ module Hubbado
       attr_accessor :log_handlers
       attr_accessor :subject
 
-      def initialize(subject, log_handlers = [])
+      def initialize(subject, log_handlers = [], level: nil)
         self.subject = subject
         self.log_handlers = Array(log_handlers)
+        @level = level
       end
 
+      # A logger built without one follows the configuration, which is every logger the gem
+      # builds itself: `Log.configure` names no level, so a class using the Dependency module
+      # takes whatever the process was configured for.
+      def level = @level || Log.config.level
+
       def log(severity, msg, data = nil)
         unless SEVERITIES.keys.include? severity.to_sym
           raise ArgumentError, "Unknown serverity #{severity}"
         end
 
+        # Read after the severity is checked, never before: the level decides what is printed,
+        # not what may be said, so quietening a logger must not turn a typo into silence.
+        return if SEVERITIES.fetch(severity.to_sym) < SEVERITIES.fetch(level)
+
         stacktrace = if data.is_a?(Exception)
                        data.full_message
                      elsif STACKTRACE_SEVERITIES.include?(severity)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-log
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Hubbado Devs
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Lightweight pluggable logging system
 test_files: []