logsy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d9d026e66871c418c7315bbec120182f0aa3a2e4caa247e9fa533a4a6b99361
-  data.tar.gz: caf2ad615f13cd2f75954e43dfcab5d61e93ec40b11c004bf9723bd8c4736721
+  metadata.gz: be9d1c01334a5549c684e6e0807eb2f0b1b00f7d481b0862a0d0d005de31b81f
+  data.tar.gz: 993aadd7127a75825114c9cadb6db4ef211fcd1e582320661b73ba483653aed9
 SHA512:
-  metadata.gz: 9bed718fb7a7618cd420220579e7edd7ce92b44d46f538a0ef2459644014fc207febe0c09cc51a3b72624d083930dc78a37e00752bab2ef6fd34f4291c6677f0
-  data.tar.gz: 2e2d8bd7a250600dedbf8e704e87227cd5ff590c8f9fee39276a1a909b8b1973d51db5f09e6a415ccd375a5222b9bef87039958e80a9c44b3718d4c5724c7d05
+  metadata.gz: 4d48f08e5b3c2f13c14ac9f8d3983c46bbb7361785343912e9840b8652cef8f6d24e3e98726dcf97fa00b1473aa776f9c0c4418add83b5888d60d398f0d081a5
+  data.tar.gz: e420eec6c13c97386d41bfbd32d91f54511c137808ce486ce00518a00df09226e6055526e8957baad210903ad71011dfc0f99fd013393cdac747b2f5558b1471

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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

@@ -82,10 +82,33 @@ 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).
 
 For other job systems (Resque, GoodJob, custom), write your own middleware using the same pattern — Logsy's `[]=` / `[]` / `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:
+
+```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
 
 A regular log line:
@@ -123,6 +146,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:
@@ -184,6 +226,14 @@ 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
 end
 ```
 

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,13 +22,19 @@ 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
 
     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
       # 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

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/railtie.rb

@@ -1,12 +1,25 @@
 # 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).
   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
   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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logsy
-  VERSION = '0.2.0'
+  VERSION = '0.3.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)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: logsy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.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