forge_ops_tracker 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81c08199bfeae97d20295b7c04a46dc3b9dd9be519d4790404b88e2ca514fbe1
-  data.tar.gz: dad1efa10164cebcbce9452c1f903812157143e871162076f09298ebf41a6ea7
+  metadata.gz: a535fb7cb193fd614ee40259a9b20e62832149c7a2dbeb7d1d40253c0630f65a
+  data.tar.gz: 559a19cd52a56addacc87c5533bc0954c7ca2de6eac81a6afb18769f280c06c5
 SHA512:
-  metadata.gz: 2a32b34300ee005cd09be7f188275091ec9ba8cf4ef2e65044176a7e6d1427feef170cbc44dbd9f7a25dcf0073b2afb6186db3db2069a5737bfdcb274e62cc7f
-  data.tar.gz: 4431641c5e95f757dd82e7af0015de824804610ee4ebf252cbe3a4db13ca5f5aa1cac5fda274a94833be652a9d6c5e25ab4406570d4790b165cf242f8490ff66
+  metadata.gz: 158342795c1dbb5e7575da43ddcd239c25b52111c268ede3fdfdbb9b5621cf1a10cd120e602f75fe2e57bd46faed9483aaa1a61f8c9f91770474210414400e8f
+  data.tar.gz: 5b4f11f1758833c58f8925f1354f8a7da49b80d04344cc2c340a2662a186fcfc0a8451709faef4c78a60d618c9f0ea936c460c97b3af8bad2687fbc8f6fbfdae

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.16.0 (2026-10-02)
+
+- Changed: outside Rails, the environment now defaults to `production` when nothing sets it (it
+  was `development`). It comes from `FORGE_OPS_ENVIRONMENT`, then `RAILS_ENV`, then `RACK_ENV`,
+  then `production`. Only `production` and `staging` send by default, so before this a plain Ruby
+  or Rack process that set just a DSN sent nothing at all. To keep the old behavior there, set
+  `FORGE_OPS_ENVIRONMENT=development` (or `RACK_ENV=development`, or `config.environment`).
+- Changed: under Rails, `FORGE_OPS_ENVIRONMENT` now takes precedence over `Rails.env` when it's
+  set. Without it nothing changes: development and test still don't send.
+- When a DSN is set but the environment isn't in `enabled_environments`, one warning is now logged
+  per process, naming the environment and how to send from it: at boot under Rails (to
+  `Rails.logger`), otherwise from `configure`, the Rack middleware, or `capture_exception` (to
+  `config.logger`, or stderr when there isn't one). Nothing is logged when no DSN is set.
+- New `ForgeOpsTracker.capture_exception(error, context: {})` reports an exception you've rescued,
+  through the same path `Rails.error` reports into, so it works without Rails too.
+- Plain Rack and Sinatra apps are now covered: `use ForgeOpsTracker::Middleware::RequestContext`
+  reports an exception escaping the app, and an error Sinatra itself turned into a 5xx response.
+  Under Rails it still only adds request context, since `Rails.error` already reports those.
+
 ## 0.15.1 (2026-10-01)
 
 - Errors reported just before a process exits are now sent before it ends. Delivery runs on a

data/README.md

@@ -1,6 +1,7 @@
 # ForgeOpsTracker
 
-Rails exception reporting client for [ForgeOps](https://getforgeops.net).
+Exception reporting client for [ForgeOps](https://getforgeops.net), for Rails, plain Rack and
+Sinatra apps, and scripts.
 
 ## Installation
 
@@ -25,6 +26,11 @@ ForgeOpsTracker.configure do |config|
 end
 ```
 
+The environment is `FORGE_OPS_ENVIRONMENT` when set, otherwise `Rails.env` under Rails, and
+outside Rails `RAILS_ENV`, then `RACK_ENV`, then `production`. Only `production` and `staging`
+send by default, so a Rails app in development or test doesn't report. When a DSN is set but the
+environment isn't enabled, one warning is logged per process (at boot under Rails) saying so.
+
 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
 rather than raised, so a broken or unreachable tracker can never take down the host app.
@@ -71,6 +77,34 @@ 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.
 
+### Outside Rails: Rack, Sinatra, and scripts
+
+Without Rails there's no `Rails.error`, so add the Rack middleware, which reports any exception
+escaping your app (and, in Sinatra, an error it turned into a 5xx response itself), then re-raises
+it unchanged:
+
+```ruby
+# config.ru, or inside a Sinatra::Base subclass
+require "forge_ops_tracker"
+
+ForgeOpsTracker.configure do |config|
+  config.dsn = ENV["FORGE_OPS_DSN"]
+end
+
+use ForgeOpsTracker::Middleware::RequestContext
+```
+
+Report an exception you rescued yourself, anywhere (Rails included), with
+`ForgeOpsTracker.capture_exception`:
+
+```ruby
+begin
+  charge_card(order)
+rescue Stripe::CardError => e
+  ForgeOpsTracker.capture_exception(e, context: { order_id: order.id })
+end
+```
+
 ### Sidekiq job failures and renamed job classes
 
 A failing Sidekiq job is reported through `Rails.error` like any other error. Since 0.10.1 the issue
@@ -254,7 +288,7 @@ 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.
+flushes are accepted but not recorded, and the response says why.
 
 ## Performance monitoring
 
@@ -279,8 +313,7 @@ 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.
+periodic flushes are accepted but not recorded, and the response says why.
 
 ### Database queries, background jobs, and outbound HTTP calls
 
@@ -353,8 +386,7 @@ unaffected: confirmed directly that Net::HTTP connects lazily, inside `#request`
 time it's called on a not-yet-started instance.
 
 Requires a ForgeOps plan that includes performance monitoring, the same plan feature performance
-monitoring itself already requires; on a plan that doesn't, the periodic flushes are simply
-rejected server-side and dropped, exactly like any other delivery failure.
+monitoring itself already requires; on a plan that doesn't, the periodic flushes are accepted but not recorded, and the response says why.
 
 ## Tracing
 
@@ -408,7 +440,7 @@ end
 ```
 
 Requires a ForgeOps plan that includes distributed tracing; on a plan that doesn't, traces are
-simply rejected server-side and dropped, exactly like any other delivery failure. The `trace_id`
+accepted but not recorded, and the response says why. The `trace_id`
 on error events is sent either way.
 
 ### The SQL behind each database span
@@ -476,7 +508,7 @@ What it doesn't do:
 It does use one pooled connection, briefly, for each plan. With the limits above that's at most 10
 short checkouts a minute, but on a pool that's already at capacity, leave it off or raise
 `explain_threshold_ms`. Plans are part of performance monitoring; on a plan without it, they're
-rejected server-side and dropped.
+accepted but not recorded, and the response says why.
 
 ## What changed
 
@@ -521,8 +553,8 @@ their values), so an added or removed variable shows up as a change. Names that
 host, like `HOSTNAME`, `PATH`, `PORT`, `LC_*`, and Kubernetes service variables, are left out, as
 are the gem's own `FORGE_OPS_*` settings.
 
-Requires a ForgeOps plan that includes change tracking; on a plan that doesn't, both are rejected
-server-side and dropped, exactly like any other delivery failure.
+Requires a ForgeOps plan that includes change tracking; on a plan that doesn't, both are accepted but not recorded,
+and the response says why.
 
 ## Custom metrics
 
@@ -543,7 +575,7 @@ 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.
+flushes are accepted but not recorded, and the response says why.
 
 ## Infrastructure monitoring
 
@@ -572,5 +604,4 @@ ForgeOpsTracker.capture_infrastructure_metric("disk_used_percent", value: disk_u
 
 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.
+monitoring; on a plan that doesn't, the periodic flushes are accepted but not recorded, and the response says why.

data/lib/forge_ops_tracker/configuration.rb

@@ -23,7 +23,7 @@ module ForgeOpsTracker
 
     def initialize
       @dsn = ENV["FORGE_OPS_DSN"]
-      @environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      @environment = self.class.resolve_environment
       @release = ENV["FORGE_OPS_RELEASE"]
       @server_name = safe_hostname
       @enabled_environments = %w[production staging]
@@ -262,10 +262,39 @@ module ForgeOpsTracker
     end
 
     def enabled?
-      !blank?(dsn) && !blank?(api_key) && enabled_environments.map(&:to_s).include?(environment.to_s)
+      configured? && environment_enabled?
+    end
+
+    # Whether a usable DSN is set, regardless of environment.
+    def configured?
+      !blank?(dsn) && !blank?(api_key)
+    end
+
+    # The one-line warning ForgeOpsTracker.warn_if_environment_disabled logs when a DSN is set but
+    # this environment isn't one that sends, or nil when there's nothing to warn about (no DSN, or
+    # the environment is enabled).
+    def disabled_environment_warning
+      return nil if !configured? || environment_enabled?
+
+      enabled = enabled_environments.map(&:to_s)
+      enabled = enabled.empty? ? "none" : enabled.join(", ")
+      "[ForgeOps] Not sending: this environment is \"#{environment}\", and only #{enabled} are enabled. " \
+        "Set FORGE_OPS_ENVIRONMENT=production (or add \"#{environment}\" to enabled_environments) to send from here."
+    end
+
+    # FORGE_OPS_ENVIRONMENT, then RAILS_ENV, then RACK_ENV, then "production". Defaulting to
+    # "production" means a plain Ruby or Rack process that only sets a DSN actually sends; a Rails
+    # app gets Rails.env from the Railtie instead (unless FORGE_OPS_ENVIRONMENT is set), so
+    # development and test stay quiet there, with one warning at boot when a DSN is set.
+    def self.resolve_environment(env = ENV)
+      [ env["FORGE_OPS_ENVIRONMENT"], env["RAILS_ENV"], env["RACK_ENV"] ].find { |value| value && !value.strip.empty? } || "production"
     end
 
     private
+      def environment_enabled?
+        enabled_environments.map(&:to_s).include?(environment.to_s)
+      end
+
       # Same substitution every *_uri method above spells out by hand: a sibling path under the
       # DSN's own /api/v1/events.
       def sibling_uri(path)

data/lib/forge_ops_tracker/middleware/request_context.rb

@@ -19,6 +19,14 @@ module ForgeOpsTracker
     # Rescues Exception, not StandardError, and always re-raises: this only ever observes an
     # exception on its way out, it never handles one, so there's no reason to let anything slip
     # past without its context attached.
+    #
+    # Outside Rails it is also what reports an unhandled request error, since there's no
+    # Rails.error to do it: add it to a plain Rack or Sinatra app with
+    # `use ForgeOpsTracker::Middleware::RequestContext`. It reports a StandardError escaping the
+    # app, and a Sinatra error the app turned into a 5xx response itself (Sinatra keeps that in
+    # env["sinatra.error"] rather than raising it when raise_errors is off, its production
+    # default). report_exceptions defaults to true only when Rails isn't loaded, and the Railtie
+    # passes false, so nothing is reported twice under Rails.
     class RequestContext
       THREAD_KEY = :forge_ops_tracker_request_context
 
@@ -28,9 +36,13 @@ module ForgeOpsTracker
       # app raised them.
       SNAPSHOT_IVAR = :@__forge_ops_tracker_request_snapshot
 
-      def initialize(app, configuration: ForgeOpsTracker.configuration)
+      FRAMEWORK_ERROR_KEY = "sinatra.error".freeze
+
+      def initialize(app, configuration: ForgeOpsTracker.configuration, report_exceptions: !defined?(::Rails::Railtie))
         @app = app
         @configuration = configuration
+        @report_exceptions = report_exceptions
+        ForgeOpsTracker.warn_if_environment_disabled if report_exceptions && configuration.equal?(ForgeOpsTracker.configuration)
       end
 
       def call(env)
@@ -38,11 +50,14 @@ module ForgeOpsTracker
 
         state = RequestState.for(env)
         Thread.current[THREAD_KEY] = state
-        app.call(env)
+        response = app.call(env)
+        report_framework_error(env, response) if report_exceptions
+        response
       rescue Exception => e
         if state
           state.mark_errored!
           self.class.attach_snapshot(e, state)
+          report(e, env) if report_exceptions && e.is_a?(StandardError)
         end
         raise
       ensure
@@ -84,7 +99,23 @@ module ForgeOpsTracker
       end
 
       private
-        attr_reader :app, :configuration
+        attr_reader :app, :configuration, :report_exceptions
+
+        # Called while this request's RequestState and the other middlewares' thread-locals are
+        # all still set, so the report carries the trace id, user and breadcrumbs.
+        def report(error, env)
+          ForgeOpsTracker.capture_exception(error, context: { "path" => env["PATH_INFO"], "method" => env["REQUEST_METHOD"] }.compact)
+        rescue StandardError
+          nil
+        end
+
+        def report_framework_error(env, response)
+          error = env[FRAMEWORK_ERROR_KEY]
+          return unless error.is_a?(StandardError) && response.is_a?(Array) && response.first.to_i >= 500
+
+          RequestContext.current&.mark_errored!
+          report(error, env)
+        end
     end
   end
 end

data/lib/forge_ops_tracker/railtie.rb

@@ -38,10 +38,19 @@ module ForgeOpsTracker
     initializer "forge_ops_tracker.subscribe_error_reporter" do |app|
       configuration = ForgeOpsTracker.configuration
       configuration.app_root ||= app.root.to_s
-      configuration.environment = Rails.env.to_s
+      # FORGE_OPS_ENVIRONMENT wins when set, so a staging box running RAILS_ENV=production can
+      # still report as staging; otherwise Rails.env, so development and test stay quiet.
+      forge_ops_environment = ENV["FORGE_OPS_ENVIRONMENT"].to_s.strip
+      configuration.environment = forge_ops_environment.empty? ? Rails.env.to_s : forge_ops_environment
       configuration.logger ||= Rails.logger
 
-      Rails.error.subscribe(ForgeOpsTracker::ErrorSubscriber.new(configuration))
+      Rails.error.subscribe(ForgeOpsTracker.error_subscriber)
+    end
+
+    # After every config/initializers file has run, so the DSN and environment are final: one
+    # warning at boot when a DSN is set but this environment doesn't send (development, say).
+    config.after_initialize do
+      ForgeOpsTracker.warn_if_environment_disabled
     end
 
     initializer "forge_ops_tracker.track_sessions" do |app|
@@ -94,7 +103,8 @@ module ForgeOpsTracker
     # PerformanceInstrumentation.controller_endpoint for what each is used for).
     initializer "forge_ops_tracker.request_context" do |app|
       configuration = ForgeOpsTracker.configuration
-      app.middleware.use ForgeOpsTracker::Middleware::RequestContext, configuration: configuration
+      # report_exceptions: false because Rails.error already reports an unhandled request error.
+      app.middleware.use ForgeOpsTracker::Middleware::RequestContext, configuration: configuration, report_exceptions: false
 
       ActiveSupport::Notifications.subscribe("start_processing.action_controller") do |*args|
         next unless configuration.enabled?

data/lib/forge_ops_tracker/version.rb

@@ -1,3 +1,3 @@
 module ForgeOpsTracker
-  VERSION = "0.15.1"
+  VERSION = "0.16.0"
 end

data/lib/forge_ops_tracker.rb

@@ -30,6 +30,8 @@ require "forge_ops_tracker/middleware/span_tracing"
 require "forge_ops_tracker/middleware/request_context"
 
 module ForgeOpsTracker
+  ENVIRONMENT_WARNING_LOCK = Mutex.new
+
   class << self
     def configuration
       @configuration ||= Configuration.new
@@ -37,10 +39,54 @@ module ForgeOpsTracker
 
     # Outside Rails this is also where the startup ChangeSnapshot goes out, since there's no
     # Railtie to send it once the app has booted; under Rails the Railtie sends it instead, after
-    # initialization, when Active Record can report the migration version.
+    # initialization, when Active Record can report the migration version. The same goes for the
+    # one-time "Not sending" warning (see warn_if_environment_disabled).
     def configure
       yield configuration
-      ChangeSnapshot.start(configuration) unless defined?(::Rails::Railtie)
+      return if defined?(::Rails::Railtie)
+
+      warn_if_environment_disabled
+      ChangeSnapshot.start(configuration)
+    end
+
+    # Reports an exception you've already rescued, e.g. from a Sinatra error handler, a plain Rack
+    # app, a script, or a background worker that isn't wired through Rails.error. Goes through the
+    # same ErrorSubscriber Rails.error reports into, so it carries the current request's user,
+    # breadcrumbs and trace the same way, and is a no-op when the gem isn't enabled. Under Rails,
+    # Rails.error.report/handle/record do the same thing. Never raises.
+    def capture_exception(error, context: {})
+      warn_if_environment_disabled unless configuration.enabled?
+      error_subscriber.report(error, handled: true, context: context || {}, source: "application")
+    end
+
+    # The one ErrorSubscriber this process reports through: the Railtie subscribes it to
+    # Rails.error, and capture_exception calls it directly, so both share one delivery queue.
+    def error_subscriber
+      @error_subscriber ||= ErrorSubscriber.new(configuration)
+    end
+
+    # Logs one warning per process when a DSN is set but the environment isn't in
+    # enabled_environments, so a process that would send nothing says so instead of staying
+    # silent. Goes to configuration.logger (Rails.logger under Rails), or $stderr when there isn't
+    # one. Never logs without a DSN. Returns whether it logged.
+    def warn_if_environment_disabled
+      message = configuration.disabled_environment_warning
+      return false unless message
+
+      ENVIRONMENT_WARNING_LOCK.synchronize do
+        return false if @environment_warning_logged
+
+        @environment_warning_logged = true
+      end
+
+      if configuration.logger
+        configuration.logger.warn(message)
+      else
+        Kernel.warn(message)
+      end
+      true
+    rescue StandardError
+      false
     end
 
     # Records one thing that changed in a running system, e.g.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forge_ops_tracker
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - ForgeOps
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.30'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
 description: Hooks Rails' error reporter and reports exceptions to ForgeOps over HTTP,
   without ever raising back into the host application.
 executables: []