logsy 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d9d026e66871c418c7315bbec120182f0aa3a2e4caa247e9fa533a4a6b99361
-  data.tar.gz: caf2ad615f13cd2f75954e43dfcab5d61e93ec40b11c004bf9723bd8c4736721
+  metadata.gz: 980d9365473b25931ea00736958f1980b5872ec25901dbd09a58347f4eca8c70
+  data.tar.gz: 0646f18af7c441b599e61ec5dfb133268cf4d371594b8a08363c6511a7f758d8
 SHA512:
-  metadata.gz: 9bed718fb7a7618cd420220579e7edd7ce92b44d46f538a0ef2459644014fc207febe0c09cc51a3b72624d083930dc78a37e00752bab2ef6fd34f4291c6677f0
-  data.tar.gz: 2e2d8bd7a250600dedbf8e704e87227cd5ff590c8f9fee39276a1a909b8b1973d51db5f09e6a415ccd375a5222b9bef87039958e80a9c44b3718d4c5724c7d05
+  metadata.gz: 6687e938d72ff9054851a86f10cc7450046110d472a88043e125aef5b4c3797d236b9406b1c3645798cb8486b15614a1fc454aaa252cfd2ff2c39714e5a6221d
+  data.tar.gz: 6cd7238d880da15217483ecbaefe19f21f1bb2f6a591059b4a9feb3507e1b1942f21ec936b5af59ee5c35179d6d0efa22bada6e423b616bd2bf0fe6ae0782f78

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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`.
+- **Auto-wiring**: the Railtie now auto-includes `Logsy::JobHooks` into `ActiveJob::Base` (via `ActiveSupport.on_load(:active_job)`), so jobs emit summaries with zero per-app setup. Opt out with `config.auto_include_job_hooks = false` and include it manually. (Non-Rails ActiveJob users include it themselves.)
+- `SidekiqMiddleware::Server`: now also sets `Logsy[:job_class]` (from `job['wrapped']`, the ActiveJob class name, falling back to `job['class']` for plain Sidekiq workers), so every job log line — including ActiveJob's own "Performing ..." — is tagged with the class, not just the `job_id`/jid.
+- `Configuration`: new `job_summary_event_name` (default `"job"`), mirroring `request_summary_event_name`; new `auto_include_job_hooks` (default `true`).
+- **Default `ignored_caller_paths`** now also skips `app/middleware` / `app/middlewares` frames — Rack middlewares sit in every request's stack and would otherwise be picked as the "app frame" for lines emitted below them. (Previously each app had to add this itself.)
+
 ## [0.2.0] - 2026-06-07
 
 - **`Logsy::RackMiddleware` + Railtie**: request_id is now captured in Rack middleware (auto-inserted after `ActionDispatch::RequestId`) instead of a controller `before_action`. Every log line of a request now carries `request_id` — including "Started GET ..." and "Processing by ..." which a controller callback fires too late to tag. Falls back to `X-Request-Id`, then a generated UUID, so the tag is always present.

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
@@ -82,9 +70,39 @@ The bundled middleware:
 - **Client side**: when a job is enqueued, copies the configured tags from `Logsy[]` into the job payload
 - **Server side**: when the job runs, sets those tags back in `Logsy[]` AND sets `Logsy[:job_id] = job['jid']` automatically
 
-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).
+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).
+
+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
+
+`Logsy::JobHooks` is the background-job counterpart of `ControllerHooks`. In a Rails app there's **nothing to do**: the Railtie auto-includes it into `ActiveJob::Base`, so every job emits one wide event with `event: "job"` when it finishes, carrying `job_class`, `queue`, `active_job_id`, `executions` (attempt count), `duration_ms`, `status` (`"ok"`/`"error"`), any `error` class/message — plus every tag set during the run (`job_id`/jid, propagated `request_id`, and anything you wrote via `Logsy[:key] = value`). It's emitted even when the job raises (then re-raised). Job arguments are deliberately omitted — ActiveJob already logs them at enqueue time, correlatable by `active_job_id`.
+
+Override `logsy_job_summary_extras` in a job to add fields:
+
+```ruby
+class SomeJob < ApplicationJob
+  private
+
+  def logsy_job_summary_extras
+    { tenant: account_id }
+  end
+end
+```
+
+To opt out of the auto-include and wire it yourself:
 
-For other job systems (Resque, GoodJob, custom), write your own middleware using the same pattern — Logsy's `[]=` / `[]` / `tags` / `reset` API is generic.
+```ruby
+Logsy.configure { |c| c.auto_include_job_hooks = false }
+# then `include Logsy::JobHooks` in the jobs you want
+```
 
 ## What it looks like in your logs
 
@@ -123,6 +141,25 @@ The wide event at end of request:
 }
 ```
 
