hubbado-log 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99367c1895c07697aa0e83dc1e068f35cf2052d75dc6c471610b47099f27fd7f
-  data.tar.gz: 58a148cfa36ea3709a2c36fbb228f089d3b176476d27ede4a74ec26a651bdf12
+  metadata.gz: 84cb20198caa8a5346b0a4d50c702b57e77f53cedc2f90e221c05a90985260a0
+  data.tar.gz: 1134a1d43db622684732e5550d76716c8be4dcb5ee0e23382c8aaaedf0743851
 SHA512:
-  metadata.gz: 5a53b16af1babaa5c90125bfddec34a02c5256661004833a63b5b54066a914bf764d2c3c738d0a0d2e556d4bd9ef86d96d7e40419e7acd810f2fb7ca4fe58788
-  data.tar.gz: 6f77c77d30c8a1ef7f89b2b73c8e09585aa3f39d6dd5d9046796220f699f2926c31debd5fb5b8f514e06c7a2fb66e2b5e20be6cf7f86b95e56bba6218a2ef5e5
+  metadata.gz: ac99e3a37b28025006034cd5032a350db0c3e0bf63ee1c504c4af81a589879a5d1e3dd72180592b5d1632471b0f00efe9353cc5dfc6f1b040bf6855370a1f537
+  data.tar.gz: 97fe613dccb476915983d4836ae3736e3fae54168872b20106a71da9e1ec70c40994a7ba79d2931f8fdfc5dd4b36defdc55bf52823de6194b2e552c2ff84f49c

data/ChangeLog.md

@@ -4,6 +4,57 @@ 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.5.0 - 2026-08-16]
+## Added
+- Three handlers, replacing eight hand-rolled copies across four projects and
+  two applications. Each is behind its own require; `require "hubbado/log"`
+  loads none of them.
+
+  ```ruby
+  require "hubbado/log/stderr_logger"
+  require "hubbado/log/notify_rollbar"
+
+  Hubbado::Log.configuration do |config|
+    config.loggers = [Hubbado::Log::StderrLogger, Hubbado::Log::NotifyRollbar]
+  end
+  ```
+
+  | Handler | Writes to | Needs |
+  |---|---|---|
+  | `StderrLogger` | `$stderr` | nothing |
+  | `RailsLogger` | `Rails.logger` | Rails, already loaded wherever a handler is registered |
+  | `NotifyRollbar` | `Rollbar` | `rollbar` in the consumer's own Gemfile |
+
+  Neither Rails nor Rollbar is a dependency of this gem, so installing it
+  installs neither. `notify_rollbar` requires `rollbar` at the top of the file,
+  making an absent gem a `LoadError` at boot rather than a `NameError` raised
+  while a failure is being reported.
+
+  Every copy discarded the `stacktrace` argument, and the Rollbar ones
+  discarded more:
+
+  | | Was | Is now |
+  |---|---|---|
+  | `StderrLogger`, an `error` carrying no exception | no stacktrace | prints it. A `warn` stays one line, and an exception's backtrace is never printed twice |
+  | `RailsLogger`, a `trace` line | `NoMethodError` in one of the two copies | written as `debug` |
+  | `NotifyRollbar`, the subject | dropped | a `subject` key, merged last so a line cannot claim another class |
+  | `NotifyRollbar`, a stacktrace with no exception | dropped | a `stacktrace` key |
+  | `NotifyRollbar`, data that is not a hash or exception | dropped | a `data` key holding its `inspect` |
+
+  Rollbar keeps the last hash it is handed and ignores anything that is not a
+  String, an Exception or a Hash, so `NotifyRollbar` merges everything into one
+  hash — built fresh per call, because Rollbar deletes a key from the hash it
+  is given.
+
+- Controls for what a handler spec stands in for: `Controls::Rollbar`,
+  `Controls::RailsLogger`, `Controls::Receiver` and `Controls::Stacktrace`.
+
+  `Controls::Rollbar` reads a notification back the way Rollbar reads its
+  arguments, keeping the last hash — so a handler sending two would pass
+  against a merging control and lose data against the real thing.
+  `Controls::RailsLogger` does not answer to `trace`, so a handler passing it
+  straight through raises here as it would in Rails.
+
 # [1.4.1 - 2026-08-16]
 ## Fixed
 - A subclass of `Hubbado::Log` can be used as a dependency. It answered `nil`

