forge_ops_tracker 0.2.1 → 0.7.0

data/lib/forge_ops_tracker/infrastructure_metric_buffer.rb

@@ -0,0 +1,69 @@
+require "thread"
+
+module ForgeOpsTracker
+  # Collects individual ForgeOpsTracker.capture_infrastructure_metric readings in-process and
+  # periodically flushes them as one batch, same shape as MetricBuffer (a sibling class, not a
+  # shared base -- this gem keeps SessionFlusher/PerformanceFlusher as separate, independently-
+  # readable classes despite their own similar shape too, and these two follow that precedent).
+  # Its main real caller is a short-lived cron/script process that exits right after a handful of
+  # capture calls, so the at_exit flush below is what actually matters in practice; the periodic
+  # background-thread timer still runs for a long-lived process that chooses to call this
+  # continuously instead, but rarely gets the chance to fire in the cron case.
+  class InfrastructureMetricBuffer
+    def initialize(configuration, client: Client.new(configuration))
+      @configuration = configuration
+      @client = client
+      @mutex = Mutex.new
+      @entries = []
+      @thread = nil
+
+      at_exit { flush }
+    end
+
+    def record(metric_name:, value:, hostname:)
+      ensure_worker_started
+
+      @mutex.synchronize do
+        @entries << { metric_name: metric_name, value: value, hostname: hostname, recorded_at: Time.now.utc.iso8601 }
+      end
+    end
+
+    # Same reset-on-success/keep-on-failure contract as MetricBuffer#flush; see that class's own
+    # comment for the accepted race this shares with it.
+    def flush
+      snapshot = nil
+
+      @mutex.synchronize do
+        return if @entries.empty?
+        snapshot = @entries
+      end
+
+      return unless client.deliver_infrastructure_metrics(snapshot)
+
+      @mutex.synchronize { @entries = [] }
+    end
+
+    private
+      attr_reader :configuration, :client
+
+      def ensure_worker_started
+        return if @thread&.alive?
+
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @thread = Thread.new { run }
+          @thread.abort_on_exception = false
+        end
+      end
+
+      def run
+        loop do
+          sleep configuration.infrastructure_metric_flush_interval
+          flush
+        rescue StandardError => e
+          configuration.logger&.debug { "[ForgeOpsTracker] infrastructure metric flush thread error: #{e.class}: #{e.message}" }
+        end
+      end
+  end
+end

data/lib/forge_ops_tracker/integrations/net_http.rb

@@ -0,0 +1,32 @@
+module ForgeOpsTracker
+  module Integrations
+    module NetHTTP
+      # Times every outbound Net::HTTP call, applied once via Net::HTTP.prepend(Timing) from
+      # Railtie. Ruby's standard library has no ActiveSupport::Notifications instrumentation of
+      # its own for outbound HTTP the way it does for ActiveRecord/ActionController, so wrapping
+      # #request directly is the only hook available; most other HTTP client libraries in the Ruby
+      # ecosystem (Faraday's own net_http adapter, HTTParty, RestClient) ultimately call through
+      # Net::HTTP too, so this covers those as a side effect without needing a wrapper per library.
+      #
+      # transaction_name is "<HTTP method> <host>", not the full URL: a request's own path or
+      # query string could carry an id or a token, the same low-cardinality/no-secrets-in-a-label
+      # reasoning every other transaction_name in this system already follows.
+      module Timing
+        # The guard (return super unless ...) skips timing, but the ensure block below still runs
+        # on every exit path regardless, same as any ensure; start staying nil is what actually
+        # skips recording there, not a second guard duplicating this one.
+        def request(req, body = nil, &block)
+          return super unless ForgeOpsTracker.configuration.track_performance && ForgeOpsTracker.configuration.enabled?
+
+          start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          super
+        ensure
+          if start
+            duration_ms = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start) * 1000.0
+            Railtie.performance_flusher.record(transaction_name: "#{req.method} #{address}", duration_ms: duration_ms, kind: "http")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forge_ops_tracker/integrations/puma.rb

