logsy 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be9d1c01334a5549c684e6e0807eb2f0b1b00f7d481b0862a0d0d005de31b81f
-  data.tar.gz: 993aadd7127a75825114c9cadb6db4ef211fcd1e582320661b73ba483653aed9
+  metadata.gz: 980d9365473b25931ea00736958f1980b5872ec25901dbd09a58347f4eca8c70
+  data.tar.gz: 0646f18af7c441b599e61ec5dfb133268cf4d371594b8a08363c6511a7f758d8
 SHA512:
-  metadata.gz: 4d48f08e5b3c2f13c14ac9f8d3983c46bbb7361785343912e9840b8652cef8f6d24e3e98726dcf97fa00b1473aa776f9c0c4418add83b5888d60d398f0d081a5
-  data.tar.gz: e420eec6c13c97386d41bfbd32d91f54511c137808ce486ce00518a00df09226e6055526e8957baad210903ad71011dfc0f99fd013393cdac747b2f5558b1471
+  metadata.gz: 6687e938d72ff9054851a86f10cc7450046110d472a88043e125aef5b4c3797d236b9406b1c3645798cb8486b15614a1fc454aaa252cfd2ff2c39714e5a6221d
+  data.tar.gz: 6cd7238d880da15217483ecbaefe19f21f1bb2f6a591059b4a9feb3507e1b1942f21ec936b5af59ee5c35179d6d0efa22bada6e423b616bd2bf0fe6ae0782f78

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.4.0] - 2026-06-29
+
+- **Sidekiq middleware is now auto-registered** — the Railtie calls `Logsy::SidekiqMiddleware.install!` for you once Sidekiq is loaded, so `request_id` (and any `job_propagated_keys`) propagates into jobs with zero per-app wiring. No more `require 'logsy/sidekiq_middleware'` + three `chain.add` lines in `config/initializers/sidekiq.rb`. Opt out with `config.auto_register_sidekiq_middleware = false`. The registration initializer runs `after: :load_config_initializers`, so it works even when the app uses `gem 'sidekiq', require: false`.
+- **`Logsy::SidekiqMiddleware.install!(sidekiq = ::Sidekiq)`**: new single entry point that registers the client + server middleware (client on both client and server chains, server on the server chain). Non-Rails apps now wire Sidekiq with one line instead of two config blocks. Idempotent — Sidekiq's `Chain#add` replaces, so it's safe alongside a stray manual registration.
+- **`Logsy.tag(**tags)`**: set several tags at once (`Logsy.tag(user_id: u.id, plan: 'pro')`), with the same String coercion as `Logsy[]=`.
+- **`Logsy.with(**tags) { ... }`**: set tags for the duration of a block and restore the previous values afterwards (deleting keys that were unset before), even if the block raises. Scopes context to a unit of work without leaking it — useful in service objects, rake tasks, and threads the Rails executor / Sidekiq middleware don't reset. Returns the block's value.
+- `Configuration`: new `auto_register_sidekiq_middleware` (default `true`).
+- **Performance** (`JsonFormatter`): no behaviour or output change, just less work on the hot path —
+  - Hash (wide-event) messages now skip the caller-location stack walk entirely. They're logged from a Logsy hook frame with no app frame to attribute, so the walk only ever scanned the full stack to emit no `file` anyway. Cuts a wide-event line with `include_caller_location` on from ~6.0µs to ~2.5µs (~2.4x) — and these fire once per request and once per job.
+  - The ANSI-code strip on String messages is now guarded by a cheap `include?("\e")` byte scan, so the common plain log line skips the regex and its allocation (~2.3x faster on that step).
+  - `app_root` is computed once per log line and threaded through the frame walk instead of being rebuilt for every stack frame inspected, removing an allocation per frame on the caller-location path.
+
 ## [0.3.0] - 2026-06-21
 
 - **`Logsy::JobHooks`**: new ActiveJob concern — the background-job counterpart of `ControllerHooks`. Emits one wide event (`event: "job"`) when each job finishes, carrying `job_class`, `queue`, `active_job_id`, `executions`, `duration_ms`, `status` (`"ok"`/`"error"`), `error`, and every Logsy tag set during the run. Emitted even when the job raises (then re-raised). Override `logsy_job_summary_extras` to add fields. Job arguments are deliberately omitted — ActiveJob already logs them at enqueue time, correlatable by `active_job_id`.

data/README.md

@@ -2,7 +2,7 @@
 
 Tagged structured logging for Rails apps. JSON output, one line per log call.
 
