forge_ops_tracker 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15d33570709adad8c061ee0c432d9a6484fc50881076fae1493b892562188e7
-  data.tar.gz: f5fada725654a4006a6a44ee0680fb5f7f34cb808087305596892101c743a0ef
+  metadata.gz: 72692319cfdf068129d7d005773e21a3b6b78cb9f7816cf0e7c8e6409c9704f1
+  data.tar.gz: 713f244a7ab71a005e66b7f00d1dff3e1e3ffc44e304d5a36f79c911e508c74b
 SHA512:
-  metadata.gz: 66513f4aebaeb443198a73bad548faaab86653841d213c37000bd343de406926053faa58b65be68934d90c8e12cc1393061ee763e7b5541c4545e90713910fb9
-  data.tar.gz: 86eb61aca41a42a55a6df37df0d8ef7789b5342055239640a593310da438cda20e3d6e959a0b229c4dbcbe137089e31d8bd537b1eb8d4e91c72bec4acfd6ec8c
+  metadata.gz: 57f5372fc1aa6ac8f8830804003c00d68d0633d4f330dc8f6c678faa1c1dbc3f09ad1da0f29c180c63a90dc41f2d0f6acb008e4a726d59ba6b806298af3d6d8f
+  data.tar.gz: 2b21f12200f99202c5f26cc739104021d5eaf1cfe16a01b075fe4bc3418ada28cf7befb91470fb1ebd8bb18865cd52e61a705decc5f511c2c497a79c74c36016

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.7.0
+
+- Automatically associates a reported error with the current signed-in user, for any Warden-based
+  auth setup (Devise included; Devise just mounts Warden automatically, this isn't Devise-
+  specific). On by default, same as every other automatic instrumentation this gem does; opt out
+  with `config.track_current_user = false`. `ForgeOpsTracker.set_user(id:, email:, username:)`
+  manually sets or overrides it, for a custom auth setup or outside a request entirely (a
+  background job, a console session).
+
+## 0.6.0
+
+- Performance monitoring now also covers database queries (`sql.active_record`, bucketed by
+  Rails' own query name, never raw SQL text), background jobs (`perform.active_job`, any backend,
+  Solid Queue included, plus raw Sidekiq workers via a server middleware, deduplicated against
+  jobs dispatched through Active Job), and outbound `Net::HTTP` calls, alongside the existing
+  controller/action timing. Each shows up as its own `kind` on the same `performance` dashboard
+  dataset. Also reports Sidekiq's, Solid Queue's, and Puma's own operational gauges (queue depth,
+  worker/dispatcher counts, Puma's thread pool) as infrastructure metrics on a periodic timer
+  (`config.gauge_poll_interval`, default 60 seconds), whenever the corresponding library is
+  already loaded. All on the same `track_performance` flag as before; no new flags to opt into.
+
 ## 0.5.0
 
 - Every reported event now carries `sdk_name` ("ruby"), so a project's language on the ForgeOps

data/README.md

@@ -67,13 +67,41 @@ Bottom line: if an exception would otherwise crash something, you're already cov
 code already catches and handles it, route that specific `rescue` through `Rails.error.handle`/
 `.record` instead of a bare one wherever you want ForgeOps to know about it.
 