@@ -0,0 +1,55 @@
+module ForgeOpsTracker
+  module Integrations
+    module Puma
+      # Reports Puma's own backlog/running-threads/pool-capacity as gauge-style infrastructure
+      # metrics on a periodic timer (see PeriodicPoller). Only ever loaded when Puma is already
+      # present (checked with defined? in Railtie).
+      #
+      # Puma.stats_hash's own shape genuinely differs by deployment mode, confirmed directly
+      # against Puma 6.6.1's real source rather than assumed: single-mode (Puma::Single, no
+      # `workers` config) has backlog/running/pool_capacity at the top level (Server#stats merged
+      # with ThreadPool#stats); clustered mode (Puma::Cluster) has none of those at the top level
+      # at all, only a worker_status array, one entry per forked worker, each carrying its own
+      # last_status hash with the identical three keys (parsed from that worker's own periodic
+      # IPC ping, see Puma::Cluster::WorkerHandle's own STATUS_PATTERN), summed across workers
+      # here for one whole-process reading, rather than reported per worker, since ForgeOps'
+      # infrastructure dataset already aggregates by hostname, not by worker index. Puma.stats_object
+      # is set unconditionally by Puma::Launcher on every normal boot (not just when a control/
+      # stats app is configured), so Puma.stats_hash is populated by the time this ever runs; still
+      # guarded against nil/an unrecognized shape, both because that wiring could change in a
+      # future Puma version and because this must never be the thing that crashes a poll tick.
+      class StatsReporter
+        def self.start(configuration: ForgeOpsTracker.configuration)
+          return unless configuration.track_performance && configuration.enabled?
+
+          PeriodicPoller.start(configuration.gauge_poll_interval, logger: configuration.logger) { new.report }
+        end
+
+        def report
+          stats = ::Puma.stats_hash
+          return unless stats
+
+          if stats[:backlog] && stats[:running]
+            report_metrics(stats[:backlog], stats[:running], stats[:pool_capacity])
+          elsif stats[:worker_status]
+            statuses = stats[:worker_status].filter_map { |worker| worker[:last_status] }.reject(&:empty?)
+            return if statuses.empty?
+
+            report_metrics(
+              statuses.sum { |s| s[:backlog] || 0 },
+              statuses.sum { |s| s[:running] || 0 },
+              statuses.sum { |s| s[:pool_capacity] || 0 }
+            )
+          end
+        end
+
+        private
+          def report_metrics(backlog, running, pool_capacity)
+            ForgeOpsTracker.capture_infrastructure_metric("puma.backlog", value: backlog)
+            ForgeOpsTracker.capture_infrastructure_metric("puma.running_threads", value: running)
+            ForgeOpsTracker.capture_infrastructure_metric("puma.pool_capacity", value: pool_capacity)
+          end
+      end
+    end
+  end
+end

data/lib/forge_ops_tracker/integrations/sidekiq.rb

