forge_ops_tracker 0.2.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 461cec25deb5d055e670ab0bf6e9fbc3cc7183fee4b9e7e731cbefabc4c615f3
-  data.tar.gz: d7fe09d86a29c7ecca952c0f9ee5bfaa839bdf8541c1d787e7b752e599c33347
+  metadata.gz: 72692319cfdf068129d7d005773e21a3b6b78cb9f7816cf0e7c8e6409c9704f1
+  data.tar.gz: 713f244a7ab71a005e66b7f00d1dff3e1e3ffc44e304d5a36f79c911e508c74b
 SHA512:
-  metadata.gz: 50c03a3c07c566d8a665fcf79996ce41b4f5012e35bca1e369da9b1d1de71ebda6d429d25e025a3f15054f93287406d5656dd7e54ac4f6bc8b0ca6c6fa2497cb
-  data.tar.gz: 2ecb9ce97ec67a22b3f21d3e6945bdc3bd45f2c7199fd92834756d9081c3ccc25694d8226933a6c72de8f0efc4be4658dfe1061beba36c3998e45c181cba2f37
+  metadata.gz: 57f5372fc1aa6ac8f8830804003c00d68d0633d4f330dc8f6c678faa1c1dbc3f09ad1da0f29c180c63a90dc41f2d0f6acb008e4a726d59ba6b806298af3d6d8f
+  data.tar.gz: 2b21f12200f99202c5f26cc739104021d5eaf1cfe16a01b075fe4bc3418ada28cf7befb91470fb1ebd8bb18865cd52e61a705decc5f511c2c497a79c74c36016

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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
+  dashboard auto-detects from whichever SDK is actually reporting into it, rather than staying
+  stuck on whatever it was created with. Never overrides a language picked by hand in project
+  settings.
+
+## 0.4.0
+
+- Session tracking (release health): every request is now counted as a session, crash-free unless
+  an unhandled exception actually escapes it, so the ForgeOps dashboard can show a crash-free rate
+  per release rather than only ever hearing about the requests that broke. Counted in-process and
+  flushed as a small periodic aggregate (`config.session_flush_interval`, default 60 seconds) on
+  its own background thread, not one network call per request. On by default, the same as error
+  tracking itself (`config.track_sessions = false` opts out); requires a ForgeOps plan that
+  includes release health, checked server-side on every flush.
+
+## 0.3.0
+
+- Source context capture: each in-app backtrace frame can now carry the 5 lines of source on
+  either side of the culprit line, read straight off disk at raise-time, so an issue's detail page
+  can show the actual code that broke, not just a file:line:method reference. On by default
+  (`config.capture_source_context = false` opts out), but the real, durable protection is a
+  per-project setting on the ForgeOps server, not this flag: turning it off there stops the server
+  from ever storing captured source lines for that project again, regardless of what any individual
+  app's own local setting is still set to. Never applies to a frame outside your app's own code,
+  and fails silently for any file that can't be read.
+
 ## 0.2.0
 
 - Client-side PII scrubbing: payloads are scrubbed (email addresses, formatted SSNs/credit

data/README.md

@@ -1,6 +1,6 @@
 # ForgeOpsTracker
 
-Rails exception reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+Rails exception reporting client for a [ForgeOps](../../) instance.
 
 ## Installation
 
@@ -22,17 +22,17 @@ end
 ```
 
 Delivery happens on a small background thread with a bounded queue and short HTTP timeouts. Every
-failure mode -- network errors, timeouts, a full queue, a malformed DSN -- is caught and dropped
+failure mode (network errors, timeouts, a full queue, a malformed DSN) is caught and dropped
 rather than raised, so a broken or unreachable tracker can never take down the host app.
 
 ## What gets reported automatically, and what doesn't
 
 **Unhandled exceptions need no further wiring at all.** The gem's Railtie subscribes to
 `Rails.error` automatically, and Rails itself reports anything that crashes a request or job
-through that same channel -- install the gem, set a DSN, and those show up in ForgeOps with zero
+through that same channel: install the gem, set a DSN, and those show up in ForgeOps with zero
 other code changes.
 
-**Handled exceptions -- code that catches its own error to keep running -- are a different story.**
+**Handled exceptions (code that catches its own error to keep running) are a different story.**
 A plain `rescue` the gem never hears about, no matter what:
 
 ```ruby
@@ -40,19 +40,19 @@ begin
   charge_card(order)
 rescue Stripe::CardError => e
   logger.warn("card declined: #{e.message}")
-  # ForgeOps never sees this -- nothing here goes through Rails.error at all.
+  # ForgeOps never sees this: nothing here goes through Rails.error at all.
 end
 ```
 
 To report it *and* keep swallowing it, swap the bare `rescue` for Rails' own built-in
-`Rails.error.handle` -- this isn't a ForgeOps-specific API, it's Rails' own error-reporting
+`Rails.error.handle`: this isn't a ForgeOps-specific API, it's Rails' own error-reporting
 convention (Rails 7+), which the gem just happens to already be subscribed to:
 
 ```ruby
 Rails.error.handle(fallback: -> { nil }) do
   charge_card(order)
 end
-# Reported to every Rails.error subscriber, including this gem, then swallowed --
+# Reported to every Rails.error subscriber, including this gem, then swallowed:
 # execution continues past the block either way.
 ```
 
@@ -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) -- and redacted
+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):
@@ -83,3 +111,156 @@ ForgeOpsTracker.configure do |config|
   config.scrub_pii = false
 end
 ```
+
+## Source context
+
+By default, each in-app backtrace frame (never a vendored gem) is captured along with the 5 lines
+of source on either side of the culprit line, read straight off disk at raise-time, so an issue's
+detail page can show the actual code that broke, not just a `file:line:method` reference. This
+never applies to a frame outside `app_root`, and it fails silently (no context, not an error) for
+any file that can't be read for whatever reason.
+
+This is a real, deliberate exception to "off by default is safer": literal source code is being
+transmitted, not just a reference to it, and the real protection here is not this flag. Every
+project on ForgeOps has its own setting (on by default, off durably and immediately once an org
+owner turns it off, regardless of what any individual app's own `config.capture_source_context` is
+still set to) that governs whether the server will ever actually store what an SDK sends; see the
+in-app help docs. Use this flag if you'd rather this gem never even attempt the disk read in the
+first place:
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.capture_source_context = false
+end
+```
+
+## Session tracking (release health)
+
+By default, every request is counted as a session: crash-free unless an unhandled exception
+actually escapes it, giving ForgeOps a crash-free rate per release to show alongside the errors
+themselves, not just the errors on their own. Counted in-process and flushed as a small periodic
+aggregate on a background thread (never one network call per request), the same delivery
+philosophy as everything else in this gem: a broken or unreachable tracker never affects the host
+app either way.
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.track_sessions = false   # opt out entirely
+  config.session_flush_interval = 30 # seconds; default 60
+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

@@ -3,8 +3,8 @@ require "json"
 require "uri"
 
 module ForgeOpsTracker
-  # Delivers one payload over HTTP. Every failure mode -- DNS, connection,
-  # timeout, TLS, a non-2xx response -- is caught here and turned into a
+  # Delivers one payload over HTTP. Every failure mode; DNS, connection,
+  # timeout, TLS, a non-2xx response; is caught here and turned into a
   # `false` return rather than a raised exception, since a broken or
   # unreachable tracker must never be able to break the host app.
   class Client
@@ -13,19 +13,49 @@ module ForgeOpsTracker
     end
 
     def deliver(payload)
-      uri = configuration.ingestion_uri
-      return false unless uri
-
-      response = http_for(uri).request(build_request(uri, payload))
-      response.is_a?(Net::HTTPSuccess)
-    rescue StandardError => e
-      log { "delivery failed: #{e.class}: #{e.message}" }
-      false
+      post(configuration.ingestion_uri, payload)
+    end
+
+    # Same delivery contract as deliver above (never raises, returns a bare
+    # true/false), just a different endpoint under the same DSN's host and
+    # api_key; see Configuration#session_checkins_uri.
+    def deliver_session_checkin(payload)
+      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
 
+      def post(uri, payload)
+        return false unless uri
+
+        response = http_for(uri).request(build_request(uri, payload))
+        response.is_a?(Net::HTTPSuccess)
+      rescue StandardError => e
+        log { "delivery failed: #{e.class}: #{e.message}" }
+        false
+      end
+
       def http_for(uri)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"

data/lib/forge_ops_tracker/configuration.rb

@@ -3,10 +3,16 @@ require "socket"
 
 module ForgeOpsTracker
   class Configuration
-    # A single Sentry-style DSN string carries both the ingestion URL and
+    # A single DSN string carries both the ingestion URL and
     # the project's api_key: "https://<api_key>@host/api/v1/events".
     attr_accessor :dsn, :environment, :release, :server_name, :app_root, :logger
     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"]
@@ -18,13 +24,53 @@ module ForgeOpsTracker
       @open_timeout = 2
       @read_timeout = 2
       @logger = nil
-      # See PiiScrubber -- redacts likely-sensitive content (emails,
+      # See PiiScrubber; redacts likely-sensitive content (emails,
       # credit cards, known API key formats, anything under a
       # suspiciously-named key) before a payload ever leaves this
       # process. ForgeOps itself scrubs again on arrival regardless, so
-      # this is a second, earlier layer, not the only one -- but "on" is
+      # this is a second, earlier layer, not the only one; but "on" is
       # the only sane default.
       @scrub_pii = true
+      # Whether EventBuilder reads a few lines of source off disk around
+      # each in-app frame's culprit line (see EventBuilder#attach_source_context).
+      # Defaults on so a snippet shows up without extra setup, but this flag
+      # alone isn't the real protection against sending proprietary source
+      # code somewhere it shouldn't go: ForgeOps' own per-project setting is
+      # the durable, server-enforced off switch, since it applies regardless
+      # of what this flag happens to be set to on any given deployment, and
+      # can't drift back on the way a local config value could. Turn this
+      # off here too if this host app never wants that disk read attempted
+      # in the first place.
+      @capture_source_context = true
+      # Auto-instruments every request the moment the gem loads, the same "on unless you turn it
+      # off" default error tracking itself already has; nothing else in this gem is opt-in. See
+      # 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
@@ -42,6 +88,46 @@ module ForgeOpsTracker
       uri
     end
 
+    # Same host and api_key as ingestion_uri, a sibling path under the same DSN rather than a
+    # second DSN to configure; the DSN's own path is always /api/v1/events (what ForgeOps issues
+    # to every project), so the session-checkins endpoint is derived by substitution.
+    def session_checkins_uri
+      uri = ingestion_uri
+      return nil unless uri
+
+      uri = uri.dup
+      uri.path = uri.path.sub(%r{/events\z}, "/session_checkins")
+      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/delivery_queue.rb

@@ -17,7 +17,7 @@ module ForgeOpsTracker
     end
 
     # Enqueues a payload, dropping it silently (never blocking the caller)
-    # if the queue is already full -- a burst of exceptions must never apply
+    # if the queue is already full; a burst of exceptions must never apply
     # backpressure to the host app.
     def push(payload)
       ensure_worker_started

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

@@ -2,18 +2,32 @@ require "time"
 
 module ForgeOpsTracker
   # Turns a raised exception into the JSON-able payload shape the ingestion
-  # API expects. Backtrace parsing is a simple regex, not a full parser --
+  # API expects. Backtrace parsing is a simple regex, not a full parser:
   # good enough for standard MRI backtrace lines across Ruby versions
   # (both the older `in \`method'` and newer `in 'method'` quoting styles).
   class EventBuilder
     LINE_PATTERN = /\A(?<file>.+?):(?<line>\d+)(?::in\s+(?<method>.+))?\z/
     MAX_FRAMES = 500
 