+## Identifying users
+
+If you're using Devise, or any other Warden-based authentication, the currently signed-in user is
+already associated with every error automatically, on by default, no setup needed:
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.track_current_user = false # opt out entirely
+end
+```
+
+For a custom auth setup this can't detect, or to override its guess, call
+`ForgeOpsTracker.set_user` yourself:
+
+```ruby
+before_action do
+  ForgeOpsTracker.set_user(id: current_user&.id, email: current_user&.email)
+end
+```
+
+Also usable outside a request entirely, a background job or a console session, for the rest of
+whichever thread calls it. `id`/`email`/`username` are all independently optional; call it with
+none of them (or with a signed-out `current_user`, as the `&.` above already handles) to clear
+whatever was set. Shows up on an issue's own detail page, and as its own `affected_users_count`
+alongside the regular event count.
+
 ## PII scrubbing
 
 By default, the message, backtrace, and any context/tags you attach are scanned for likely
 personal data: email addresses, formatted SSNs/credit cards, known API key/token formats, and
 anything under a suspiciously-named key (`password`, `api_key`, `ssn`, and similar); redacted
 before the payload ever leaves this process. ForgeOps itself scrubs again on arrival regardless, so
-this is a second, earlier layer, not the only one.
+this is a second, earlier layer, not the only one. The user identified via automatic Warden
+detection or `ForgeOpsTracker.set_user` above is a deliberate exception: it's never scrubbed,
+since redacting it would defeat the whole point of identifying users in the first place.
 
 To disable it (e.g. if your app already scrubs its own error context, or you have your own reasons
 to want the raw payload):
@@ -124,3 +152,115 @@ end
 
 Requires a ForgeOps plan that includes release health; on a plan that doesn't, the periodic
 flushes are simply rejected server-side and dropped, exactly like any other delivery failure.
+
+## Performance monitoring
+
+By default, every request's controller/action duration is timed (via Rails' own
+`process_action.action_controller` instrumentation, no extra middleware needed) so a dashboard
+widget on ForgeOps can show which parts of your app are actually slow, not just which ones raise.
+Bucketed by transaction ("PostsController#show") and flushed as a small periodic aggregate per
+transaction on a background thread, the same delivery philosophy as session tracking above: a
+broken or unreachable tracker never affects the host app either way.
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.track_performance = false   # opt out entirely
+  config.performance_flush_interval = 30 # seconds; default 60
+end
+```
+
+Requires a ForgeOps plan that includes performance monitoring; on a plan that doesn't, the
+periodic flushes are simply rejected server-side and dropped, exactly like any other delivery
+failure.
+
+### Database queries, background jobs, and outbound HTTP calls
+
+The same automatic instrumentation, on the same `track_performance` flag, also covers:
+
+- **Database queries**, via `sql.active_record`: bucketed by Rails' own auto-generated query name
+  ("User Load", "Order Create"), not the raw SQL text. Internal schema-introspection queries
+  ("SCHEMA") and cached reads (never a real round trip to the database) are skipped.
+- **Background jobs**, via `perform.active_job`: bucketed by job class. Covers any Active Job
+  backend, Solid Queue included, with no backend-specific code needed.
+- **Raw Sidekiq workers** (a `Sidekiq::Worker`/`Sidekiq::Job` not dispatched through Active Job):
+  a server middleware, registered automatically when Sidekiq is already loaded. A job dispatched
+  through Active Job and run on Sidekiq is still only counted once, by the Active Job hook above,
+  not twice.
+- **Outbound `Net::HTTP` calls**, bucketed by `"<method> <host>"`, never the full URL (a path or
+  query string could carry an id or a token). Most other Ruby HTTP client libraries (Faraday's own
+  `net_http` adapter, HTTParty, RestClient) ultimately call through `Net::HTTP`, so this covers
+  those too as a side effect.
+
+Every one of these shows up as its own `kind` ("controller", "job", "query", "http") on the same
+`performance` dashboard dataset, so "slowest jobs" and "slowest queries" are just a filtered
+version of the same widget builder "slowest transactions" already uses.
+
+### Sidekiq, Solid Queue, and Puma gauges
+
+Also on by default whenever the corresponding library is already loaded: Sidekiq's own aggregate
+stats (`Sidekiq::Stats`: processed/failed/scheduled/retry/dead counts, plus a queue-depth reading
+per queue), Solid Queue's own state (active workers, active dispatchers, failed/scheduled/blocked
+counts, a queue-depth reading per queue), and Puma's own thread pool (backlog, running threads,
+pool capacity). Reported as ordinary infrastructure metrics (`sidekiq.queue_depth.default`,
+`puma.backlog`, and so on) via the same `capture_infrastructure_metric` call your own scripts use,
+on a periodic timer:
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.gauge_poll_interval = 30 # seconds; default 60
+end
+```
+
+No separate opt-out: these are gated by the same `track_performance` flag as everything else in
+this section, not a flag of their own.
+
+## Custom metrics
+
+Unlike session/performance tracking above, there's no automatic instrumentation here at all: a
+signup or a payment isn't something this gem could ever detect on its own, so this is an explicit
+call your own code makes. `value` defaults to `1.0` so a bare counter-style call needs no
+argument; pass one for a metric with a real amount. Buffered and flushed as a batch on a
+background thread, same delivery philosophy as everything else here, so this is safe to call from
+inside a request (right after a signup completes, say) without adding network latency there.
+
+```ruby
+ForgeOpsTracker.capture_metric("signups")
+ForgeOpsTracker.capture_metric("revenue", value: 49.00)
+
+ForgeOpsTracker.configure do |config|
+  config.metric_flush_interval = 30 # seconds; default 60
+end
+```
+
+Requires a ForgeOps plan that includes custom metrics; on a plan that doesn't, the periodic
+flushes are simply rejected server-side and dropped, exactly like any other delivery failure.
+
+## Infrastructure monitoring
+
+A deliberately different shape from everything above: there's no automatic instrumentation and no
+ForgeOps-built agent. Run your own short-lived script on a cron entry or a systemd timer, reading
+your own host's own stats; `hostname` defaults to the box the script is actually running on.
+Buffered and flushed on exit, so a handful of capture calls in one short-lived process still cost
+one network request, not several.
+
+```ruby
+# A cron entry or systemd timer runs this periodically, not your web app itself.
+require "forge_ops_tracker"
+ForgeOpsTracker.configure { |config| config.dsn = ENV["FORGE_OPS_DSN"] }
+
+load_average = File.read("/proc/loadavg").split.first.to_f
+ForgeOpsTracker.capture_infrastructure_metric("load_average", value: load_average)
+
+meminfo = File.read("/proc/meminfo").lines.to_h { |line| line.split(":").map(&:strip) }
+total_kb, available_kb = meminfo["MemTotal"].to_i, meminfo["MemAvailable"].to_i
+ForgeOpsTracker.capture_infrastructure_metric("memory_used_percent",
+  value: 100.0 * (total_kb - available_kb) / total_kb)
+
+disk_used_percent = `df --output=pcent / | tail -1`.strip.delete("%").to_f
+ForgeOpsTracker.capture_infrastructure_metric("disk_used_percent", value: disk_used_percent)
+```
+
+The example above is Linux-specific (`/proc/loadavg`, `/proc/meminfo`); on another OS, read that
+platform's own equivalents instead. Requires a ForgeOps plan that includes infrastructure
+monitoring; on a plan that doesn't, the periodic flushes are simply rejected server-side and
+dropped, exactly like any other delivery failure.

data/lib/forge_ops_tracker/client.rb

@@ -23,6 +23,26 @@ module ForgeOpsTracker
       post(configuration.session_checkins_uri, payload)
     end
 
+    # Same delivery contract again; see Configuration#performance_samples_uri. payload here is a
+    # batch (one entry per distinct transaction a flush interval saw), not a single aggregate the
+    # way deliver_session_checkin's own payload is, so this posts { samples: [...] } rather than
+    # the array bare, matching what Api::V1::PerformanceSamplesController expects.
+    def deliver_performance_samples(samples)
+      post(configuration.performance_samples_uri, { samples: samples })
+    end
+
+    # Same delivery contract again; see Configuration#custom_metrics_uri. payload is a batch of
+    # individual capture_metric calls (see MetricBuffer), matching what
+    # Api::V1::CustomMetricsController expects.
+    def deliver_metrics(entries)
+      post(configuration.custom_metrics_uri, { metrics: entries })
+    end
+
+    # Same again; see Configuration#infrastructure_metrics_uri and InfrastructureMetricBuffer.
+    def deliver_infrastructure_metrics(entries)
+      post(configuration.infrastructure_metrics_uri, { metrics: entries })
+    end
+
     private
       attr_reader :configuration
 

data/lib/forge_ops_tracker/configuration.rb

@@ -9,6 +9,10 @@ module ForgeOpsTracker
     attr_accessor :enabled_environments, :queue_size, :open_timeout, :read_timeout, :scrub_pii
     attr_accessor :capture_source_context
     attr_accessor :track_sessions, :session_flush_interval
+    attr_accessor :track_performance, :performance_flush_interval
+    attr_accessor :track_current_user
+    attr_accessor :metric_flush_interval, :infrastructure_metric_flush_interval
+    attr_accessor :gauge_poll_interval
 
     def initialize
       @dsn = ENV["FORGE_OPS_DSN"]
@@ -43,6 +47,30 @@ module ForgeOpsTracker
       # ForgeOpsTracker::Middleware::SessionTracking for what this actually wraps.
       @track_sessions = true
       @session_flush_interval = 60
+      # Auto-instruments every request the same "on unless you turn it off" default as
+      # track_sessions above; see Railtie's own comment for exactly what this subscribes to.
+      @track_performance = true
+      @performance_flush_interval = 60
+      # Auto-detects the current user via Warden (env["warden"].user; Devise mounts Warden
+      # automatically, so this covers Devise apps too, but works for any Warden-based auth, not
+      # just Devise specifically) the same "on unless you turn it off" default every other
+      # automatic instrumentation flag above already has. See
+      # ForgeOpsTracker::Middleware::UserContext for how, and ForgeOpsTracker.set_user for the
+      # manual override/fallback when there's no Warden at all or its guess isn't right.
+      @track_current_user = true
+      # No track_metrics/track_infrastructure boolean the way track_sessions/track_performance
+      # each have one: those gate automatic instrumentation that's on unless you turn it off;
+      # capture_metric/capture_infrastructure_metric are explicit calls the customer's own code
+      # chooses to make at all, so there's no "automatic behavior" for a flag to disable. Only
+      # the flush interval needs a knob.
+      @metric_flush_interval = 60
+      @infrastructure_metric_flush_interval = 60
+      # How often the Sidekiq/Solid Queue/Puma stats reporters poll and report their own gauge
+      # readings (queue depth, worker counts, Puma backlog/threads/pool capacity). Gated by
+      # track_performance, same as controller/job/query/http timing: one flag for "automatically
+      # instrument this app's own operational data," reused rather than adding a separate boolean
+      # per new automatic instrumentation source this gem grows.
+      @gauge_poll_interval = 60
     end
 
     def api_key
@@ -72,6 +100,34 @@ module ForgeOpsTracker
       uri
     end
 
+    # Same substitution as session_checkins_uri above, its own sibling path under the same DSN.
+    def performance_samples_uri
+      uri = ingestion_uri
+      return nil unless uri
+
+      uri = uri.dup
+      uri.path = uri.path.sub(%r{/events\z}, "/performance_samples")
+      uri
+    end
+
+    def custom_metrics_uri
+      uri = ingestion_uri
+      return nil unless uri
+
+      uri = uri.dup
+      uri.path = uri.path.sub(%r{/events\z}, "/custom_metrics")
+      uri
+    end
+
+    def infrastructure_metrics_uri
+      uri = ingestion_uri
+      return nil unless uri
+
+      uri = uri.dup
+      uri.path = uri.path.sub(%r{/events\z}, "/infrastructure_metrics")
+      uri
+    end
+
     def enabled?
       !blank?(dsn) && !blank?(api_key) && enabled_environments.map(&:to_s).include?(environment.to_s)
     end

data/lib/forge_ops_tracker/error_subscriber.rb

@@ -14,7 +14,12 @@ module ForgeOpsTracker
     def report(error, handled: true, severity: nil, context: {}, source: nil)
       return unless configuration.enabled?
 
-      delivery_queue.push(event_builder.build(error, context: context))
+      # Read here, not inside EventBuilder: Rails.error.subscribe's own #report interface never
+      # hands this class the Rack env, so ForgeOpsTracker::Middleware::UserContext (Warden
+      # auto-detection) and ForgeOpsTracker.set_user (the manual override/fallback) both
+      # communicate with this exact same thread-local instead, the only channel available here.
+      user = Thread.current[:forge_ops_tracker_current_user]
+      delivery_queue.push(event_builder.build(error, context: context, user: user))
       nil
     rescue StandardError => e
       configuration.logger&.debug { "[ForgeOpsTracker] report failed: #{e.class}: #{e.message}" }

data/lib/forge_ops_tracker/event_builder.rb

@@ -27,7 +27,7 @@ module ForgeOpsTracker
       @configuration = configuration
     end
 
-    def build(error, context: {})
+    def build(error, context: {}, user: nil)
       payload = {
         exception_class: error.class.name,
         message: error.message.to_s,
@@ -40,16 +40,18 @@ module ForgeOpsTracker
         tags: {},
         sdk_name: SDK_NAME
       }
+      payload[:user] = user if user && !user.empty?
       scrub(payload)
     end
 
     private
       attr_reader :configuration
 
-      # exception_class/occurred_at/environment/release/server_name/sdk_name are
-      # left alone; structured fields this gem or the host app sets
-      # deliberately, not free text an exception or its context could
-      # accidentally spill sensitive data into.
+      # exception_class/occurred_at/environment/release/server_name/sdk_name/user are left alone;
+      # structured fields this gem or the host app sets deliberately, not free text an exception
+      # or its context could accidentally spill sensitive data into. user specifically is a
+      # deliberate exemption, not an oversight: the server's own PiiScrubber-equivalent would
+      # otherwise redact the exact email address this field exists to carry.
       def scrub(payload)
         return payload unless configuration.scrub_pii
 

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

@@ -2,6 +2,20 @@ require "rails/railtie"
 
 module ForgeOpsTracker
   class Railtie < ::Rails::Railtie
+    # Shared across every performance-timing subscription/integration below (controller, query,
+    # job, raw Sidekiq, outbound Net::HTTP): one flusher, one background thread, one set of
+    # buckets, since PerformanceFlusher already buckets on [transaction_name, kind] and safely
+    # handles concurrent calls from several sources at once. Exposed as a class method, not a
+    # local variable inside one initializer, specifically so the Sidekiq/Net::HTTP integrations
+    # (each guarded by their own separate initializer, since each only loads if its own optional
+    # library is present) can record into the exact same instance rather than each starting a
+    # redundant flusher/thread of their own.
+    class << self
+      def performance_flusher
+        @performance_flusher ||= ForgeOpsTracker::PerformanceFlusher.new(ForgeOpsTracker.configuration)
+      end
+    end
+
     initializer "forge_ops_tracker.subscribe_error_reporter" do |app|
       configuration = ForgeOpsTracker.configuration
       configuration.app_root ||= app.root.to_s
@@ -14,5 +28,110 @@ module ForgeOpsTracker
     initializer "forge_ops_tracker.track_sessions" do |app|
       app.middleware.use ForgeOpsTracker::Middleware::SessionTracking, configuration: ForgeOpsTracker.configuration
     end
+
+    # Warden::Manager (mounted automatically by Devise, or directly by any other Warden-based
+    # auth setup) sets env["warden"] itself; this only ever reads it, so it works regardless of
+    # exactly where in the middleware stack this ends up relative to Warden::Manager, as long as
+    # that key exists in env by the time this middleware's own #call runs, which is true for any
+    # Warden-based auth setup: it mounts its own middleware once, for the whole app, long before
+    # any individual request begins.
+    initializer "forge_ops_tracker.track_current_user" do |app|
+      app.middleware.use ForgeOpsTracker::Middleware::UserContext, configuration: ForgeOpsTracker.configuration
+    end
+
+    # Rails already fires "process_action.action_controller" after every request with the
+    # controller/action and how long it took (event.duration, in ms) built in, so unlike session
+    # tracking above (which needed a Rack middleware because there's no single existing hook for
+    # "a request finished"), this needs no middleware of its own at all, just a subscriber.
+    # Guarded the same way the error subscriber and session-tracking middleware both are: on by
+    # default, off entirely if track_performance is turned off or the gem itself isn't enabled
+    # (no DSN configured, or the current environment isn't in enabled_environments).
+    #
+    # sql.active_record/perform.active_job are subscribed here too, not in their own separate
+    # initializers: all three (plus Sidekiq/Net::HTTP below) are genuinely the same concern
+    # (automatic performance timing), sharing the one performance_flusher above; see
+    # PerformanceInstrumentation for the actual transaction_name/skip decisions each one makes,
+    # kept out of these blocks specifically so that decision logic is unit-testable without a real
+    # Rails/ActiveJob boot (this gem's own test suite doesn't require Rails at all; see that
+    # file's own comment).
+    initializer "forge_ops_tracker.track_performance" do
+      configuration = ForgeOpsTracker.configuration
+      flusher = Railtie.performance_flusher
+
+      ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+        next unless configuration.track_performance && configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        transaction_name = PerformanceInstrumentation.controller_transaction_name(event.payload)
+        flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "controller")
+      end
+
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        next unless configuration.track_performance && configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        transaction_name = PerformanceInstrumentation.query_transaction_name(event.payload)
+        next if transaction_name.nil? # SCHEMA/cached, see PerformanceInstrumentation's own comment
+
+        flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "query")
+      end
+
+      ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
+        next unless configuration.track_performance && configuration.enabled?
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        transaction_name = PerformanceInstrumentation.job_transaction_name(event.payload)
+        flusher.record(transaction_name: transaction_name, duration_ms: event.duration, kind: "job")
+      end
+    end
+
+    # Raw (non-ActiveJob) Sidekiq::Worker job timing, plus Sidekiq's own queue-depth/processed/
+    # failed/etc. gauges: a separate initializer, since unlike ActiveRecord/ActionController
+    # (always present in any Rails app this gem's own gemspec already implies), Sidekiq is
+    # genuinely optional and isn't a declared dependency of this gem at all.
+    initializer "forge_ops_tracker.track_sidekiq" do
+      next unless defined?(::Sidekiq)
+
+      require "forge_ops_tracker/integrations/sidekiq"
+
+      configuration = ForgeOpsTracker.configuration
+      ::Sidekiq.configure_server do |config|
+        config.server_middleware do |chain|
+          # No extra args to chain.add: Sidekiq calls Middleware.new(*args) itself for every job,
+          # splatting whatever was passed here; the middleware's own keyword-argument defaults
+          # (ForgeOpsTracker.configuration, Railtie.performance_flusher) already resolve correctly
+          # when called with none, and passing a keyword hash through *args here is genuinely
+          # ambiguous (Sidekiq's own chain.add doc example passes a literal positional Hash, not
+          # keyword syntax, for exactly this reason).
+          chain.add ForgeOpsTracker::Integrations::Sidekiq::Middleware
+        end
+      end
+
+      ForgeOpsTracker::Integrations::Sidekiq::StatsReporter.start(configuration: configuration)
+    end
+
+    initializer "forge_ops_tracker.track_solid_queue" do
+      next unless defined?(::SolidQueue)
+
+      require "forge_ops_tracker/integrations/solid_queue"
+      ForgeOpsTracker::Integrations::SolidQueue::StatsReporter.start(configuration: ForgeOpsTracker.configuration)
+    end
+
+    initializer "forge_ops_tracker.track_puma" do
+      next unless defined?(::Puma)
+
+      require "forge_ops_tracker/integrations/puma"
+      ForgeOpsTracker::Integrations::Puma::StatsReporter.start(configuration: ForgeOpsTracker.configuration)
+    end
+
+    # Net::HTTP is always present (Ruby's own standard library), so this always prepends; the
+    # actual on/off decision happens at call time inside Timing#request itself (checking
+    # configuration.track_performance/enabled? the same way the subscriptions above do), so
+    # toggling that flag after boot still takes effect immediately, the same as every other
+    # automatic instrumentation point in this gem.
+    initializer "forge_ops_tracker.track_net_http" do
+      require "forge_ops_tracker/integrations/net_http"
+      Net::HTTP.prepend(ForgeOpsTracker::Integrations::NetHTTP::Timing)
+    end
   end
 end

data/lib/forge_ops_tracker/version.rb

@@ -1,3 +1,3 @@
 module ForgeOpsTracker
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/forge_ops_tracker.rb

@@ -6,7 +6,13 @@ require "forge_ops_tracker/client"
 require "forge_ops_tracker/delivery_queue"
 require "forge_ops_tracker/error_subscriber"
 require "forge_ops_tracker/session_flusher"
+require "forge_ops_tracker/performance_flusher"
+require "forge_ops_tracker/performance_instrumentation"
+require "forge_ops_tracker/metric_buffer"
+require "forge_ops_tracker/infrastructure_metric_buffer"
+require "forge_ops_tracker/periodic_poller"
 require "forge_ops_tracker/middleware/session_tracking"
+require "forge_ops_tracker/middleware/user_context"
 
 module ForgeOpsTracker
   class << self
@@ -17,6 +23,50 @@ module ForgeOpsTracker
     def configure
       yield configuration
     end
+
+    # Records a named business metric (a signup, a payment, anything a customer wants to name),
+    # buffered and flushed periodically as a batch rather than one network call per capture (see
+    # MetricBuffer). value defaults to 1.0 so a bare counter-style call ("a signup happened")
+    # needs no argument; pass an explicit one for a metric with a real magnitude ("a $49 payment
+    # happened"). A no-op, same as every other capture path in this gem, when the gem isn't
+    # enabled (no DSN configured, or the current environment isn't in enabled_environments).
+    def capture_metric(name, value: 1.0)
+      return unless configuration.enabled?
+
+      metric_buffer.record(metric_name: name, value: value)
+    end
+
+    # Records one infrastructure reading (CPU/memory/disk, or anything else a customer's own
+    # script reads) from one of their own hosts. hostname defaults to Configuration#server_name
+    # (already derived from Socket.gethostname), so a script running on the box it's reporting
+    # about doesn't need to pass one explicitly. Same buffered-batch delivery and no-op-when-
+    # disabled contract as capture_metric above.
+    def capture_infrastructure_metric(name, value:, hostname: nil)
+      return unless configuration.enabled?
+
+      infrastructure_metric_buffer.record(metric_name: name, value: value, hostname: hostname || configuration.server_name)
+    end
+
+    # Manually attaches an affected user to whatever gets reported for the rest of this request
+    # (or, outside a request entirely, in a background job or a console session, for the rest of
+    # this thread). Sets the same thread-local ForgeOpsTracker::Middleware::UserContext's own
+    # Warden auto-detection uses, so this composes with it rather than being a second, separate
+    # mechanism: call this after that middleware ran to override its guess, or call it standalone
+    # in an app with no Warden at all. id/email/username are all independently optional; a call
+    # with none of them (or all nil) clears whatever was set.
+    def set_user(id: nil, email: nil, username: nil)
+      user = { id: id, email: email, username: username }.compact
+      Thread.current[:forge_ops_tracker_current_user] = user.empty? ? nil : user
+    end
+
+    private
+      def metric_buffer
+        @metric_buffer ||= MetricBuffer.new(configuration)
+      end
+
+      def infrastructure_metric_buffer
+        @infrastructure_metric_buffer ||= InfrastructureMetricBuffer.new(configuration)
+      end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge_ops_tracker
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ForgeOps
@@ -23,6 +23,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  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: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 description: Hooks Rails' error reporter and reports exceptions to a ForgeOps exception
   tracker instance over HTTP, without ever raising back into the host application.
 executables: []
@@ -38,7 +80,17 @@ files:
 - lib/forge_ops_tracker/delivery_queue.rb
 - lib/forge_ops_tracker/error_subscriber.rb
 - lib/forge_ops_tracker/event_builder.rb
+- lib/forge_ops_tracker/infrastructure_metric_buffer.rb
+- lib/forge_ops_tracker/integrations/net_http.rb
+- lib/forge_ops_tracker/integrations/puma.rb
+- lib/forge_ops_tracker/integrations/sidekiq.rb
+- lib/forge_ops_tracker/integrations/solid_queue.rb
+- lib/forge_ops_tracker/metric_buffer.rb
 - lib/forge_ops_tracker/middleware/session_tracking.rb
+- lib/forge_ops_tracker/middleware/user_context.rb
+- lib/forge_ops_tracker/performance_flusher.rb
+- lib/forge_ops_tracker/performance_instrumentation.rb
+- lib/forge_ops_tracker/periodic_poller.rb
 - lib/forge_ops_tracker/pii_scrubber.rb
 - lib/forge_ops_tracker/railtie.rb
 - lib/forge_ops_tracker/session_flusher.rb