@@ -0,0 +1,69 @@
+# Sidekiq::Stats/Sidekiq::Queue (used by StatsReporter below) live in sidekiq/api, not
+# autoloaded by a bare "sidekiq" require; a real Sidekiq server process almost always already has
+# this loaded some other way, but requiring it explicitly here doesn't depend on that happening to
+# be true.
+require "sidekiq/api"
+
+module ForgeOpsTracker
+  module Integrations
+    module Sidekiq
+      # Times a raw (non-ActiveJob) Sidekiq::Worker's own #perform. Registered via
+      # Sidekiq.configure_server { |c| c.server_middleware { |chain| chain.add ... } } (see
+      # Railtie); only ever loaded when Sidekiq is already present (checked with defined? there),
+      # matching every other optional integration in this gem.
+      #
+      # Skips (yields, but doesn't record) any job whose worker is ActiveJob's own Sidekiq wrapper:
+      # see PerformanceInstrumentation.sidekiq_worker_is_active_job_wrapper?'s own comment for why
+      # that job is already counted by the perform.active_job subscription instead, and would be
+      # double-counted here otherwise.
+      class Middleware
+        include ::Sidekiq::ServerMiddleware
+
+        def initialize(configuration: ForgeOpsTracker.configuration, flusher: Railtie.performance_flusher)
+          @configuration = configuration
+          @flusher = flusher
+        end
+
+        def call(job_instance, _msg, _queue)
+          skip = !@configuration.track_performance || !@configuration.enabled? ||
+            PerformanceInstrumentation.sidekiq_worker_is_active_job_wrapper?(job_instance)
+          start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) unless skip
+
+          yield
+        ensure
+          unless skip
+            duration_ms = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start) * 1000.0
+            @flusher.record(transaction_name: job_instance.class.name, duration_ms: duration_ms, kind: "job")
+          end
+        end
+      end
+
+      # Reports Sidekiq's own aggregate stats (Sidekiq::Stats, Sidekiq::Queue) as gauge-style
+      # infrastructure metrics on a periodic timer (see PeriodicPoller), via the same public
+      # ForgeOpsTracker.capture_infrastructure_metric every customer's own manual infrastructure-
+      # monitoring script already uses; no new ingestion endpoint or dashboard dataset needed.
+      class StatsReporter
+        def self.start(configuration: ForgeOpsTracker.configuration)
+          return unless configuration.track_performance && configuration.enabled?
+
+          PeriodicPoller.start(configuration.gauge_poll_interval, logger: configuration.logger) { new.report }
+        end
+
+        def report
+          stats = ::Sidekiq::Stats.new
+
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.processed", value: stats.processed)
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.failed", value: stats.failed)
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.scheduled_size", value: stats.scheduled_size)
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.retry_size", value: stats.retry_size)
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.dead_size", value: stats.dead_size)
+          ForgeOpsTracker.capture_infrastructure_metric("sidekiq.workers_size", value: stats.workers_size)
+
+          ::Sidekiq::Queue.all.each do |queue|
+            ForgeOpsTracker.capture_infrastructure_metric("sidekiq.queue_depth.#{queue.name}", value: queue.size)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forge_ops_tracker/integrations/solid_queue.rb

@@ -0,0 +1,37 @@
+module ForgeOpsTracker
+  module Integrations
+    module SolidQueue
+      # Reports Solid Queue's own gauge-style state as infrastructure metrics on a periodic timer
+      # (see PeriodicPoller and Sidekiq::StatsReporter's own comment, the same shape). Only ever
+      # loaded when Solid Queue is already present (checked with defined? in Railtie).
+      #
+      # No job *duration*/*count* reporting here: Solid Queue jobs are ActiveJob jobs, already
+      # covered end to end by the perform.active_job subscription in Railtie regardless of which
+      # backend actually runs them, so there's nothing left for this integration to time.
+      #
+      # kind is Solid Queue's own attribute on a registered process (a plain String, "Worker" or
+      # "Dispatcher": confirmed directly against solid_queue's own Processes::Base#kind, which is
+      # literally self.class.name.demodulize, not assumed from its docs), so this reads it exactly
+      # as Solid Queue itself defines it rather than re-deriving it a different way.
+      class StatsReporter
+        def self.start(configuration: ForgeOpsTracker.configuration)
+          return unless configuration.track_performance && configuration.enabled?
+
+          PeriodicPoller.start(configuration.gauge_poll_interval, logger: configuration.logger) { new.report }
+        end
+
+        def report
+          ForgeOpsTracker.capture_infrastructure_metric("solid_queue.active_workers", value: ::SolidQueue::Process.where(kind: "Worker").count)
+          ForgeOpsTracker.capture_infrastructure_metric("solid_queue.active_dispatchers", value: ::SolidQueue::Process.where(kind: "Dispatcher").count)
+          ForgeOpsTracker.capture_infrastructure_metric("solid_queue.failed", value: ::SolidQueue::FailedExecution.count)
+          ForgeOpsTracker.capture_infrastructure_metric("solid_queue.scheduled", value: ::SolidQueue::ScheduledExecution.count)
+          ForgeOpsTracker.capture_infrastructure_metric("solid_queue.blocked", value: ::SolidQueue::BlockedExecution.count)
+
+          ::SolidQueue::Queue.all.each do |queue|
+            ForgeOpsTracker.capture_infrastructure_metric("solid_queue.queue_depth.#{queue.name}", value: queue.size)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forge_ops_tracker/metric_buffer.rb