-Logsy gives you **one wide JSON event per request** plus **correlated breadcrumb logs**, all tagged with whatever per-request context you set via `Logsy[:key] = value`. Tags propagate across background jobs (Sidekiq middleware bundled). Where you ship the JSON is your call — Logsy just writes structured lines to stdout.
+Logsy gives you **one wide JSON event per request** plus **correlated breadcrumb logs**, all tagged with whatever per-request context you set via `Logsy[:key] = value`. Tags propagate across background jobs (Sidekiq middleware auto-wired — zero config). Where you ship the JSON is your call — Logsy just writes structured lines to stdout.
 
 ## Installation
 
@@ -53,26 +53,14 @@ end
 
 That's it. No `Current` model to define, no attribute declarations — just key/value.
 
-### 5. (Optional) Background job propagation
+### 5. Background job propagation — automatic for Sidekiq
 
-If you use Sidekiq:
+If you use Sidekiq, there's **nothing to do**: the Railtie registers the bundled middleware for you once Sidekiq is loaded, so `request_id` (and any other `job_propagated_keys`) flows from the enqueueing request into the job — and on into any jobs that job enqueues.
 
-```ruby
-# config/initializers/sidekiq.rb
-require 'logsy/sidekiq_middleware'
-
-Sidekiq.configure_client do |config|
-  config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
-end
-
-Sidekiq.configure_server do |config|
-  config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
-  config.server_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Server) }
-end
-```
+Want to propagate more than `request_id`? That's the only thing you'd configure:
 
 ```ruby
-# config/initializers/logsy.rb (optional — only if you want to propagate more than request_id)
+# config/initializers/logsy.rb (optional)
 Logsy.configure do |c|
   c.job_propagated_keys = %i[request_id user_id tenant_id]
 end
@@ -84,7 +72,14 @@ The bundled middleware:
 
 Anything the job code writes via `Logsy[:foo] = bar` while running shows up on every log line emitted during the job. Tags reset automatically after each job (no leak between jobs sharing a worker thread). The server middleware also sets `Logsy[:job_class]` (the wrapped ActiveJob class name, e.g. `"GenerateEodJob"`, falling back to the worker class for plain Sidekiq jobs).
 
-For other job systems (Resque, GoodJob, custom), write your own middleware using the same pattern — Logsy's `[]=` / `[]` / `tags` / `reset` API is generic.
+To wire it up yourself (non-Rails, or after opting out with `config.auto_register_sidekiq_middleware = false`) it's a one-liner:
+
+```ruby
+require 'logsy/sidekiq_middleware'
+Logsy::SidekiqMiddleware.install!   # registers client + server middleware
+```
+
+For other job systems (Resque, GoodJob, custom), write your own middleware using the same pattern — Logsy's `[]=` / `[]` / `tag` / `with` / `tags` / `reset` API is generic.
 
 ### 6. Job wide event — automatic
 
@@ -175,14 +170,24 @@ Notes on the fields:
 ## API reference
 
 ```ruby
-Logsy[:user_id] = 'u-1'   # set a tag
-Logsy[:user_id]            # read it
-Logsy.tags                 # all tags as a hash
-Logsy.reset                # clear all tags (the controller/middleware do this for you)
+Logsy[:user_id] = 'u-1'              # set a tag
+Logsy[:user_id]                       # read it
+Logsy.tag(user_id: 'u-1', plan: 'pro') # set several at once
+Logsy.with(order_id: 'o-9') { ... }    # set for the block, restore afterwards
+Logsy.tags                            # all tags as a hash
+Logsy.reset                           # clear all tags (the controller/middleware do this for you)
 ```
 
 Symbol and string keys are equivalent — `Logsy['user_id']` and `Logsy[:user_id]` access the same slot.
 
+`Logsy.with` scopes tags to a block and restores the prior values on exit (even if the block raises) — handy in service objects, rake tasks, or threads the Rails executor / Sidekiq middleware don't reset for you:
+
+```ruby
+Logsy.with(order_id: order.id) do
+  process(order)   # every log line here carries order_id; gone afterwards
+end
+```
+
 ## Customizing the wide event
 
 Override `logsy_request_summary_extras` in your controller to add fields:
@@ -234,6 +239,12 @@ Logsy.configure do |c|
   # so jobs emit summaries with no setup). Set false to wire it yourself.
   # Default: true
   c.auto_include_job_hooks = true
+
+  # Register the bundled Sidekiq middleware automatically when Sidekiq is
+  # loaded (the Railtie does this so request_id propagates into jobs with
+  # no setup). Set false to call Logsy::SidekiqMiddleware.install! yourself.
+  # Default: true
+  c.auto_register_sidekiq_middleware = true
 end
 ```
 
@@ -251,7 +262,7 @@ Logsy fills the gap: a small, dictionary-style API (`Logsy[:foo] = bar`) plus a
 
 ```bash
 bundle install
-bundle exec rspec       # 34 specs
+bundle exec rspec       # 64 specs
 bundle exec rubocop     # lint
 ```
 

data/lib/logsy/configuration.rb