data/README.md

@@ -48,13 +48,143 @@ end
 Either way the logger writes through the handlers the process was configured with, at the level
 and tags it was configured for.
 
+## Handlers
+
+A handler is what a log line is finally written *to*. The process names them, and the log system
+builds each one itself with no arguments:
+
+```ruby
+Hubbado::Log.configuration do |config|
+  config.loggers = [Hubbado::Log::StderrLogger]
+end
+```
+
+Handlers mostly belong to the application rather than to this gem, because what they write to is
+the application's — a Rails logger, a Rollbar token. Write one by subclassing
+`Hubbado::Log::LogHandler` and implementing `log`:
+
+```ruby
+class MyHandler < Hubbado::Log::LogHandler
+  def log(subject, severity, message, data = nil, stacktrace = nil)
+    ...
+  end
+end
+```
+
+`data` is whatever the call site passed as the second argument, and is an `Exception` when it
+logged one. `stacktrace` is the exception's `full_message` in that case, and otherwise the caller
+stack, synthesised for `warn`, `error`, `fatal` and `unknown` only.
+
+### `Hubbado::Log::StderrLogger`
+
+For a command-line tool, where the log is a person watching a run. It is not loaded by
+`require 'hubbado/log'` — ask for it:
+
+```ruby
+require 'hubbado/log/stderr_logger'
+```
+
+It prints the severity, the subject and the message on one line, and anything the line carried
+below it:
+
+    WARN Scanning::Sweep: rec_1 skipped, no rate
+    ERROR Scanning::Sweep: rec_2 refused
+    /app/lib/scanning/sweep.rb:41:in 'post': HTTP 400 (RequestError)
+      from /app/lib/scanning/sweep.rb:12:in 'call'
+
+A stacktrace prints at `error` and above, and only when the data is not an exception — an
+exception already prints its own backtrace, so honouring both would print it twice. A `warn`
+stays one line: it is a condition to examine rather than a failure to trace, and a sweep that
+warns per row would otherwise bury itself in Ruby stack.
+
+Pass `io:` to write somewhere else, which is mainly how a spec reads it back:
+
+```ruby
+Hubbado::Log::StderrLogger.new(io: StringIO.new)
+```
+
+### `Hubbado::Log::RailsLogger`
+
+Writes into a Rails application's own log.
+
+```ruby
+require "hubbado/log/rails_logger"
+
+Hubbado::Log.configuration do |config|
+  config.loggers = [Hubbado::Log::RailsLogger]
+end
+```
+
+Rails is not a dependency of this gem. The constant is read lazily, and the only place a handler
+is ever registered is an environment file, where Rails is loaded by definition.
+
+The subject and message go on one line, and the data and stacktrace on lines below it, all at the
+severity of the line. An exception is one line rather than two — its backtrace already carries the
+message that its `inspect` would repeat. `trace` is written as `debug`, because Rails' logger has
+no method below it, and a handler passing `trace` straight through raises `NoMethodError` on the
+first trace line it is handed.
+
+Unlike the stderr handler, the stacktrace is written at every severity. A Rails log is read after
+the fact, and by machine as often as by a person, so there is nothing to keep readable by
+withholding frames.
+
+Pass `rails_logger:` to write somewhere else, which is mainly how a spec reads it back. Left
+unset, `Rails.logger` is read on every line rather than held, so a handler built before Rails
+replaced its logger still writes to the current one.
+
+### `Hubbado::Log::NotifyRollbar`
+
+Forwards a line worth an incident to Rollbar: `warn` as a warning, `error`, `fatal` and
+`unknown` as errors, and anything below a warning not at all.
+
+**Rollbar is not a dependency of this gem.** It is a development dependency, so nothing about
+installing `hubbado-log` installs Rollbar. A consumer that wants this handler puts `rollbar` in
+its own Gemfile and requires the handler itself:
+
+```ruby
+require "hubbado/log/notify_rollbar"
+
+Hubbado::Log.configuration do |config|
+  config.loggers = [Hubbado::Log::StderrLogger, Hubbado::Log::NotifyRollbar]
+end
+```
+
+The require raises `LoadError` at boot if Rollbar is absent, which is deliberate — the
+alternative is a `NameError` raised inside `log`, at the moment something is trying to report a
+failure, replacing the error being reported with a worse one.
+
+The handler configures nothing. Access token, environment and scrubbing are Rollbar's own
+`Rollbar.configure`, which the application owns.
+
+Everything the line carried travels as Rollbar's extra data, in **one** hash — Rollbar scans its
+arguments by type and keeps the last hash it is given, so a second one would silently displace
+the first:
+
+| The line has | Reaches the item as |
+|---|---|
+| an exception as its data | the exception itself, which Rollbar groups and traces on |
+| a hash as its data | those keys, stringified |
+| anything else as its data | a `data` key holding its `inspect` |
+| — | a `subject` key naming the class that logged it |
+| a stacktrace, with no exception | a `stacktrace` key |
+
+The handler's own keys are merged last, so a line cannot tell an item it came from a different
+class. A stacktrace is sent only when there is no exception, because Rollbar reads the backtrace
+off an exception itself.
+
+The message is sent as a String whatever it was — Rollbar matches its title by type, so anything
+else would leave the item with no title at all.
+
+Pass `notifier:` to record what was sent rather than send it, which is mainly how a spec reads it
+back.
+
 ## Level
 
 A message below the level reaches no handler.
 
 ```ruby
 Hubbado::Log.configuration do |config|
-  config.loggers = [MyStderrHandler]
+  config.loggers = [Hubbado::Log::StderrLogger]
   config.level = :debug
 end
 ```