@@ -0,0 +1,80 @@
+require "thread"
+
+module ForgeOpsTracker
+  # Collects individual ForgeOpsTracker.capture_metric calls in-process and periodically flushes
+  # them as one batch, rather than one network call per capture -- the same "lazily start a
+  # background thread on first use" pattern SessionFlusher/PerformanceFlusher already use, so each
+  # forked Puma/Passenger worker gets its own fresh thread instead of inheriting a dead one across
+  # fork. Unlike those two, this collects a *list* of individually-meaningful entries rather than
+  # summing them into buckets: a customer's own signup or payment is exactly the kind of thing
+  # they'll want a genuinely accurate count/sum of later, not something to pre-aggregate away
+  # client-side, so CustomMetricsController stores one row per entry as-is.
+  class MetricBuffer
+    def initialize(configuration, client: Client.new(configuration))
+      @configuration = configuration
+      @client = client
+      @mutex = Mutex.new
+      @entries = []
+      @thread = nil
+
+      # Flushes whatever's already buffered on a normal process exit, so the last partial window
+      # isn't silently dropped; same reasoning every other buffer/flusher in this gem documents.
+      at_exit { flush }
+    end
+
+    def record(metric_name:, value:)
+      ensure_worker_started
+
+      @mutex.synchronize do
+        @entries << {
+          metric_name: metric_name, value: value,
+          environment: configuration.environment.to_s, release: configuration.release,
+          recorded_at: Time.now.utc.iso8601
+        }
+      end
+    end
+
+    # Snapshots and resets the buffered entries, then delivers them as one batch. A failed
+    # delivery keeps every entry where it is rather than resetting, so the next flush's batch
+    # just grows instead of losing what was already buffered; same reasoning SessionFlusher#flush
+    # already documents, including the same small, accepted race (an entry recorded during the
+    # in-flight HTTP request gets folded into this snapshot's own reset rather than kept for the
+    # next one) that class already lives with, for the same reason: simple and consistent beats a
+    # cleverer dedup that would only trade one rare edge case for a subtler one.
+    def flush
+      snapshot = nil
+
+      @mutex.synchronize do
+        return if @entries.empty?
+        snapshot = @entries
+      end
+
+      return unless client.deliver_metrics(snapshot)
+
+      @mutex.synchronize { @entries = [] }
+    end
+
+    private
+      attr_reader :configuration, :client
+
+      def ensure_worker_started
+        return if @thread&.alive?
+
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @thread = Thread.new { run }
+          @thread.abort_on_exception = false
+        end
+      end
+
+      def run
+        loop do
+          sleep configuration.metric_flush_interval
+          flush
+        rescue StandardError => e
+          configuration.logger&.debug { "[ForgeOpsTracker] metric flush thread error: #{e.class}: #{e.message}" }
+        end
+      end
+  end
+end

data/lib/forge_ops_tracker/middleware/session_tracking.rb

@@ -0,0 +1,38 @@
+module ForgeOpsTracker
+  module Middleware
+    # Wraps every request: counts it, and separately counts it as crashed only when an exception
+    # actually escapes to here, never inferred from whether ErrorSubscriber happened to report
+    # anything, since ErrorSubscriber reports handled errors too (see Rails.error.handle), so "an
+    # event was reported" and "this request crashed" aren't the same signal. Always re-raises,
+    # so the host app's own error handling and ErrorSubscriber both run completely unaffected by
+    # this middleware's presence; it only ever observes, never intercepts.
+    class SessionTracking
+      def initialize(app, configuration: ForgeOpsTracker.configuration, flusher: nil)
+        @app = app
+        @configuration = configuration
+        @flusher = flusher
+      end
+
+      def call(env)
+        return app.call(env) unless configuration.track_sessions && configuration.enabled?
+
+        begin
+          response = app.call(env)
+        rescue StandardError
+          flusher_instance.record_session(crashed: true)
+          raise
+        end
+
+        flusher_instance.record_session(crashed: false)
+        response
+      end
+
+      private
+        attr_reader :app, :configuration
+
+        def flusher_instance
+          @flusher ||= SessionFlusher.new(configuration)
+        end
+    end
+  end
+end

data/lib/forge_ops_tracker/middleware/user_context.rb

