forge_ops_tracker 0.5.0 → 0.10.1

data/lib/forge_ops_tracker/failure_event_buffer.rb

@@ -0,0 +1,73 @@
+require "thread"
+
+module ForgeOpsTracker
+  # Collects individual job/dependency failures in-process (see Railtie's own perform.active_job
+  # subscription and Integrations::NetHTTP::Timing#request, the two places that actually call
+  # #record) and periodically flushes them as one batch, the same shape MetricBuffer already uses
+  # for the identical reason: a real failure's own detail (which job, what error) is exactly the
+  # kind of thing worth an accurate individual record of, not something to pre-aggregate away the
+  # way PerformanceFlusher's own count/sum/max buckets duration.
+  class FailureEventBuffer
+    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(kind:, transaction_name:, error_class: nil, error_message: nil)
+      ensure_worker_started
+
+      @mutex.synchronize do
+        @entries << {
+          kind: kind, transaction_name: transaction_name, error_class: error_class, error_message: error_message,
+          environment: configuration.environment.to_s, release: configuration.release,
+          occurred_at: Time.now.utc.iso8601
+        }
+      end
+    end
+
+    # Snapshots and resets the buffered entries, then delivers them as one batch. Same "a failed
+    # delivery keeps every entry for the next attempt" contract as MetricBuffer#flush.
+    def flush
+      snapshot = nil
+
+      @mutex.synchronize do
+        return if @entries.empty?
+        snapshot = @entries
+      end
+
+      return unless client.deliver_failure_events(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.failure_event_flush_interval
+          flush
+        rescue StandardError => e
+          configuration.logger&.debug { "[ForgeOpsTracker] failure event flush thread error: #{e.class}: #{e.message}" }
+        end
+      end
+  end
+end

data/lib/forge_ops_tracker/histogram_bucketer.rb

@@ -0,0 +1,32 @@
+module ForgeOpsTracker
+  # Buckets a single duration into one of a fixed set of latency-range labels, the building block
+  # PerformanceFlusher uses to accumulate an approximate distribution (not just count/sum/max)
+  # alongside every [transaction_name, kind] bucket it already tallies. The server merges these
+  # counts across matching samples at read time and walks cumulative counts to approximate a
+  # percentile, the same "accurate to the bucket width, not exact" trade-off Prometheus's own
+  # histogram_quantile makes: this SDK does not store, or need, the raw duration list a true
+  # percentile would require.
+  #
+  # BOUNDARIES_MS is duplicated (not shared via a gem dependency) on the server side, in
+  # app/services/histogram_percentile.rb: the gem and the Rails app it reports to are separate
+  # deployables, the same "duplicated, not imported, so this package's own dependency graph stays
+  # independent" reasoning already applied elsewhere in this repo (e.g. the React Native SDK's own
+  # copy of the TypeScript SDK's PII scrubber). Change one, change the other, or a released gem
+  # version and the server version it talks to would silently disagree about what each bucket label
+  # means.
+  module HistogramBucketer
+    BOUNDARIES_MS = [ 50, 100, 250, 500, 1000, 2500, 5000, 10_000 ].freeze
+
+    # Returns the label (a String) of the smallest boundary duration_ms fits under, or "inf" for
+    # anything larger than the largest boundary. String, not Integer/Float: this travels as a JSON
+    # object key once flushed (see PerformanceFlusher#flush), and JSON object keys are always
+    # strings regardless of what Ruby type builds the Hash locally, so returning a String here
+    # keeps the in-process Hash's own keys identical to what actually goes over the wire, rather
+    # than looking different locally and then silently getting stringified only at serialization
+    # time.
+    def self.bucket_for(duration_ms)
+      boundary = BOUNDARIES_MS.find { |b| duration_ms <= b }
+      boundary ? boundary.to_s : "inf"
+    end
+  end
+end

data/lib/forge_ops_tracker/infrastructure_metric_buffer.rb

@@ -0,0 +1,86 @@
+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
+    # Once this many entries are buffered, further ones are dropped until a flush succeeds: a plan
+    # without the feature answers 403 on every flush, and an uncapped buffer would then grow for as
+    # long as the process lives. Dropping the newest rather than the oldest keeps the entries a flush
+    # is delivering at the front of the array, which is what makes removing exactly them exact.
+    MAX_ENTRIES = 1000
+
+    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:)
+      return false unless keepable?(value)
+
+      ensure_worker_started
+
+      @mutex.synchronize do
+        return false if @entries.size >= MAX_ENTRIES
+
+        @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.dup
+      end
+
+      return unless client.deliver_infrastructure_metrics(snapshot)
+
+      # Exactly the entries just delivered: anything recorded while the request was in flight sits
+      # after them and stays for the next flush (resetting the whole array here lost it).
+      @mutex.synchronize { @entries.shift(snapshot.size) }
+    end
+
+    private
+      attr_reader :configuration, :client
+
+      # A NaN or infinite value is not valid JSON and would make the server reject the whole batch.
+      def keepable?(value)
+        value.is_a?(Numeric) && value.to_f.finite?
+      end
+
+      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/active_record_pool.rb