data/hubbado-log.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "hubbado-log"
-  s.version = "1.4.1"
+  s.version = "1.5.0"
   s.summary = "Lightweight pluggable logging system"
 
   s.authors = ["Hubbado Devs"]
@@ -30,4 +30,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency "debug"
   s.add_development_dependency "hubbado-style"
   s.add_development_dependency "test_bench"
+
+  # Development only, deliberately. `hubbado/log/notify_rollbar` requires it, and nothing else
+  # in the gem does — so a consumer that never asks for that handler never installs Rollbar.
+  s.add_development_dependency "rollbar"
 end

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

@@ -0,0 +1,24 @@
+module Hubbado
+  class Log
+    module Controls
+      # Stands in for `Rails.logger`, recording the lines it was asked to write.
+      #
+      # It answers to the severities Rails' own logger answers to, and deliberately not to
+      # `trace`, which Rails has no method for. A handler passing the gem's lowest severity
+      # straight through raises here exactly as it would in a Rails application, rather than
+      # being quietly recorded and passing a spec.
+      class RailsLogger
+        SEVERITIES = %i[debug info warn error fatal unknown].freeze
+
+        def self.example = new
+
+        # Each entry is the severity it was written at and the text of it.
+        def lines = @lines ||= []
+
+        SEVERITIES.each do |severity|
+          define_method(severity) { |line| lines << [severity, line] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Hubbado
+  class Log
+    module Controls
+      # A class that takes a logger, which is what the handler controls attach to.
+      class Receiver
+        include Log::Dependency
+
+        def self.example = new
+
+        # One that has the attribute but no logger behind it, for the guard that refuses to
+        # attach to it. The Dependency module cannot produce this — it builds a logger on first
+        # read — so the shape has to be written out.
+        def self.without_logger
+          Class.new { attr_accessor :logger }.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Hubbado
+  class Log
+    module Controls
+      # Stands in for the Rollbar module, recording what it was handed rather than sending it.
+      # Every level Rollbar answers to is defined, so a handler notifying at a level it should
+      # have stayed quiet at is recorded and asserted against rather than raising.
+      class Rollbar
+        # Rollbar takes its arguments positionally and untyped, assigning each one it recognises
+        # over any earlier one of the same kind. So every reader here takes the **last** match,
+        # not the first: a notification is asserted on for what Rollbar would make of it, and a
+        # handler passing two of anything must lose the same one here that it loses there.
+        Notification = Struct.new(:level, :arguments) do
+          def message = arguments.grep(String).last
+
+          # `::Exception`, not `Exception` — this module has a control of that name, and a bare
+          # constant here resolves to it and matches nothing.
+          def exception = arguments.grep(::Exception).last
+
+          def extra = arguments.grep(Hash).last
+
+          def hashes = arguments.grep(Hash).length
+        end
+
+        LEVELS = %i[debug info warning warn error critical].freeze
+
+        def self.example = new
+
+        def notifications = @notifications ||= []
+
+        LEVELS.each do |level|
+          define_method(level) { |*arguments| notifications << Notification.new(level, arguments) }
+        end
+
+        # Without a level, whether anything was sent at all — which a spec asserting silence
+        # would otherwise have to infer from an attribute never having been set.
+        def notified?(level = nil)
+          return !notifications.empty? if level.nil?
+
+          notifications.any? { |notification| notification.level == level.to_s.to_sym }
+        end
+
+        # The most recent notification. Derived rather than assigned alongside `notifications`,
+        # so the two cannot disagree about which is the latest.
+        %i[level message exception extra].each do |field|
+          define_method(field) { notifications.last&.public_send(field) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Hubbado
+  class Log
+    module Controls
+      # What the logger synthesises for a line carrying no exception: `Kernel.caller`, joined
+      # by newlines. Recognisably a stack, and recognisably not any other string a spec asserts
+      # on.
+      module Stacktrace
+        def self.example
+          "lib/scanning.rb:14:in 'sweep'\nlib/cli.rb:3:in 'call'"
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log/controls.rb

@@ -1,7 +1,13 @@
 require_relative 'controls/data'
 require_relative 'controls/exception'
 require_relative 'controls/message'
+require_relative 'controls/stacktrace'
 require_relative 'controls/subject'
 
+require_relative 'controls/receiver'
+
 require_relative 'controls/log_handler'
 require_relative 'controls/logger'
+
+require_relative 'controls/rails_logger'
+require_relative 'controls/rollbar'

data/lib/hubbado/log/notify_rollbar.rb

@@ -0,0 +1,70 @@
+require 'rollbar'
+
+require_relative '../log'
+
+module Hubbado
+  class Log
+    # Forwards a log line worth an incident to Rollbar.
+    class NotifyRollbar < LogHandler
+      # Rollbar's own levels. It has none above error, so the two severities above `warn` share
+      # it, and anything below a warning is running commentary that reaches the handlers which
+      # print rather than this one.
+      LEVELS = { warn: :warn, error: :error, fatal: :error, unknown: :error }.freeze
+
+      def initialize(notifier: nil)
+        super()
+
+        @notifier = notifier
+      end
+
+      def log(subject, severity, message, data = nil, stacktrace = nil)
+        level = LEVELS[severity.to_sym]
+        return if level.nil?
+
+        error = data if data.is_a?(::Exception)
+
+        notifier.public_send(
+          level, *[error, title(message), extra(subject, data, stacktrace)].compact
+        )
+      end
+
+      private
+
+      # Read rather than stored, so a process that reconfigures Rollbar after the log system
+      # built its handlers is notified through what it configured.
+      def notifier = @notifier || ::Rollbar
+
+      # Rollbar matches its title by type: a message that is not a String is ignored, and the
+      # item arrives with no title at all rather than with a bad one.
+      def title(message) = message.to_s
+
+      # One hash, never two. Rollbar scans its arguments by type and keeps the last hash it
+      # finds, discarding any earlier one — so a line's own data and the fields added here have
+      # to arrive merged, or one of them silently never reaches the item.
+      #
+      # Built fresh every call for the same reason it is merged: Rollbar deletes a key from the
+      # hash it is given, and the caller still holds theirs.
+      #
+      # The handler's fields merge last. A call site names the record it is about, and an item
+      # that could be told its subject was something else would file under a class that never
+      # logged it.
+      def extra(subject, data, stacktrace)
+        extra = context(data).merge("subject" => subject)
+
+        return extra if stacktrace.nil? || data.is_a?(Exception)
+
+        extra.merge("stacktrace" => stacktrace)
+      end
+
+      # Rollbar matches a String to the message and an Exception to the exception, and ignores
+      # anything else it is handed. Data that is neither is named here rather than dropped.
+      def context(data)
+        case data
+          when nil, Exception then {}
+          when Hash then data.transform_keys(&:to_s)
+          else { "data" => data.inspect }
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log/rails_logger.rb

@@ -0,0 +1,46 @@
+require_relative '../log'
+
+module Hubbado
+  class Log
+    # Writes a log line into a Rails application's own log.
+    class RailsLogger < LogHandler
+      # Rails has no logger method below debug, so the gem's trace is written as one. A handler
+      # passing it straight through raises NoMethodError on the first trace line it is handed.
+      RAILS_SEVERITIES = { trace: :debug }.freeze
+
+      def initialize(rails_logger: nil)
+        super()
+
+        @rails_logger = rails_logger
+      end
+
+      def log(subject, severity, message, data = nil, stacktrace = nil)
+        rails_severity = RAILS_SEVERITIES.fetch(severity.to_sym, severity)
+
+        rails_logger.send(rails_severity, "#{subject}: #{message}")
+
+        details(data, stacktrace).each do |detail|
+          rails_logger.send(rails_severity, detail)
+        end
+      end
+
+      private
+
+      # Read rather than stored, because Rails replaces its logger during boot and a handler
+      # built before that would keep writing to the one it replaced.
+      def rails_logger = @rails_logger || ::Rails.logger
+
+      # A Rails log is read after the fact, and by machine as often as by a person, so the
+      # stacktrace is written whatever the severity — where a terminal withholds it below error
+      # to stay readable.
+      #
+      # An exception is one entry rather than two: its `full_message` carries the message that
+      # `inspect` would print, so writing both writes the message twice.
+      def details(data, stacktrace)
+        return [stacktrace || data.full_message] if data.is_a?(::Exception)
+
+        [data&.inspect, stacktrace].compact
+      end
+    end
+  end
+end

data/lib/hubbado/log/stderr_logger.rb

@@ -0,0 +1,54 @@
+require_relative '../log'
+
+module Hubbado
+  class Log
+    # Prints a log line where a person watching a run can see it.
+    class StderrLogger < LogHandler
+      # Where a stacktrace earns its space on a terminal. The logger synthesises one for `warn`
+      # too, but a warning is a condition to examine rather than a failure to trace, and its
+      # message already names the field and value — so a sweep that warns per row would bury
+      # itself in Ruby stack to solve a problem stderr does not have.
+      FAILURE_SEVERITIES = %i[error fatal unknown].freeze
+
+      def initialize(io: nil)
+        super()
+
+        @io = io
+      end
+
+      # One write, because a line and the detail under it belong together. Three writes let a
+      # second thread put its own line between them, and a stacktrace filed under the wrong
+      # message is worse than no stacktrace.
+      def log(subject, severity, message, data = nil, stacktrace = nil)
+        lines = ["#{severity.to_s.upcase} #{subject}: #{message}"]
+        lines << detail(data, stacktrace) unless data.nil?
+        lines << stacktrace if print_stacktrace?(severity, data, stacktrace)
+
+        io.puts(lines.join("\n"))
+      end
+
+      private
+
+      # Read rather than stored, so a process that rebinds $stderr after the log system built
+      # its handlers is written to rather than the stream it replaced.
+      def io = @io || $stderr
+
+      # An exception carries its own backtrace, and the logger has already rendered it into the
+      # stacktrace argument — so that string is reused rather than rendered a second time.
+      def detail(data, stacktrace)
+        return data.inspect unless data.is_a?(::Exception)
+
+        stacktrace || data.full_message
+      end
+
+      # An exception is excluded because its `full_message` is printed from the data above, so
+      # honouring the argument as well would print the backtrace twice.
+      def print_stacktrace?(severity, data, stacktrace)
+        return false if stacktrace.nil?
+        return false if data.is_a?(::Exception)
+
+        FAILURE_SEVERITIES.include?(severity.to_sym)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-log
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Hubbado Devs
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rollbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - devs@hubbado.com
 executables: []
@@ -97,11 +111,18 @@ files:
 - lib/hubbado/log/controls/log_handler.rb
 - lib/hubbado/log/controls/logger.rb
 - lib/hubbado/log/controls/message.rb
+- lib/hubbado/log/controls/rails_logger.rb
+- lib/hubbado/log/controls/receiver.rb
+- lib/hubbado/log/controls/rollbar.rb
+- lib/hubbado/log/controls/stacktrace.rb
 - lib/hubbado/log/controls/subject.rb
 - lib/hubbado/log/log.rb
 - lib/hubbado/log/log_handler.rb
 - lib/hubbado/log/logger.rb
 - lib/hubbado/log/logger/substitute.rb
+- lib/hubbado/log/notify_rollbar.rb
+- lib/hubbado/log/rails_logger.rb
+- lib/hubbado/log/stderr_logger.rb
 - lib/hubbado/log/tags.rb
 homepage: https://www.github.com/hubbado/hubbado-log
 licenses: