forge_ops_tracker 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 073a3b64414a46750408cc7824f0edd39ecdfa1a27a9b6ad6aee7c747c90f334
+  data.tar.gz: c5a4c430bfc726d62f45475dcc33eb453651cc99a575d3606433036afb51adf5
+SHA512:
+  metadata.gz: cb8dbef976d942b852e8f0cfa84a46277534f0835df4ab33a3c515a8a5ce1d1accf90f1f72ad8841130fb977e8a2a7e2cfdc97757b8fe98e883f57691082b642
+  data.tar.gz: 200daa5942120bb078c0203914684dd42c0722db024639188528b569a6a2661a0b3276c7c32108f31685985f27fbe942b136feac7795f16432f2666f76b6e238

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0
+
+- Client-side PII scrubbing: payloads are scrubbed (email addresses, formatted SSNs/credit
+  cards, known API key/token formats, and any field whose name suggests a secret) before they
+  ever leave the host app's process, not just on arrival at the ForgeOps server. On by default;
+  `config.scrub_pii = false` opts out.
+
+## 0.1.0
+
+- Initial release: a Railtie subscribing to `Rails.error`, so unhandled exceptions and job
+  failures report automatically with no further wiring. Delivery runs 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.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# ForgeOpsTracker
+
+Rails exception reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+
+## Installation
+
+```ruby
+gem "forge_ops_tracker", path: "gems/forge_ops_tracker" # or git: "..." once split into its own repo
+```
+
+## Configuration
+
+Set a DSN (from a project's settings page in ForgeOps) via an initializer or environment variable:
+
+```ruby
+# config/initializers/forge_ops_tracker.rb
+ForgeOpsTracker.configure do |config|
+  config.dsn = ENV["FORGE_OPS_DSN"] # "https://<api_key>@forgeops.example.com/api/v1/events"
+  config.release = ENV["HEROKU_SLUG_COMMIT"] || `git rev-parse HEAD`.strip
+  config.enabled_environments = %w[production staging] # default; reporting is a no-op elsewhere
+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
+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
+other code changes.
+
+**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
+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.
+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
+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 --
+# execution continues past the block either way.
+```
+
+Or `Rails.error.record`, if you want it reported *and* still raised (e.g. so a background job's
+own retry logic still sees the failure):
+
+```ruby
+Rails.error.record { charge_card(order) } # reports, then re-raises
+```
+
+Bottom line: if an exception would otherwise crash something, you're already covered. If your own
+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.
+
+## 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
+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.
+
+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):
+
+```ruby
+ForgeOpsTracker.configure do |config|
+  config.scrub_pii = false
+end
+```

data/lib/forge_ops_tracker/client.rb