@@ -0,0 +1,52 @@
+module ForgeOpsTracker
+  module Middleware
+    # Wraps every request: if Warden is mounted (env["warden"] present, whether or not the app
+    # uses Devise specifically, since Devise just mounts Warden automatically, but any Warden-
+    # based auth setup works here, confirmed directly against the installed warden gem's own
+    # Warden::Manager/Warden::Proxy source) and it has a signed-in user, stashes a serialized
+    # version of that user in a thread-local for the duration of this request so
+    # ErrorSubscriber#report (which never receives the Rack env at all: Rails.error.subscribe's
+    # own interface hands it error/context/severity, nothing request-shaped) can read it back and
+    # attach it to whatever gets reported. A sibling to SessionTracking, not folded into it:
+    # distinct concern, same "own file, own class" shape every middleware in this gem already
+    # takes.
+    #
+    # The ensure-clear is load-bearing, not optional: Puma reuses threads across requests, so
+    # leaving this set would leak one request's user into a later, unrelated request handled on
+    # the same thread.
+    class UserContext
+      def initialize(app, configuration: ForgeOpsTracker.configuration)
+        @app = app
+        @configuration = configuration
+      end
+
+      def call(env)
+        return app.call(env) unless configuration.track_current_user && configuration.enabled?
+
+        if env.key?("warden") && (user = env["warden"].user)
+          serialized = serialize(user)
+          Thread.current[:forge_ops_tracker_current_user] = serialized unless serialized.empty?
+        end
+
+        app.call(env)
+      ensure
+        Thread.current[:forge_ops_tracker_current_user] = nil
+      end
+
+      private
+        attr_reader :app, :configuration
+
+        # Duck-types rather than assuming a Devise-shaped model: id if the object responds to it,
+        # email if it responds to it, username else name if either responds to it. A custom
+        # Warden setup with a differently-shaped user object just gets whatever subset applies
+        # here; ForgeOpsTracker.set_user covers anything this can't infer.
+        def serialize(user)
+          {
+            id: (user.id if user.respond_to?(:id)),
+            email: (user.email if user.respond_to?(:email)),
+            username: (user.username if user.respond_to?(:username)) || (user.name if user.respond_to?(:name))
+          }.compact
+        end
+    end
+  end
+end

data/lib/forge_ops_tracker/performance_flusher.rb