@@ -0,0 +1,41 @@
+module ForgeOpsTracker
+  module Integrations
+    module ActiveRecordPool
+      # Reports this process's own ActiveRecord connection pool utilization as infrastructure
+      # metrics on a periodic timer, the same shape as Sidekiq::StatsReporter/SolidQueue::StatsReporter
+      # (see either's own comment), and, like both of those, only ever loaded when ActiveRecord is
+      # actually present (checked with defined? in Railtie, not assumed).
+      #
+      # Scoped to the current process's own primary connection pool only, via the bare
+      # ActiveRecord::Base.connection_pool this process is actually using: a known v1 limitation,
+      # not an oversight, for an app with multiple databases (ActiveRecord::Base.connection_pool is
+      # only ever one of potentially several pools such an app has configured). Reporting every
+      # configured pool would need ActiveRecord::Base.connection_handler's own registry, a genuinely
+      # separate piece of work; this integration reports what a single-database app (the common
+      # case, and the only case this gem's own test suite/README examples ever set up) actually has.
+      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
+          stat = ::ActiveRecord::Base.connection_pool.stat
+          size = stat[:size].to_i
+          busy = stat[:busy].to_i
+
+          # 0/0 (a pool nobody's ever checked a connection out of yet, or, in practice, never) reads
+          # as 0% utilized, not NaN/an error: a pool that's never been used is exactly as "not under
+          # pressure" as a pool with plenty of headroom, not a value worth surfacing as broken.
+          utilization_pct = size.zero? ? 0.0 : (100.0 * busy / size).round(1)
+
+          ForgeOpsTracker.capture_infrastructure_metric("active_record_pool.utilization_pct", value: utilization_pct)
+          ForgeOpsTracker.capture_infrastructure_metric("active_record_pool.size", value: size)
+          ForgeOpsTracker.capture_infrastructure_metric("active_record_pool.busy", value: busy)
+          ForgeOpsTracker.capture_infrastructure_metric("active_record_pool.waiting", value: stat[:waiting].to_i)
+        end
+      end
+    end
+  end
+end

data/lib/forge_ops_tracker/integrations/net_http.rb

@@ -0,0 +1,114 @@
+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.
+      #
+      # Known, honest gap, confirmed directly against Net::HTTP's own source and real behavior, not
+      # assumed: Net::HTTP.get_response and the Net::HTTP.start { |http| ... } block form both open
+      # the TCP connection inside #start, *before* the block (and so before #request, the only
+      # method this wraps) ever runs, so a connection-refused/DNS-failure error raised during that
+      # setup is structurally invisible here, for timing, breadcrumbs, and the failure detection
+      # below alike (a pre-existing limitation this round's own test suite is what actually
+      # surfaced, not something newly introduced). Net::HTTP.new(...).request(...), the other
+      # common calling convention (no explicit #start at all), is different and unaffected:
+      # confirmed directly that Net::HTTP connects lazily, inside #request itself, the first time
+      # it's called on a not-yet-started instance, so that path's own connection failures are
+      # caught exactly like any other #request failure.
+      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)
+          configuration = ForgeOpsTracker.configuration
+          return super unless (configuration.track_performance || configuration.track_breadcrumbs || configuration.track_failures || configuration.track_tracing) && configuration.enabled?
+
+          start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          response = super
+        rescue StandardError => e
+          # Only track_failures below needs the actual exception object (for error_class/
+          # error_message); everything else keys off response staying nil, already true on this
+          # path without capturing anything. re-raised unchanged: this gem must never swallow or
+          # alter what the host app's own call to Net::HTTP#request would have raised.
+          raised_error = e
+          raise
+        ensure
+          if start
+            duration_ms = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start) * 1000.0
+            # Computed once, unconditionally, not separately inside each flag-gated block below:
+            # both the breadcrumb and track_failures sections need it, and a value only ever
+            # assigned inside one conditional branch but read from another relies on Ruby's own
+            # "a local is declared the moment its assignment is lexically parsed, regardless of
+            # whether that branch actually ran" scoping, a real but easy-to-break-on-reorder
+            # subtlety not worth the risk here.
+            status = response&.code&.to_i
+            if configuration.track_performance
+              Railtie.performance_flusher.record(transaction_name: "#{req.method} #{address}", duration_ms: duration_ms, kind: "http")
+            end
+            # The same "method + host, never the full path/query string" reasoning
+            # transaction_name above already follows: a URL's own path or query could carry an id
+            # or a token, and this is a breadcrumb message, not a value this gem controls the
+            # cardinality of. Mirrors sdks/typescript's own fetch/xhr breadcrumbs: category
+            # "http", status + duration_ms in data, level "warning" for a non-2xx/3xx response.
+            if configuration.track_breadcrumbs
+              # No status at all means the request itself raised (a timeout, a connection
+              # refused, ...) before a response ever came back: worth "error", not the misleading
+              # "info" a bare status-based check would default a nil status to, the same "the
+              # request truly failed" case sdks/typescript's own fetch breadcrumb catch block
+              # marks "error" for.
+              level = if status.nil?
+                "error"
+              elsif status >= 400
+                "warning"
+              else
+                "info"
+              end
+              ForgeOpsTracker.add_breadcrumb(
+                "#{req.method} #{address}",
+                category: "http",
+                level: level,
+                data: { status: status, duration_ms: duration_ms.round(1) }.compact
+              )
+            end
+            # Independent of track_performance/track_breadcrumbs above, same "several genuinely
+            # independent mechanisms recorded from the same instrumentation point" pattern this
+            # exact call site already established for breadcrumbs. A failure is the request
+            # raising, or a 5xx: not a 4xx, the identical distinction the breadcrumb level just
+            # above already draws between "the dependency is unhealthy" (worth "error"/failure)
+            # and "the dependency responded, just not with success" (only "warning").
+            if configuration.track_failures && (status.nil? || status >= 500)
+              Railtie.failure_event_buffer.record(
+                kind: "dependency", transaction_name: "#{req.method} #{address}",
+                error_class: raised_error&.class&.name, error_message: raised_error&.message
+              )
+            end
+            # A leaf span, the same "parented onto whatever's currently open, never touches the
+            # stack itself" shape the sql.active_record subscription's own span recording already
+            # takes: an outbound HTTP call has no children of its own to nest anything under
+            # either.
+            if configuration.track_tracing && (buffer = Thread.current[:forge_ops_tracker_spans])
+              # duration_ms itself is exact (computed from the monotonic clock above); started_at
+              # here is only derived from it (now minus duration), an approximation off the wall
+              # clock rather than a second real timestamp captured at the top of this method - a
+              # few milliseconds of drift on where the bar starts in a waterfall, never on how long
+              # it actually took.
+              start_time = ::Time.now.utc - (duration_ms / 1000.0)
+              buffer.record(
+                span_id: SecureRandom.hex(8), name: "#{req.method} #{address}", kind: "http",
+                started_at: start_time, duration_ms: duration_ms, data: { status: status }.compact
+              )
+            end
+          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/redis_client.rb