@@ -0,0 +1,49 @@
+require "net/http"
+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
+  # `false` return rather than a raised exception, since a broken or
+  # unreachable tracker must never be able to break the host app.
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+    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
+    end
+
+    private
+      attr_reader :configuration
+
+      def http_for(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = configuration.open_timeout
+        http.read_timeout = configuration.read_timeout
+        http
+      end
+
+      def build_request(uri, payload)
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Authorization"] = "Bearer #{configuration.api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(payload)
+        request
+      end
+
+      def log
+        configuration.logger&.debug { "[ForgeOpsTracker] #{yield}" }
+      end
+  end
+end

data/lib/forge_ops_tracker/configuration.rb

@@ -0,0 +1,68 @@
+require "uri"
+require "socket"
+
+module ForgeOpsTracker
+  class Configuration
+    # A single Sentry-style 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
+
+    def initialize
+      @dsn = ENV["FORGE_OPS_DSN"]
+      @environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      @release = ENV["FORGE_OPS_RELEASE"]
+      @server_name = safe_hostname
+      @enabled_environments = %w[production staging]
+      @queue_size = 1000
+      @open_timeout = 2
+      @read_timeout = 2
+      @logger = nil
+      # 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
+      # the only sane default.
+      @scrub_pii = true
+    end
+
+    def api_key
+      parsed_dsn&.user
+    end
+
+    # The ingestion URL with credentials stripped out (they travel as the
+    # Authorization header instead, not embedded in the request URI).
+    def ingestion_uri
+      return nil unless parsed_dsn
+
+      uri = parsed_dsn.dup
+      uri.user = nil
+      uri.password = nil
+      uri
+    end
+
+    def enabled?
+      !blank?(dsn) && !blank?(api_key) && enabled_environments.map(&:to_s).include?(environment.to_s)
+    end
+
+    private
+      def parsed_dsn
+        return nil if blank?(dsn)
+
+        @parsed_dsn ||= URI.parse(dsn)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      def safe_hostname
+        Socket.gethostname
+      rescue StandardError
+        nil
+      end
+  end
+end

data/lib/forge_ops_tracker/delivery_queue.rb

@@ -0,0 +1,57 @@
+require "thread"
+
+module ForgeOpsTracker
+  # A small in-process background thread + bounded queue, so delivery never
+  # blocks the request that raised the error and never depends on the host
+  # app having any particular job backend configured. The worker thread is
+  # started lazily on first push (not at load time), so it's created fresh
+  # in each forked Puma/Passenger worker process rather than being carried
+  # across a fork, which would leave it dead in the child.
+  class DeliveryQueue
+    def initialize(configuration, client: Client.new(configuration))
+      @configuration = configuration
+      @client = client
+      @queue = SizedQueue.new(configuration.queue_size)
+      @mutex = Mutex.new
+      @thread = nil
+    end
+
+    # Enqueues a payload, dropping it silently (never blocking the caller)
+    # if the queue is already full -- a burst of exceptions must never apply
+    # backpressure to the host app.
+    def push(payload)
+      ensure_worker_started
+      @queue.push(payload, true)
+      true
+    rescue ThreadError
+      log { "delivery queue full, dropping event" }
+      false
+    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
+          client.deliver(@queue.pop)
+        rescue StandardError => e
+          log { "delivery thread error: #{e.class}: #{e.message}" }
+        end
+      end
+
+      def log
+        configuration.logger&.debug { "[ForgeOpsTracker] #{yield}" }
+      end
+  end
+end

data/lib/forge_ops_tracker/error_subscriber.rb

@@ -0,0 +1,27 @@
+module ForgeOpsTracker
+  # Implements the subscriber interface Rails.error.subscribe expects
+  # (#report). An error reporter that itself raises while reporting an
+  # error is the worst possible failure mode, so every path here is
+  # wrapped to guarantee this never propagates an exception back into the
+  # host app's error-handling cycle.
+  class ErrorSubscriber
+    def initialize(configuration, delivery_queue: DeliveryQueue.new(configuration), event_builder: EventBuilder.new(configuration))
+      @configuration = configuration
+      @delivery_queue = delivery_queue
+      @event_builder = event_builder
+    end
+
+    def report(error, handled: true, severity: nil, context: {}, source: nil)
+      return unless configuration.enabled?
+
+      delivery_queue.push(event_builder.build(error, context: context))
+      nil
+    rescue StandardError => e
+      configuration.logger&.debug { "[ForgeOpsTracker] report failed: #{e.class}: #{e.message}" }
+      nil
+    end
+
+    private
+      attr_reader :configuration, :delivery_queue, :event_builder
+  end
+end

data/lib/forge_ops_tracker/event_builder.rb

@@ -0,0 +1,73 @@
+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 --
+  # 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
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def build(error, context: {})
+      payload = {
+        exception_class: error.class.name,
+        message: error.message.to_s,
+        backtrace: backtrace_frames(error),
+        occurred_at: Time.now.utc.iso8601,
+        environment: configuration.environment.to_s,
+        release: configuration.release,
+        server_name: configuration.server_name,
+        context: context || {},
+        tags: {}
+      }
+      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.
+      def scrub(payload)
+        return payload unless configuration.scrub_pii
+
+        payload.merge(
+          message: PiiScrubber.scrub(payload[:message]),
+          backtrace: PiiScrubber.scrub(payload[:backtrace]),
+          context: PiiScrubber.scrub(payload[:context]),
+          tags: PiiScrubber.scrub(payload[:tags])
+        )
+      end
+
+      def backtrace_frames(error)
+        Array(error.backtrace).first(MAX_FRAMES).filter_map { |line| parse_backtrace_line(line) }
+      end
+
+      def parse_backtrace_line(line)
+        match = LINE_PATTERN.match(line.to_s)
+        return nil unless match
+
+        file = match[:file]
+        {
+          file: file,
+          line: match[:line].to_i,
+          method: match[:method]&.gsub(/\A[`'"]|['"]\z/, ""),
+          in_app: in_app?(file)
+        }
+      end
+
+      def in_app?(file)
+        root = configuration.app_root
+        return false if root.nil? || root.to_s.empty?
+
+        file.start_with?(root.to_s) && !file.include?("/gems/") && !file.include?("/bundle/")
+      end
+  end
+end

data/lib/forge_ops_tracker/pii_scrubber.rb

@@ -0,0 +1,70 @@
+module ForgeOpsTracker
+  # Redacts likely-sensitive content out of a payload before it ever leaves
+  # this process -- the same patterns ForgeOps itself applies again on
+  # arrival (defense in depth: this layer keeps the data off the wire and
+  # out of any request logging in between; the server-side layer is what
+  # actually protects the database, and doesn't depend on every reporting
+  # app running an up-to-date version of this gem). See the main
+  # application's PiiScrubber for the shared design rationale -- kept as a
+  # separate, dependency-free implementation here rather than requiring the
+  # private app's code, since this gem has to work standalone in any host
+  # app regardless of what's reporting into it.
+  #
+  # Can be turned off via configuration.scrub_pii = false for a host app
+  # that already scrubs its own data before it ever reaches error context,
+  # or that has its own reasons to want the raw payload. Off by default is
+  # not an option: the safe default has to be "on."
+  module PiiScrubber
+    REDACTED = "[FILTERED]"
+
+    SENSITIVE_KEYS = %w[
+      password passwd pwd
+      secret apisecret clientsecret secretkey
+      token accesstoken refreshtoken apikey apitoken authorization authtoken bearer sessiontoken csrftoken
+      creditcard cardnumber cardnum cvv cvv2 cvc
+      ssn socialsecuritynumber socialsecurity
+      privatekey
+    ].freeze
+
+    PATTERNS = {
+      "EMAIL" => /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/,
+      "SSN" => /\b\d{3}-\d{2}-\d{4}\b/,
+      "CREDIT CARD" => /\b\d{4}[ -]\d{4}[ -]\d{4}[ -]\d{1,4}\b/,
+      "BEARER TOKEN" => %r{\bBearer\s+[A-Za-z0-9\-._~+/]+=*}i,
+      "JWT" => /\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+      "AWS KEY" => /\bAKIA[0-9A-Z]{16}\b/,
+      "STRIPE KEY" => /\b[sr]k_(?:live|test)_[A-Za-z0-9]{10,}\b/,
+      "GITHUB TOKEN" => /\bgh[pousr]_[A-Za-z0-9]{20,}\b/
+    }.freeze
+
+    def self.scrub(value, key: nil)
+      if sensitive_key?(key) && !value.nil?
+        REDACTED
+      else
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), out| out[k] = scrub(v, key: k) }
+        when Array
+          value.map { |v| scrub(v, key: key) }
+        when String
+          scrub_string(value)
+        else
+          value
+        end
+      end
+    end
+
+    def self.sensitive_key?(key)
+      return false if key.nil?
+
+      normalized = key.to_s.downcase.gsub(/[^a-z0-9]/, "")
+      SENSITIVE_KEYS.any? { |sensitive| normalized.include?(sensitive) }
+    end
+    private_class_method :sensitive_key?
+
+    def self.scrub_string(string)
+      PATTERNS.reduce(string) { |scrubbed, (label, pattern)| scrubbed.gsub(pattern, "[#{label} FILTERED]") }
+    end
+    private_class_method :scrub_string
+  end
+end

data/lib/forge_ops_tracker/railtie.rb

@@ -0,0 +1,14 @@
+require "rails/railtie"
+
+module ForgeOpsTracker
+  class Railtie < ::Rails::Railtie
+    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
+      configuration.logger ||= Rails.logger
+
+      Rails.error.subscribe(ForgeOpsTracker::ErrorSubscriber.new(configuration))
+    end
+  end
+end

data/lib/forge_ops_tracker/version.rb

@@ -0,0 +1,3 @@
+module ForgeOpsTracker
+  VERSION = "0.2.0"
+end

data/lib/forge_ops_tracker.rb

@@ -0,0 +1,21 @@
+require "forge_ops_tracker/version"
+require "forge_ops_tracker/configuration"
+require "forge_ops_tracker/pii_scrubber"
+require "forge_ops_tracker/event_builder"
+require "forge_ops_tracker/client"
+require "forge_ops_tracker/delivery_queue"
+require "forge_ops_tracker/error_subscriber"
+
+module ForgeOpsTracker
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end
+
+require "forge_ops_tracker/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: forge_ops_tracker
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- ForgeOps
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Hooks Rails' error reporter and reports exceptions to a private ForgeOps
+  exception tracker instance over HTTP, without ever raising back into the host application.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/forge_ops_tracker.rb
+- lib/forge_ops_tracker/client.rb
+- lib/forge_ops_tracker/configuration.rb
+- 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/pii_scrubber.rb
+- lib/forge_ops_tracker/railtie.rb
+- lib/forge_ops_tracker/version.rb
+homepage: https://getforgeops.net
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://getforgeops.net
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Rails exception reporting client for a self-hosted ForgeOps tracker
+test_files: []