@@ -23,7 +23,7 @@ module Logsy
     attr_accessor :job_propagated_keys, :ignored_caller_paths,
                   :include_caller_location, :request_summary_event_name,
                   :job_summary_event_name, :caller_location_max_depth,
-                  :auto_include_job_hooks
+                  :auto_include_job_hooks, :auto_register_sidekiq_middleware
 
     def initialize
       @job_propagated_keys        = [:request_id]
@@ -35,11 +35,16 @@ module Logsy
       # into ActiveJob::Base, so every job emits a summary wide event with
       # no per-app setup. Set to false to opt out and include it manually.
       @auto_include_job_hooks     = true
+      # When true (the default), the Railtie registers the bundled Sidekiq
+      # middleware (client + server) for you when Sidekiq is loaded, so
+      # request_id and friends propagate into jobs with no per-app wiring.
+      # Set to false to register them yourself (or not at all).
+      @auto_register_sidekiq_middleware = true
       # How many stack frames to inspect before giving up on attributing
       # the log line to app code. App frames sit within a few dozen frames
       # of the logger; framework-only lines (no app frame at all) would
       # otherwise pay a full walk of a 100+ deep Rails stack on every line.
-      @caller_location_max_depth  = 64
+      @caller_location_max_depth = 64
     end
   end
 end

data/lib/logsy/json_formatter.rb

@@ -42,7 +42,11 @@ module Logsy
         level: severity
       }
 
-      add_caller_location!(payload) if Logsy.configuration.include_caller_location
+      # Hash messages are structured wide-event emissions from our own
+      # ControllerHooks/JobHooks. They're logged from a logsy frame with no
+      # app frame above to attribute, so the caller walk only ever scans the
+      # full stack to emit no :file — skip it (output is identical either way).
+      add_caller_location!(payload) if Logsy.configuration.include_caller_location && !message.is_a?(::Hash)
       merge_context!(payload)
       merge_message!(payload, message)
 
@@ -54,10 +58,11 @@ module Logsy
     private
 
     def add_caller_location!(payload)
-      location = find_user_frame
+      root = app_root # computed once per line, not rebuilt for every frame inspected
+      location = find_user_frame(root)
       return unless location
 
-      payload[:file] = "#{relative_path(location.path)}:#{location.lineno}"
+      payload[:file] = "#{relative_path(location.path, root)}:#{location.lineno}"
     end
 
     # Walk the stack in small batches instead of capturing it all at once:
@@ -66,14 +71,14 @@ module Logsy
     # capturing everything costs ~3x more per log line. The walk is capped
     # at caller_location_max_depth so framework-only lines (no app frame
     # anywhere) don't pay for a full-stack scan either.
-    def find_user_frame
+    def find_user_frame(root)
       start = 2 # skip find_user_frame and add_caller_location!
       limit = start + Logsy.configuration.caller_location_max_depth
       while start < limit
         batch = caller_locations(start, [FRAME_BATCH_SIZE, limit - start].min)
         return nil if batch.nil? || batch.empty?
 
-        batch.each { |loc| return loc if user_frame?(loc.path) }
+        batch.each { |loc| return loc if user_frame?(loc.path, root) }
         return nil if batch.size < FRAME_BATCH_SIZE
 
         start += FRAME_BATCH_SIZE
@@ -85,10 +90,10 @@ module Logsy
     # stdlib, or logging machinery. With an app root (Rails), only frames
     # under it count (vendored gems under root excluded); without one,
     # any non-gem frame counts.
-    def user_frame?(path)
+    def user_frame?(path, root)
       return false if Logsy.configuration.ignored_caller_paths.any? { |pattern| path.match?(pattern) }
 
-      if (root = app_root)
+      if root
         path.start_with?(root) && !path.include?('/vendor/bundle/')
       else
         !gem_frame?(path)
@@ -105,8 +110,7 @@ module Logsy
       defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? "#{Rails.root}/" : nil
     end
 
-    def relative_path(path)
-      root = app_root
+    def relative_path(path, root)
       return path unless root && path.start_with?(root)
 
       path[root.length..]
@@ -123,7 +127,10 @@ module Logsy
     def merge_message!(payload, message)
       case message
       when ::String
-        payload[:msg] = message.gsub(ANSI_ESCAPE, '').strip
+        # Only ActiveRecord SQL lines carry ANSI codes; skip the regex (and
+        # its allocation) on the common plain line with a cheap byte scan.
+        cleaned = message.include?("\e") ? message.gsub(ANSI_ESCAPE, '') : message
+        payload[:msg] = cleaned.strip
       when ::Hash
         message.each { |k, v| payload[k.to_sym] = v }
       when ::Exception

data/lib/logsy/railtie.rb