@@ -0,0 +1,62 @@
+module ForgeOpsTracker
+  module Integrations
+    module RedisClientTiming
+      # Times every Redis command, applied once via RedisClient.prepend(Timing) from Railtie, the
+      # same Module#prepend + super shape Integrations::NetHTTP::Timing already uses for the
+      # identical reason: neither Ruby's Redis ecosystem nor RedisClient itself fires an
+      # ActiveSupport::Notifications event of its own, so wrapping #call directly is the only hook
+      # available. Targets RedisClient specifically (the modern, actively-maintained low-level
+      # client both the current redis gem (5.x+) and standalone RedisClient users go through), not
+      # the older redis-rb 4.x Redis::Client - confirmed directly (not assumed) that redis 5.x no
+      # longer defines Redis::Client at all, so a hook there would silently do nothing on any
+      # currently-installed version of the gem.
+      #
+      # Unlike controller/query timing, this is span-only: there's no "redis" PerformanceSample
+      # kind for this to feed into the aggregate Performance page (that page has no Redis panel at
+      # all yet), so this only ever contributes to a captured trace's own waterfall, plus a
+      # breadcrumb and a dependency failure record, the same two other independent mechanisms
+      # NetHTTP::Timing's own call site already establishes.
+      #
+      # name is "Redis <COMMAND>" (the command verb alone, upcased: GET, SET, LPUSH, ...), never
+      # the key or any argument - the same low-cardinality, no-secrets-in-a-label reasoning every
+      # other transaction_name/span name in this gem already follows; a Redis key can easily carry
+      # a customer's own id or other sensitive value.
+      def call(*command, **kwargs)
+        configuration = ForgeOpsTracker.configuration
+        return super unless (configuration.track_breadcrumbs || configuration.track_failures || configuration.track_tracing) && configuration.enabled?
+
+        name = "Redis #{command.first.to_s.upcase}"
+        start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        result = super
+      rescue StandardError => e
+        raised_error = e
+        raise
+      ensure
+        if start
+          duration_ms = (::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start) * 1000.0
+
+          if configuration.track_breadcrumbs
+            ForgeOpsTracker.add_breadcrumb(
+              name, category: "redis", level: raised_error ? "error" : "info",
+              data: { duration_ms: duration_ms.round(1) }
+            )
+          end
+
+          if configuration.track_failures && raised_error
+            Railtie.failure_event_buffer.record(
+              kind: "dependency", transaction_name: name,
+              error_class: raised_error.class.name, error_message: raised_error.message
+            )
+          end
+
+          if configuration.track_tracing && (buffer = Thread.current[:forge_ops_tracker_spans])
+            buffer.record(
+              span_id: SecureRandom.hex(8), name: name, kind: "redis",
+              started_at: ::Time.now.utc - (duration_ms / 1000.0), duration_ms: duration_ms
+            )
+          end
+        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