@@ -0,0 +1,101 @@
+require "thread"
+
+module ForgeOpsTracker
+  # Times every request/job/query/outbound call in-process, bucketed by [transaction_name, kind]
+  # (see Railtie's several ActiveSupport::Notifications subscriptions, each a different kind), and
+  # periodically flushes each distinct bucket as one small aggregate report, rather than one
+  # network call per event. One shared flusher for every kind, not one per kind: the aggregation
+  # shape (count + duration sum + max over a period) is identical regardless of what's actually
+  # being timed. Same "lazily start a background thread on first use, not at load time" pattern
+  # SessionFlusher already uses, so each forked Puma/Passenger worker gets its own fresh thread
+  # instead of inheriting a dead one across fork.
+  class PerformanceFlusher
+    def initialize(configuration, client: Client.new(configuration))
+      @configuration = configuration
+      @client = client
+      @mutex = Mutex.new
+      @buckets = {}
+      @period_started_at = Time.now.utc
+      @thread = nil
+
+      # Flushes whatever's already tallied on a normal process exit, so the last partial window
+      # (anything shorter than a full performance_flush_interval) isn't silently dropped; same
+      # reasoning SessionFlusher's own at_exit hook documents.
+      at_exit { flush }
+    end
+
+    # kind ("controller"/"job"/"query"/"http", see Railtie's own subscriptions) is part of the
+    # bucket key alongside transaction_name, not folded into transaction_name itself: a job and a
+    # controller action (or, less likely but still real, a query and a job) can share a name
+    # without colliding into the same bucket.
+    def record(transaction_name:, duration_ms:, kind: "controller")
+      ensure_worker_started
+
+      @mutex.synchronize do
+        bucket = (@buckets[[ transaction_name, kind ]] ||= { count: 0, duration_sum_ms: 0.0, max_duration_ms: 0.0 })
+        bucket[:count] += 1
+        bucket[:duration_sum_ms] += duration_ms
+        bucket[:max_duration_ms] = duration_ms if duration_ms > bucket[:max_duration_ms]
+      end
+    end
+
+    # Snapshots and resets the in-process buckets, then delivers them as one batch. A failed
+    # delivery keeps every bucket where it is rather than resetting, so the next flush's window
+    # just grows instead of losing what was already tallied; same reasoning SessionFlusher#flush
+    # already documents, and the same reason PerformanceSamplesController accepts a batch rather
+    # than a single row: a failed flush shouldn't have to re-deliver by transaction one at a time.
+    def flush
+      snapshot = nil
+      period_started_at = nil
+
+      @mutex.synchronize do
+        return if @buckets.empty?
+
+        period_started_at = @period_started_at
+        snapshot = @buckets.map do |(transaction_name, kind), bucket|
+          {
+            transaction_name: transaction_name,
+            kind: kind,
+            environment: configuration.environment.to_s,
+            release: configuration.release,
+            period_started_at: period_started_at.iso8601,
+            period_ended_at: Time.now.utc.iso8601,
+            request_count: bucket[:count],
+            duration_sum_ms: bucket[:duration_sum_ms],
+            max_duration_ms: bucket[:max_duration_ms]
+          }
+        end
+      end
+
+      return unless snapshot && client.deliver_performance_samples(snapshot)
+
+      @mutex.synchronize do
+        @buckets = {}
+        @period_started_at = Time.now.utc
+      end
+    end
+
+    private
+      attr_reader :configuration, :client
+
+      def ensure_worker_started
+        return if @thread&.alive?
+
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @thread = Thread.new { run }
+          @thread.abort_on_exception = false
+        end
+      end
+
+      def run
+        loop do
+          sleep configuration.performance_flush_interval
+          flush
+        rescue StandardError => e
+          configuration.logger&.debug { "[ForgeOpsTracker] performance flush thread error: #{e.class}: #{e.message}" }
+        end
+      end
+  end
+end

data/lib/forge_ops_tracker/performance_instrumentation.rb

@@ -0,0 +1,60 @@
+module ForgeOpsTracker
+  # The actual "what do we call this, and should we even record it" decisions Railtie's
+  # ActiveSupport::Notifications subscriptions make, pulled out into plain module-function methods
+  # rather than left inline in each subscribe block. Railtie itself only ever loads when
+  # Rails::Railtie is already defined (see lib/forge_ops_tracker.rb's own final line), so nothing
+  # in that file can be exercised by this gem's own test suite without adding Rails itself as a
+  # development dependency just to fire a notification event by hand; every method here takes a
+  # plain payload Hash instead of a real ActiveSupport::Notifications::Event, so the decision logic
+  # itself (the SCHEMA/cached skip, the ActiveJob-wrapper dedup) is fully unit-testable with no
+  # Rails/Sidekiq/ActiveJob dependency at all. Railtie's own subscribe blocks stay thin, calling
+  # straight into these.
+  module PerformanceInstrumentation
+    module_function
+
+    def controller_transaction_name(payload)
+      "#{payload[:controller]}##{payload[:action]}"
+    end
+
+    # nil means "don't record this one": Rails' own sql.active_record fires for two kinds of
+    # noise that would drown out real query timing otherwise. "SCHEMA" is Rails' own internal
+    # introspection (column lookups, etc.), never something a customer's own code triggered;
+    # payload[:cached] is a genuinely instant hash lookup off Rails' own query cache, not a real
+    # round trip to the database, so timing it would understate every cached query's own real
+    # cost the next time it isn't cached.
+    #
+    # payload[:name] (Rails' own auto-generated label, e.g. "User Load", "Order Create"), not
+    # payload[:sql] (the literal query text): a customer's own query text could carry a literal
+    # value in some edge cases despite ActiveRecord's own parameterization, and even where it
+    # doesn't, raw SQL text is far higher cardinality than this system's transaction_name is
+    # designed for everywhere else. Falls back to the literal string "SQL" for the rare query
+    # with no name at all, rather than skipping it outright.
+    def query_transaction_name(payload)
+      return nil if payload[:name] == "SCHEMA" || payload[:cached]
+
+      # A plain nil-or-empty check, not ActiveSupport's #presence: this module is unit-tested
+      # without Rails/ActiveSupport loaded at all (see this file's own top comment), so it can't
+      # rely on a method ActiveSupport adds to String/NilClass.
+      name = payload[:name]
+      name.nil? || name.empty? ? "SQL" : name
+    end
+
+    def job_transaction_name(payload)
+      payload[:job].class.name
+    end
+
+    # True for a job dispatched through ActiveJob but actually run on Sidekiq: Sidekiq's own
+    # server middleware chain wraps every job it runs, ActiveJob-dispatched or not, so without
+    # this check a job on the Sidekiq/ActiveJob combination would be recorded twice: once here
+    # (kind: "job", via the raw Sidekiq middleware) and once already by the perform.active_job
+    # subscription that already covers every ActiveJob job regardless of which queue backend
+    # actually runs it (Solid Queue, Sidekiq, or anything else). The class name itself is
+    # ActiveJob's own, not this gem's: confirmed directly against how ActiveJob wraps a job for
+    # Sidekiq, not assumed from either project's docs alone.
+    def sidekiq_worker_is_active_job_wrapper?(worker)
+      return false unless defined?(::ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper)
+
+      worker.is_a?(::ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper)
+    end
+  end
+end