@@ -8,6 +8,8 @@ module Logsy
   #   that the "Started GET ..." line is already tagged.
   # - Includes Logsy::JobHooks into ActiveJob::Base so every job emits a
   #   summary wide event (disable via config.auto_include_job_hooks = false).
+  # - Registers the bundled Sidekiq middleware when Sidekiq is loaded
+  #   (disable via config.auto_register_sidekiq_middleware = false).
   class Railtie < ::Rails::Railtie
     initializer 'logsy.insert_rack_middleware' do |app|
       app.middleware.insert_after(ActionDispatch::RequestId, Logsy::RackMiddleware)
@@ -21,5 +23,16 @@ module Logsy
         include(Logsy::JobHooks) if Logsy.configuration.auto_include_job_hooks
       end
     end
+
+    # Runs after config/initializers so it sees Sidekiq even when the app
+    # uses `gem 'sidekiq', require: false` and loads it in an initializer.
+    # Registering here still takes effect: Sidekiq reads its middleware
+    # chains when jobs are enqueued/run, which is always after boot.
+    initializer 'logsy.register_sidekiq_middleware', after: :load_config_initializers do
+      next unless Logsy.configuration.auto_register_sidekiq_middleware && defined?(::Sidekiq)
+
+      require 'logsy/sidekiq_middleware'
+      Logsy::SidekiqMiddleware.install!
+    end
   end
 end

data/lib/logsy/sidekiq_middleware.rb

@@ -4,18 +4,36 @@ require 'logsy/sidekiq_middleware/client'
 require 'logsy/sidekiq_middleware/server'
 
 module Logsy
-  # Sidekiq middleware namespace. Require this file (or rely on a Rails
-  # railtie) to make {Client} and {Server} available, then register them
-  # with Sidekiq:
+  # Sidekiq middleware namespace.
   #
-  #   Sidekiq.configure_client do |config|
-  #     config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
-  #   end
+  # In a Rails app there is nothing to do: the Railtie calls {install!} for
+  # you once Sidekiq is loaded (opt out with
+  # `config.auto_register_sidekiq_middleware = false`).
   #
-  #   Sidekiq.configure_server do |config|
-  #     config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
-  #     config.server_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Server) }
-  #   end
+  # Outside Rails — or after opting out — require this file and register the
+  # middleware with a single call:
+  #
+  #   require 'logsy/sidekiq_middleware'
+  #   Logsy::SidekiqMiddleware.install!
   module SidekiqMiddleware
+    # Registers the bundled middleware with Sidekiq:
+    #   - Client on the client chain (web/console enqueues a job)
+    #   - Client on the server's client chain (a running job enqueues another)
+    #   - Server on the server chain (a worker runs a job)
+    #
+    # Idempotent: Sidekiq's Chain#add replaces an existing entry, so calling
+    # this twice (e.g. auto-registration plus a stray manual call) won't
+    # duplicate the middleware. `sidekiq` defaults to the ::Sidekiq constant
+    # and is injectable for testing.
+    def self.install!(sidekiq = ::Sidekiq)
+      sidekiq.configure_client do |config|
+        config.client_middleware { |chain| chain.add(Client) }
+      end
+
+      sidekiq.configure_server do |config|
+        config.client_middleware { |chain| chain.add(Client) }
+        config.server_middleware { |chain| chain.add(Server) }
+      end
+    end
   end
 end

data/lib/logsy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logsy
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/logsy.rb

@@ -32,6 +32,35 @@ module Logsy
       Store.tags[key.to_sym] = value&.to_s
     end
 
+    # Set several tags at once. Keyword sugar over repeated `Logsy[]=`,
+    # so the same String coercion applies. Returns the given tags.
+    #
+    #   Logsy.tag(user_id: user.id, order_id: order.id)
+    def tag(**tags)
+      tags.each { |key, value| self[key] = value }
+      tags
+    end
+
+    # Set tags for the duration of the block, then restore the previous
+    # values (deleting keys that were unset before). Use to scope context
+    # to a unit of work without leaking it to whatever runs next on the
+    # same thread/fiber — handy in service objects, rake tasks, or threads
+    # the Rails executor / Sidekiq middleware don't reset for you.
+    #
+    #   Logsy.with(order_id: order.id) do
+    #     process(order)   # every log line here carries order_id
+    #   end
+    #
+    # Returns the block's value.
+    def with(**tags)
+      keys  = tags.keys.map(&:to_sym)
+      saved = keys.to_h { |key| [key, Store.tags[key]] }
+      tag(**tags)
+      yield
+    ensure
+      saved.each { |key, value| value.nil? ? Store.tags.delete(key) : Store.tags[key] = value }
+    end
+
     # All tags currently set, as a hash. Used by the formatter on every
     # log line; consumers can call it for debugging.
     def tags

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logsy
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ruby_is_love