+    # Identifies this gem to the server's auto language-detection on the project the event lands
+    # in (see Project#note_sdk_platform server-side); "ruby", matching this repo's own sdks/
+    # directory naming for every other language's client.
+    SDK_NAME = "ruby".freeze
+
+    # How many lines of source to grab on either side of the culprit line
+    # (see #attach_source_context), and the longest a single captured line
+    # is allowed to be before getting truncated; guards against a single
+    # pathological minified/generated line ballooning the payload. ForgeOps
+    # itself re-truncates on arrival too, the same "don't just trust the
+    # SDK" posture MAX_FRAMES already gets on the server side.
+    CONTEXT_LINES = 5
+    MAX_CONTEXT_LINE_LENGTH = 500
+
     def initialize(configuration)
       @configuration = configuration
     end
 
-    def build(error, context: {})
+    def build(error, context: {}, user: nil)
       payload = {
         exception_class: error.class.name,
         message: error.message.to_s,
@@ -23,18 +37,21 @@ module ForgeOpsTracker
         release: configuration.release,
         server_name: configuration.server_name,
         context: context || {},
-        tags: {}
+        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 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
 
@@ -55,12 +72,13 @@ module ForgeOpsTracker
         return nil unless match
 
         file = match[:file]
-        {
+        frame = {
           file: file,
           line: match[:line].to_i,
           method: match[:method]&.gsub(/\A[`'"]|['"]\z/, ""),
           in_app: in_app?(file)
         }
+        attach_source_context(frame)
       end
 
       def in_app?(file)
@@ -69,5 +87,43 @@ module ForgeOpsTracker
 
         file.start_with?(root.to_s) && !file.include?("/gems/") && !file.include?("/bundle/")
       end
+
+      # Reads a few lines of source straight off disk around the culprit
+      # line, at raise-time, in the same running process the exception came
+      # from. Gated on two things: the frame has to be in-app (never a
+      # vendored dependency; there'd be nothing meaningful to show, and
+      # it's not the host app's own code to begin with), and
+      # configuration.capture_source_context has to be on (see
+      # Configuration for why it defaults to true and why ForgeOps' own
+      # per-project setting, not this flag, is the durable, protected way
+      # to turn it off). Best-effort: any file that can't be read (deleted,
+      # permission denied, a path that only ever existed inside a build
+      # step and isn't present in this deployment) just means this one
+      # frame gets no source context, not a raised error of its own.
+      def attach_source_context(frame)
+        return frame unless configuration.capture_source_context && frame[:in_app]
+
+        lines = File.readlines(frame[:file])
+        index = frame[:line] - 1
+        return frame unless index.between?(0, lines.length - 1)
+
+        from = [ index - CONTEXT_LINES, 0 ].max
+        to = [ index + CONTEXT_LINES, lines.length - 1 ].min
+
+        frame.merge(
+          context_line: truncate_line(lines[index]),
+          pre_context: lines[from...index].map { |source_line| truncate_line(source_line) },
+          post_context: lines[(index + 1)..to].map { |source_line| truncate_line(source_line) }
+        )
+      rescue SystemCallError, IOError
+        frame
+      end
+
+      def truncate_line(line)
+        line = line.chomp
+        return line if line.length <= MAX_CONTEXT_LINE_LENGTH
+
+        "#{line[0, MAX_CONTEXT_LINE_LENGTH]}..."
+      end
   end
 end