data/lib/forge_ops_tracker/periodic_poller.rb

@@ -0,0 +1,50 @@
+module ForgeOpsTracker
+  # A small shared background-thread loop for the Sidekiq/Solid Queue/Puma stats reporters (see
+  # integrations/): unlike PerformanceFlusher and the two metric buffers, which genuinely differ
+  # in what they buffer and are kept as separate sibling classes on purpose (see
+  # InfrastructureMetricBuffer's own comment), these three reporters only differ in *what they
+  # poll*, not *how they poll it*: lazily start a thread on first use (so a forked worker gets
+  # its own live thread regardless of when it forked relative to load, same reasoning
+  # PerformanceFlusher's own lazy start documents), sleep the interval, call the block, rescue and
+  # log so one bad tick never kills the loop, forever. Genuinely mechanical enough across all
+  # three to share, unlike those.
+  #
+  # No at_exit flush: unlike the flushers/buffers, which hold real accumulated data that would
+  # otherwise be lost, a gauge reading skipped on process exit is simply the same as one skipped
+  # because the interval hadn't ticked yet: nothing to lose.
+  class PeriodicPoller
+    def self.start(interval, logger: nil, &block)
+      new(interval, logger: logger, &block).tap(&:start)
+    end
+
+    def initialize(interval, logger: nil, &block)
+      @interval = interval
+      @logger = logger
+      @block = block
+      @mutex = Mutex.new
+      @thread = nil
+    end
+
+    def start
+      return if @thread&.alive?
+
+      @mutex.synchronize do
+        return if @thread&.alive?
+
+        @thread = Thread.new { run }
+        @thread.abort_on_exception = false
+      end
+      self
+    end
+
+    private
+      def run
+        loop do
+          sleep @interval
+          @block.call
+        rescue StandardError => e
+          @logger&.debug { "[ForgeOpsTracker] periodic poller error: #{e.class}: #{e.message}" }
+        end
+      end
+  end
+end

data/lib/forge_ops_tracker/pii_scrubber.rb

@@ -1,11 +1,11 @@
 module ForgeOpsTracker
   # Redacts likely-sensitive content out of a payload before it ever leaves
-  # this process -- the same patterns ForgeOps itself applies again on
+  # this process; the same patterns ForgeOps itself applies again on
   # arrival (defense in depth: this layer keeps the data off the wire and
   # out of any request logging in between; the server-side layer is what
   # actually protects the database, and doesn't depend on every reporting
   # app running an up-to-date version of this gem). See the main
-  # application's PiiScrubber for the shared design rationale -- kept as a
+  # application's PiiScrubber for the shared design rationale; kept as a
   # separate, dependency-free implementation here rather than requiring the
   # private app's code, since this gem has to work standalone in any host
   # app regardless of what's reporting into it.