hubbado-log 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 420feafe971a2416372391df56971288d2a8a6730d5b2a5b010370465fe0eecb
-  data.tar.gz: 1755fdec20e188020cc6b55431c5a6ccc5edeaec13d952430663e3eb9397685c
+  metadata.gz: 49c303fe323be43f901ed8ef3958b87c79296af3a15efb11c9efb8a9b57156aa
+  data.tar.gz: 97bc2f947b3a4fc0cfd1845c34d722d6608cf36c1daf853334d3b3b03c4171b5
 SHA512:
-  metadata.gz: d1195dd74d23e42ab83a6b93daba36cdd53b5311ee2a1dd19399f1090fe9c2fba4a2b9fe660489a2ba8c85816a3995e495979a7ea3b01c83693a5a2a7dfa0292
-  data.tar.gz: a4c8a344ae3c7297037890633fbec484f5d45114cbc2b1f76bdf15314d2b48a5b7b17ad35c6601a9f59720b6ea98c41b9c34676a1d01d5953bbba8ba5627271b
+  metadata.gz: fde7c3bf0995e34348f47a8441df1b95cf9505c909b08bac8fcc409f994ce8c8eb28cb05343e24b4066977a804434ced09cad3fb36e75908e375d3bddbc81304
+  data.tar.gz: 4f4cae84446c3d1bdf8a9ebb2b986f82a558c623af90a3278c62fa67ee8a23a55163129efc787758b5434faf101346e15187c9f112007333b7295cb26cf3648f

data/ChangeLog.md

@@ -4,6 +4,48 @@ 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.3.0 - 2026-08-15]
+## Added
+- Tags, a second filtering axis beside the level. A message names its concern
+  with `tag:` or `tags:`, and `LOG_TAGS` decides which tagged messages are
+  written. The syntax and semantics are Eventide's log gem's, so a string an
+  operator writes means the same thing in both codebases.
+- `config.tags`, set in code the way `config.level` is, and a `tags:` keyword on
+  `Logger.new` so one logger can name its own list without the process being
+  turned up around it — the escape hatch the level already had.
+- `Controls::LogHandler` records every message it is given in `messages`, answers
+  `logged?` with or without a severity, resets with `reset`, and builds a wired
+  logger with `.attach` or `.logger`. Five downstream projects had each
+  hand-rolled the same thing because the control kept only the most recent; they
+  can delete their copy whenever it suits them. The attributes still read the
+  most recent, derived from `messages` rather than assigned beside it.
+- `.attach` and `.logger` name `_all` as well as `trace`, so neither the
+  configured level nor the configured tag list decides what a spec can read back.
+  `.attach` raises a named `ArgumentError` for a class carrying no logger rather
+  than failing on nil.
+
+## Changed
+- The test suite sets `LOG_TAGS` rather than defaulting it, so a value left in a
+  developer's shell cannot decide which tests can write anything.
+
+## Compatibility
+Nothing that exists breaks. A handler's arguments are unchanged — tags decide
+whether it is called, and are not passed to it. Every handler across the
+consuming repositories was checked and needs no edit.
+
+One theoretical change: the severity methods and `Hubbado::Log.log` now name
+`tag:` and `tags:`, so a call site passing its data as bare keywords —
+`logger.info('x', record_id: 7)`, which worked because Ruby folded them into a
+positional hash while the methods accepted none — raises instead. No such call
+site exists in any consuming repository; pass the hash explicitly if one appears.
+
+## Not included
+A tag declared once per component, and tags reaching a log handler. Neither has
+an implementer: nothing tags a message yet, and no handler prints or routes on
+one. Eventide does not pass tags to its own output either — they filter, and
+stop there. Both are worth adding when something needs them, and neither has to
+break a handler to arrive.
+
 # [1.2.0 - 2026-08-14]
 ## Added
 - A `trace` level, below `debug`. Program flow — a line per iteration of a loop —

data/README.md

@@ -20,7 +20,7 @@ Or install it yourself as:
 
 ## Level
 