+The wide event at end of a job (with `Logsy::JobHooks`):
+
+```json
+{
+  "ts":"2026-05-02T10:00:00.250Z",
+  "level":"INFO",
+  "event":"job",
+  "job_class":"SpgReverseTransactionJob",
+  "queue":"default",
+  "active_job_id":"09fe3546-211b-45cf-9434-fb2689c580c5",
+  "executions":1,
+  "duration_ms":842.10,
+  "status":"ok",
+  "job_id":"402797cb0cfc9324cc10cc7f",
+  "transaction_id":"019c0440-a797-7479-8d3a-4260ba896681",
+  "rrn":"123456789012"
+}
+```
+
 Search your log store by `message_id` to find every request from that message. Pivot from a request's `request_id` to see every breadcrumb log line emitted while it ran.
 
 Notes on the fields:
@@ -133,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:
@@ -184,6 +231,20 @@ Logsy.configure do |c|
 
   # The "event" name on the request summary. Default: "request"
   c.request_summary_event_name = 'http_request'
+
+  # The "event" name on the job summary (Logsy::JobHooks). Default: "job"
+  c.job_summary_event_name = 'background_job'
+
+  # Auto-include Logsy::JobHooks into ActiveJob::Base (the Railtie does this
+  # 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
 ```
 
@@ -201,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

@@ -8,7 +8,12 @@ module Logsy
       %r{/lograge/},
       %r{/sprockets/},
       %r{/quiet_assets/},
-      %r{/lib/logsy/}
+      %r{/lib/logsy/},
+      # Rack middlewares sit in every request's call stack, so without this
+      # they'd be picked as the "app frame" for lines emitted below them
+      # (e.g. "Started GET ..." would be attributed to a health_check
+      # middleware). Matches app/middleware and app/middlewares.
+      %r{/app/middlewares?/}
     ].freeze
 
     # Tag keys that should be carried across job boundaries (e.g. when a
@@ -17,18 +22,29 @@ module Logsy
     # specific (Logsy ships one for Sidekiq).
     attr_accessor :job_propagated_keys, :ignored_caller_paths,
                   :include_caller_location, :request_summary_event_name,
-                  :caller_location_max_depth
+                  :job_summary_event_name, :caller_location_max_depth,
+                  :auto_include_job_hooks, :auto_register_sidekiq_middleware
 
     def initialize
       @job_propagated_keys        = [:request_id]
       @ignored_caller_paths       = DEFAULT_IGNORED_CALLER_PATHS.dup
       @include_caller_location    = true
       @request_summary_event_name = 'request'
+      @job_summary_event_name     = 'job'
+      # When true (the default), the Railtie auto-includes Logsy::JobHooks
+      # 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/job_hooks.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Logsy
+  # Include into your ApplicationJob (or specific jobs) to emit a single
+  # "wide event" log line when the job finishes — carrying the job class,
+  # queue, ActiveJob id, attempt count, duration_ms, status/error, and
+  # every Logsy tag set during the run (job_id/jid, propagated request_id,
+  # and anything the job wrote via `Logsy[:key] = value`, e.g. an RRN).
+  #
+  # This is the background-job counterpart of Logsy::ControllerHooks.
+  # Per-job context capture (job_id, job_class, propagated tags) lives in
+  # Logsy::SidekiqMiddleware::Server — not here — so even ActiveJob's own
+  # "Performing ..." line is already tagged before this hook runs.
+  #
+  # Usage:
+  #
+  #   class ApplicationJob < ActiveJob::Base
+  #     include Logsy::JobHooks
+  #   end
+  #
+  # Override `logsy_job_summary_extras` to add custom fields to the event:
+  #
+  #   def logsy_job_summary_extras
+  #     { tenant: account_id }
+  #   end
+  #
+  # Job arguments are intentionally omitted — ActiveJob already logs them
+  # once at enqueue time ("Enqueued ... with arguments: ..."), correlatable
+  # by active_job_id, so repeating them here would only duplicate (and risk
+  # leaking) payload data.
+  module JobHooks
+    extend ActiveSupport::Concern
+
+    included do
+      around_perform :_logsy_emit_job_summary
+    end
+
+    private
+
+    def _logsy_emit_job_summary
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      error = nil
+      yield
+    rescue StandardError => e
+      error = e
+      raise
+    ensure
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+      payload = {
+        event: Logsy.configuration.job_summary_event_name,
+        job_class: self.class.name,
+        queue: queue_name,
+        active_job_id: job_id,
+        executions:,
+        duration_ms:,
+        status: error ? 'error' : 'ok',
+        error: error && "#{error.class}: #{error.message}"
+      }.merge(logsy_job_summary_extras).compact
+
+      Rails.logger.info(payload)
+    end
+
+    # Override in subclasses to add fields to the job summary wide event.
+    def logsy_job_summary_extras
+      {}
+    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

@@ -1,12 +1,38 @@
 # frozen_string_literal: true
 
 module Logsy
-  # Inserts the request-id capturing middleware right after
-  # ActionDispatch::RequestId, before Rails::Rack::Logger — early enough
-  # that the "Started GET ..." line is already tagged.
+  # Wires Logsy into Rails with zero per-app setup:
+  #
+  # - Inserts the request-id capturing middleware right after
+  #   ActionDispatch::RequestId, before Rails::Rack::Logger — early enough
+  #   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)
     end
+
+    initializer 'logsy.include_job_hooks' do
+      # Fires when ActiveJob::Base loads (eager load in production, first
+      # reference in development) — after config/initializers have run, so
+      # an app's auto_include_job_hooks = false is respected.
+      ActiveSupport.on_load(:active_job) do
+        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/server.rb

@@ -4,14 +4,17 @@ module Logsy
   module SidekiqMiddleware
     # Server-side middleware: reads propagated tags back from the job
     # payload, sets them on the per-job Logsy store, sets job_id from
-    # Sidekiq's `jid`, and resets the store after the job runs (even on
-    # error) so tags don't leak between jobs sharing a worker thread.
+    # Sidekiq's `jid` and job_class from the worker (the wrapped ActiveJob
+    # class name when run through ActiveJob), and resets the store after the
+    # job runs (even on error) so tags don't leak between jobs sharing a
+    # worker thread.
     #
     # Anything the job code writes via `Logsy[:foo] = bar` while running
     # will appear on every log line emitted during the job.
     class Server
       def call(_worker_instance, job, _queue)
         Logsy[:job_id] = job['jid']
+        Logsy[:job_class] = job['wrapped'] || job['class']
         Logsy.configuration.job_propagated_keys.each do |key|
           value = job[key.to_s]
           Logsy[key] = value if value

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.2.0'
+  VERSION = '0.4.0'
 end

data/lib/logsy.rb

@@ -5,6 +5,7 @@ require 'logsy/store'
 require 'logsy/configuration'
 require 'logsy/json_formatter'
 require 'logsy/controller_hooks'
+require 'logsy/job_hooks'
 require 'logsy/rack_middleware'
 require 'logsy/railtie' if defined?(Rails::Railtie)
 
@@ -31,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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ruby_is_love
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,7 @@ files:
 - lib/logsy.rb
 - lib/logsy/configuration.rb
 - lib/logsy/controller_hooks.rb
+- lib/logsy/job_hooks.rb
 - lib/logsy/json_formatter.rb
 - lib/logsy/rack_middleware.rb
 - lib/logsy/railtie.rb