-A line below the level reaches no handler.
+A message below the level reaches no handler.
 
 ```ruby
 Hubbado::Log.configuration do |config|
@@ -45,13 +45,72 @@ Levels, lowest first:
 | `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)`.
+
+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.
 
+## Tags
+
+A level says what kind of thing happened. A tag says which concern it belongs to, so a
+completion that is simply frequent can be filtered out without being demoted to `debug`.
+
+Name the concern where the message is written. `tag:` and `tags:` are both accepted, and a
+message can use either or both:
+
+```ruby
+logger.info('Invoice raised', tags: [:invoicing, :billing])
+logger.trace('Row read', tag: :data)
+```
+
+### `LOG_TAGS`
+
+Which tagged messages are written is decided by `LOG_TAGS`, a comma-separated list:
+
+    $ LOG_TAGS='_untagged,-data,billing,invoicing' ./my-command
+
+| Entry | Meaning |
+|---|---|
+| `name` | Write messages carrying this tag |
+| `-name` | Do not write messages carrying this tag, even if another entry includes them |
+| `_untagged` | Write messages carrying no tag at all |
+| `_all` | Write every message, whatever it carries |
+
+A message can also tag itself `:*`, which writes it whatever the list says.
+
+**Write the list with no spaces.** It is split on commas and nothing else, so `http, cache`
+asks for a tag named `http` and another named `⎵cache`, which nothing carries. This is
+Eventide's behaviour, kept deliberately so one `LOG_TAGS` means the same thing to both gems.
+
+Tags compose with the level rather than replacing it: both filters have to pass, so a tag
+cannot raise a message above the level and the level cannot rescue one the list leaves out.
+
+A single logger can name its own list, as it can name its own level, so one component can be
+read without turning up everything around it:
+
+```ruby
+Hubbado::Log::Logger.new(subject, handlers, level: :trace, tags: '_all')
+```
+
+The syntax and its behaviour are Eventide's log gem, copied deliberately so that a string an
+operator writes means the same thing in both codebases. Two consequences of that are worth
+knowing before adopting tags:
+
+- **`LOG_TAGS` is an allow-list.** A tagged message is written only if the list names it. Adding
+  a tag to a call site therefore *silences* that message everywhere `LOG_TAGS` has not been
+  updated — cron, CI and production included. Ship the variable with the tag.
+- **There is no way to mute one concern and keep the rest.** `-name` subtracts only from
+  messages an include has already matched, and `_all` is answered before any exclusion, so
+  `_all,-data` still writes `data` messages. Keeping everything except one concern means naming
+  the others.
+
+`LOG_TAGS` is shared with Eventide's log gem, as `LOG_LEVEL` is. In a process running both, one
+list decides for both, and an application whose messages are all untagged goes silent unless the
+list contains `_untagged`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/hubbado-log.gemspec

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

data/lib/hubbado/log/configuration.rb

@@ -1,16 +1,24 @@
 module Hubbado
   class Log
     class Configuration
-      # Tracing is off until somebody asks for it, which is what lets a debug line be written
+      # Tracing is off until somebody asks for it, which is what lets a debug message be written
       # for a human watching one run without it also reaching every unattended log.
       DEFAULT_LEVEL = :info
 
       attr_accessor :loggers
       attr_reader :level
+      attr_reader :tags
 
-      def initialize(level: nil)
+      def initialize(level: nil, tags: nil)
         @loggers = []
         self.level = level || DEFAULT_LEVEL
+        self.tags = tags
+      end
+
+      # Takes the LOG_TAGS string as readily as a list, so nothing upstream has to know the
+      # syntax in order to hand a value in.
+      def tags=(value)
+        @tags = Tags.parse(value)
       end
 
       # A name rather than a severity is answered with the default instead of an exception.

data/lib/hubbado/log/controls/log_handler.rb

@@ -2,18 +2,63 @@ module Hubbado
   class Log
     module Controls
       class LogHandler < Hubbado::Log::LogHandler
-        attr_accessor :subject
-        attr_accessor :severity
-        attr_accessor :message
-        attr_accessor :data
-        attr_accessor :stacktrace
+        # Everything a class logged, in order, because a run that reports two failures needs
+        # both of them. The attributes below read the most recent.
+        def messages
+          @messages ||= []
+        end
+
+        # Replaces a class's logger with one writing here, keeping its subject. Neither the
+        # configured level nor the configured tags decide what a spec attaching one of these can
+        # read: it is asking what the class said, and the process's filters are not its subject.
+        def self.attach(instance, level: :trace, tags: Tags::ALL)
+          logger = instance.logger
+
+          if logger.nil?
+            raise ArgumentError, "#{instance.class} carries no logger to attach to. " \
+                                 "Use .logger for a class that is handed one instead."
+          end
+
+          new.tap do |handler|
+            instance.logger = Logger.new(logger.subject, [handler], level: level, tags: tags)
+          end
+        end
+
+        # For a class handed a logger rather than carrying one, and for a spec that wants both.
+        def self.logger(subject = Subject.example, level: :trace, tags: Tags::ALL)
+          handler = new
+
+          [handler, Logger.new(subject, [handler], level: level, tags: tags)]
+        end
 
         def log(subject, severity, message, data = nil, stacktrace = nil)
-          self.subject = subject
-          self.severity = severity
-          self.message = message
-          self.data = data
-          self.stacktrace = stacktrace
+          messages << {
+            subject: subject,
+            severity: severity,
+            message: message,
+            data: data,
+            stacktrace: stacktrace
+          }
+        end
+
+        # Named without a severity, this answers whether anything was written at all — which a
+        # spec would otherwise have to infer from an attribute never having been set. A severity
+        # is compared as a symbol, because #log takes a String as readily and passes on what it
+        # was given.
+        def logged?(severity = nil)
+          return !messages.empty? if severity.nil?
+
+          messages.any? { |written| written.fetch(:severity).to_s.to_sym == severity.to_s.to_sym }
+        end
+
+        def reset
+          @messages = []
+        end
+
+        # The most recent message. Derived rather than assigned alongside `messages`, so the two
+        # cannot disagree about which message is the latest.
+        %i[subject severity message data stacktrace].each do |field|
+          define_method(field) { messages.last&.fetch(field) }
         end
       end
     end

data/lib/hubbado/log/log.rb

@@ -2,17 +2,18 @@ module Hubbado
   class Log
     include Dependency
 
-    # Ordered, because the level compares against them. `trace` is program flow, a line per
+    # Ordered, because the level compares against them. `trace` is program flow, a message 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
 
     LEVEL_VARIABLE = "LOG_LEVEL".freeze
+    TAGS_VARIABLE = "LOG_TAGS".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])
+    # The one place the environment is read. A command names its level and tags here or not at
+    # all, and everything downstream is handed the value rather than the variable.
+    @config = Configuration.new(level: ENV[LEVEL_VARIABLE], tags: ENV[TAGS_VARIABLE])
 
     class << self
       attr_reader :config
@@ -31,8 +32,11 @@ module Hubbado
         @logger = Logger.new('', loggers)
       end
 
-      def log(*args)
-        logger.log(*args)
+      # The keywords are named rather than swept up with the positionals: a method taking only
+      # `*args` accepts no keywords, so Ruby would fold them into a trailing hash and they would
+      # arrive as the message's data — which a handler hands to Rollbar as the exception.
+      def log(*args, tag: nil, tags: nil)
+        logger.log(*args, tag: tag, tags: tags)
       end
     end
 

data/lib/hubbado/log/logger.rb

@@ -4,18 +4,23 @@ module Hubbado
       attr_accessor :log_handlers
       attr_accessor :subject
 
-      def initialize(subject, log_handlers = [], level: nil)
+      def initialize(subject, log_handlers = [], level: nil, tags: nil)
         self.subject = subject
         self.log_handlers = Array(log_handlers)
         @level = level
+        @tags = tags
       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
+      # builds itself: `Log.configure` names neither, 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)
+      # Named per logger as well as per process, as the level is and as Eventide's log gem has
+      # it, so one component can be read without turning up everything around it.
+      def tags = @tags.nil? ? Log.config.tags : Tags.parse(@tags)
+
+      def log(severity, msg, data = nil, tag: nil, tags: nil)
         unless SEVERITIES.keys.include? severity.to_sym
           raise ArgumentError, "Unknown serverity #{severity}"
         end
@@ -24,6 +29,19 @@ module Hubbado
         # 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)
 
+        # Singular and plural are both accepted and both kept, following Eventide's log gem,
+        # where real call sites use either and occasionally hand an array to the singular one.
+        #
+        # Named as symbols, because that is what LOG_TAGS is parsed into: a String here would
+        # match nothing and its message would go missing with nothing said about it.
+        message_tags = (Array(tags) + Array(tag)).map { |name| name.to_s.to_sym }
+
+        # Both filters have to pass. A tag cannot raise a message above the level, and the level
+        # cannot rescue one the list leaves out.
+        #
+        # `self.` because the `tags:` keyword above shadows the reader.
+        return unless self.tags.write?(message_tags)
+
         stacktrace = if data.is_a?(Exception)
                        data.full_message
                      elsif STACKTRACE_SEVERITIES.include?(severity)
@@ -36,8 +54,8 @@ module Hubbado
       end
 
       SEVERITIES.each_key do |severity|
-        define_method severity do |msg, data = nil|
-          log severity, msg, data
+        define_method severity do |msg, data = nil, tag: nil, tags: nil|
+          log severity, msg, data, tag: tag, tags: tags
         end
       end
 

data/lib/hubbado/log/tags.rb

@@ -0,0 +1,82 @@
+module Hubbado
+  class Log
+    # The operator's list, from LOG_TAGS: an allow-list a message's own tags have to intersect
+    # before it is written.
+    class Tags
+      # Every tag is written, whatever else the list says.
+      ALL = :_all
+
+      # Messages carrying no tag at all are written. Without it, naming any tag silences them.
+      UNTAGGED = :_untagged
+
+      # A message marks itself as written whatever the operator asked for.
+      EVERY_MESSAGE = :*
+
+      EXCLUSION = "-".freeze
+
+      # Split on commas and nothing else, which is all Eventide's log gem does. Trimming the
+      # spaces would be kinder, and would make one LOG_TAGS mean different things in the two gems
+      # that share the variable — the divergence this gem cannot afford.
+      def self.parse(value)
+        return value if value.is_a?(self)
+        return new if value.nil?
+        return new(value) if value.is_a?(Array)
+
+        new(value.to_s.split(","))
+      end
+
+      attr_reader :tags
+
+      def initialize(tags = [])
+        @tags = Array(tags).map { |tag| tag.to_s.to_sym }
+      end
+
+      # An exclusion-only list still counts as the operator having named tags, which is what
+      # makes `-data` on its own silence everything rather than subtract from everything.
+      def any?
+        !tags.empty?
+      end
+
+      # Branch for branch from Eventide's log gem, so that a string an operator writes means the
+      # same thing in both codebases. That includes the awkward part: `_all` is answered before
+      # any exclusion, so `_all,-data` writes `data` messages regardless.
+      def write?(message_tags)
+        message_tags = Array(message_tags)
+
+        return true if message_tags.empty? && !any?
+        return true if message_tags.include?(EVERY_MESSAGE)
+        return true if named?(ALL)
+        return true if message_tags.empty? && named?(UNTAGGED)
+        return true if !message_tags.empty? && any? && intersect?(message_tags)
+
+        false
+      end
+
+      private
+
+      def named?(tag)
+        tags.include?(tag)
+      end
+
+      def intersect?(message_tags)
+        return false if message_tags.intersect?(excluded)
+
+        included.intersect?(message_tags)
+      end
+
+      def included
+        @included ||= tags.reject { |tag| excluded?(tag) }
+      end
+
+      def excluded
+        @excluded ||= tags
+          .select { |tag| excluded?(tag) }
+          .map { |tag| tag.to_s.delete_prefix(EXCLUSION).to_sym }
+      end
+
+      def excluded?(tag)
+        tag.to_s.start_with?(EXCLUSION)
+      end
+    end
+  end
+end

data/lib/hubbado/log.rb

@@ -1,4 +1,5 @@
 require 'dependency'
+require "hubbado/log/tags"
 require "hubbado/log/configuration"
 require "hubbado/log/log"
 require "hubbado/log/logger"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-log
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Hubbado Devs
@@ -86,6 +86,7 @@ files:
 - lib/hubbado/log/log.rb
 - lib/hubbado/log/log_handler.rb
 - lib/hubbado/log/logger.rb
+- lib/hubbado/log/tags.rb
 homepage: https://www.github.com/hubbado/hubbado-log
 licenses:
 - MIT