errorgap 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b1e9118a26db2870eb0aa90b9a4ef3784138e078d03b2959ce1b064949b53de
-  data.tar.gz: e3da3e394f5aa7961c5956f8fdfa5346696086324b48eedac330e0d95dd42f59
+  metadata.gz: f52bfa8726abcfbc207b98bc4756db649a619595a56298d4c06b73c63d7b8d08
+  data.tar.gz: bf7d11b852e1fffe27e928ccc259fa3589d35997e4d4eeabfa609c19020a16f6
 SHA512:
-  metadata.gz: b8d0f1bae2b1df08c0893e414a8916a4cc7487afa5443eb3c1de0860133baca93d71c29935552c158ec93392b878b44933848e53ed5761aca84fd141014d2702
-  data.tar.gz: a9ba148ab19bba740b6d877403ee628c43f303a27abfdd20347a5728d7860ea1ec792739b3b23c5b1992066cdd309ac457fd28de60fd9bb7cca4af19bddc49b6
+  metadata.gz: 32f5f975ae8555dc20ee6cdde6618ebe5b001ecf89b51bb59e4f4b72cd3a2d64747c5814c60ab590fe26adbfb23f5923dd2c45511c2c22ad4c3b518877917368
+  data.tar.gz: 7aec10caf7eef47f0e593266cfe554ef67aab2c2fb32e03320cfd3e7c1fad88db40b9ececff9241dbb136858c3f85830fe895b6dc6442d789b474cf8c19252bd

data/CHANGELOG.md

@@ -5,6 +5,76 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-10-13
+
+### Added
+
+- **Remote settings.** The gem follows the project's settings in errorgap
+  (Project settings › What SDKs send): when errors, performance data or logs
+  are switched off there, running apps stop sending them within ten minutes,
+  with no deploy. Read on a background thread from
+  `GET /api/projects/:slug/config`; if errorgap cannot be reached everything
+  stays on. `config.remote_settings = false` (or
+  `ERRORGAP_REMOTE_SETTINGS=false`) turns this off.
+- **Resque.** Failed jobs are reported with their class, queue and arguments,
+  alongside Resque's own failure backend.
+- **Delayed Job.** Jobs are timed as `job` transactions and their errors
+  reported with the job class, queue, id and attempt count.
+- **Rake.** An error that ends a task is reported with the task's name and
+  flushed before Rake exits.
+
+In Rails all three are installed for you. Elsewhere:
+`Errorgap::Integrations::Resque.install`, `…::DelayedJob.install`,
+`…::Rake.install`.
+
+## [0.9.0] - 2026-10-13
+
+### Added
+
+- **Background jobs.** In Rails, ActiveJob jobs (any adapter) and Sidekiq
+  jobs are timed as `job` transactions and their errors are reported with the
+  job class, queue, id and arguments, then re-raised so retries work as
+  before. Outside Rails: `Errorgap::Integrations::ActiveJob.install` /
+  `Errorgap::Integrations::Sidekiq.install`.
+- **`config.before_notify`.** A block that sees each notice before it is sent
+  and can change it or return `false` to drop it.
+- **Outbound HTTP spans.** `Net::HTTP` requests made during a transaction are
+  recorded as `http` spans (`GET api.stripe.com`).
+- **Signed-in user.** Errors raised in a request carry the Warden / Devise
+  user as `session.user_id` and `session.user_email`
+  (`config.capture_user = false` to turn off). `Errorgap.set_user(id:,
+  email:)` names the user anywhere else.
+- **Release detection.** With `config.release` unset the release is read from
+  the platform's commit variable (`SOURCE_VERSION`, `HEROKU_SLUG_COMMIT`,
+  `RENDER_GIT_COMMIT`, `KAMAL_VERSION`, …), a Capistrano `REVISION` file or
+  the git checkout.
+- **Deploys.** `Errorgap.track_release` and `errorgap deploy` record a release
+  with errorgap; `config.track_release = true` records it when the first
+  error of a process is reported.
+- `config.timeout` (5 seconds) and `config.queue_size` (100).
+
+### Changed
+
+- **Delivery.** Async sends go through one bounded queue and one worker
+  thread instead of a thread per notice, transaction and log line. A full
+  queue drops its oldest entry. Requests time out after `config.timeout`
+  (they previously waited up to 60 seconds). Sends that fail on the network
+  or with a 5xx are retried up to three times; a 429 or 503 pauses sending
+  for the server's `Retry-After`. Queued payloads are flushed at exit, and
+  the worker restarts in forked processes (Puma workers, Sidekiq).
+- The Rack middleware queues an uncaught error instead of sending it inside
+  the failing request.
+
+### Fixed
+
+- **Nested sensitive params were sent unmasked.** `filter_keys` was only
+  applied to top-level keys, so `user[password]` went out in the clear. Keys
+  are now masked at any depth, in arrays, in the Rack session and in the
+  query string. `filter_keys` also accepts regexps.
+- A param holding invalid UTF-8, a reference cycle or an object that cannot
+  be serialized no longer loses the notice; long strings and large
+  collections are truncated.
+
 ## [0.8.0] - 2026-10-06
 
 ### Added

data/README.md

@@ -34,10 +34,65 @@ Errorgap.configure do |config|
 
   # The deployed version or commit (defaults to ERRORGAP_RELEASE). Errors carry
   # it, so errorgap ties each one to the deploy that shipped it.
+  # Unset, it is detected: the platform's commit variable, a Capistrano
+  # REVISION file, then the git checkout.
   config.release = ENV["GIT_SHA"]
+
+  # Change a notice before it is sent, or return false to drop it.
+  config.before_notify do |notice|
+    false if notice[:errors].first[:type] == "ActionController::RoutingError"
+  end
 end
 ```
 
+`filter_keys` (substrings or regexps, case-insensitive) are masked at any
+depth in params, the session and the query string. `config.timeout` (5 s) and
+`config.queue_size` (100) bound delivery: notices are queued and sent by one
+background thread, retried after a network failure or 5xx, and paused when the
+server answers 429.
+
+## Background jobs
+
+In Rails, ActiveJob (any adapter) and Sidekiq jobs need no setup: each job is
+timed as a `job` transaction when APM is on, and an error it raises is reported
+with the job class, queue, id and arguments, then re-raised. Outside Rails:
+
+```ruby
+Errorgap::Integrations::ActiveJob.install
+Errorgap::Integrations::Sidekiq.install
+```
+
+Resque, Delayed Job and Rake tasks are covered the same way (in Rails with no
+setup; elsewhere `Errorgap::Integrations::Resque.install`,
+`Errorgap::Integrations::DelayedJob.install`,
+`Errorgap::Integrations::Rake.install`).
+
+## Remote settings
+
+Errors, performance data and logs can each be switched off for a project in
+errorgap (Project settings › What SDKs send). Running apps follow within ten
+minutes, with no deploy. If errorgap cannot be reached, everything stays on.
+`config.remote_settings = false` ignores the project's switches.
+
+## Users
+
+Errors raised in a request carry the signed-in Warden / Devise user's id and
+email (`config.capture_user = false` to turn off). Anywhere else:
+
+```ruby
+Errorgap.set_user(id: account.id, email: account.email)
+```
+
+## Deploys
+
+```sh
+bundle exec errorgap deploy --sha "$GIT_SHA" --branch main
+```
+
+or `Errorgap.track_release(sha:, branch:)` from a deploy script, or
+`config.track_release = true` to record the release when a process reports its
+first error.
+
 When the errorgap browser SDK is on the page, its API calls send an
 `x-errorgap-trace` header; the Rack middleware records it on the request's
 transaction, so the browser's Performance view links each call to the server
@@ -123,7 +178,7 @@ app or background job — use the block API:
 ```ruby
 Errorgap.track_transaction(method: "GET", path: "/orders/{id}", path_raw: "/orders/7", status_code: 200) do |spans|
   spans.database("SELECT * FROM orders WHERE id = 7", 4.2, fn_name: "Repo.load")
-  spans.external(30.0, fn_name: "Gateway.fetch")
+  spans.external(30.0, fn_name: "Gateway.fetch")   # Net::HTTP calls are recorded for you
 end
 
 Errorgap.track_job("ReceiptJob", queue: "mailers") do |spans|

data/exe/errorgap

@@ -9,7 +9,23 @@ case command
 when "test"
   Errorgap.notify(RuntimeError.new("Errorgap test exception"), sync: true)
   puts "Sent test exception to Errorgap."
+when "deploy"
+  # errorgap deploy [--version V] [--sha SHA] [--branch B] [--environment E]
+  options = {}
+  ARGV.each_slice(2) do |flag, value|
+    key = flag.to_s.sub(/\A--/, "").to_sym
+    abort "Unknown option #{flag}" unless %i[version sha branch environment].include?(key)
+    abort "Missing value for #{flag}" if value.nil?
+    options[key] = value
+  end
+  result = Errorgap.track_release(**options)
+  if result&.success?
+    puts "Recorded release with Errorgap."
+  else
+    warn "Release not recorded#{result ? " (#{result.error || result.status})" : ": no version or sha"}"
+    exit 1
+  end
 else
-  warn "Usage: errorgap test"
+  warn "Usage: errorgap test | errorgap deploy [--version V] [--sha SHA] [--branch B] [--environment E]"
   exit 1
 end

data/lib/errorgap/configuration.rb

@@ -17,10 +17,18 @@ module Errorgap
                   :logs_enabled,
                   :minimum_log_level,
                   :max_breadcrumbs,
-                  :release,
+                  :timeout,
+                  :queue_size,
+                  :capture_user,
+                  :track_release,
+                  :release_sha,
+                  :release_branch,
+                  :remote_settings,
                   :auth_events,
                   :auth_user,
                   :app_name
+    attr_writer :release
+    attr_reader :before_notify_hooks
 
     def initialize
       @endpoint = ENV.fetch("ERRORGAP_ENDPOINT", "http://127.0.0.1:3030")
@@ -37,9 +45,28 @@ module Errorgap
       @logs_enabled = true
       @minimum_log_level = "info"
       @max_breadcrumbs = 25
+      # Seconds allowed for each request to errorgap.
+      @timeout = 5
+      # Payloads held for the background sender; the oldest is dropped when
+      # the queue is full.
+      @queue_size = 100
       # The deployed version or commit: errors are attributed to the deploy
-      # that shipped them.
+      # that shipped them. Unset, it is read from the platform's commit
+      # variable, a REVISION file or the git checkout.
       @release = ENV["ERRORGAP_RELEASE"].to_s.strip.empty? ? nil : ENV["ERRORGAP_RELEASE"].strip
+      @release_sha = nil
+      @release_branch = nil
+      # Record the release with errorgap (Deploys) when the first error of a
+      # process is reported.
+      @track_release = false
+      # Attach the signed-in user's id and email to errors raised in a
+      # request (Warden / Devise).
+      @capture_user = true
+      @before_notify_hooks = []
+      # Follow the project's settings in errorgap (Project settings › What
+      # SDKs send): stop sending errors, performance data or logs when they
+      # are switched off there.
+      @remote_settings = ENV["ERRORGAP_REMOTE_SETTINGS"].to_s.strip.downcase != "false"
       # Sign-ins to this app (Security › Logins). Off until you opt in: they
       # carry user names and IPs.
       @auth_events = false
@@ -50,6 +77,26 @@ module Errorgap
       @app_name = nil
     end
 
+    def release
+      return @release if @release
+
+      unless defined?(@detected_release) && @detected_root == root_directory
+        @detected_root = root_directory
+        @detected_release = ReleaseDetector.detect(root_directory)
+      end
+      @detected_release
+    end
+
+    # Runs before a notice is sent, with the notice as a Hash that can be
+    # changed in place. Return `false` to drop it.
+    #
+    #   config.before_notify { |notice| false if notice[:errors][0][:type] == "Timeout::Error" }
+    def before_notify(callable = nil, &block)
+      hook = callable || block
+      @before_notify_hooks << hook if hook.respond_to?(:call)
+      hook
+    end
+
     def validate!
       raise ArgumentError, "Errorgap project_slug is required" if blank?(project_slug)
 

data/lib/errorgap/delivery.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Errorgap
+  # Sends every payload (notices, transactions, logs, sign-ins, releases) to
+  # the ingestion API. Async sends go through one bounded queue drained by a
+  # single worker thread, so a burst of errors cannot spawn a thread each or
+  # hold the host's memory. A send that fails on the network or with a 5xx is
+  # retried later; a 429 or 503 pauses all sending for the server's
+  # `Retry-After`.
+  class Delivery
+    Result = Struct.new(:status, :body, :error, keyword_init: true) do
+      def success?
+        error.nil? && status.to_i.between?(200, 299)
+      end
+    end
+
+    class RateLimited < StandardError; end
+
+    MAX_ATTEMPTS = 3
+    RETRY_DELAY = 30
+    DEFAULT_RETRY_AFTER = 60
+    MAX_RETRY_AFTER = 300
+    BACKLOG_SIZE = 100
+    FLUSH_TIMEOUT = 5
+
+    Item = Struct.new(:resource, :payload, :attempt, :due_at)
+
+    def initialize(configuration)
+      @configuration = configuration
+      @mutex = Mutex.new
+      @work = ConditionVariable.new
+      @idle = ConditionVariable.new
+      @queue = []
+      @backlog = []
+      @in_flight = 0
+      @paused_until = nil
+      @worker = nil
+      @pid = nil
+    end
+
+    def configure(configuration)
+      @configuration = configuration
+    end
+
+    # Queue a payload and return at once. When the queue is full the oldest
+    # entry is dropped, so the newest errors survive a burst.
+    def enqueue(resource, payload)
+      @mutex.synchronize do
+        ensure_worker
+        if @queue.length >= queue_size
+          @queue.shift
+          log("queue full, dropped the oldest payload")
+        end
+        @queue << Item.new(resource, payload, 1, nil)
+        @work.signal
+      end
+      Result.new(status: 202, body: "queued")
+    end
+
+    # Send now, on the calling thread.
+    def post(resource, payload)
+      if paused?
+        return Result.new(error: RateLimited.new("rate limited by the server, not sent"))
+      end
+
+      uri = URI.join(base_url, "api/projects/#{@configuration.project_slug}/#{resource}")
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "errorgap-ruby/#{Errorgap::VERSION}"
+      request["X-Errorgap-Project-Key"] = @configuration.api_key if present?(@configuration.api_key)
+      request.body = JSON.generate(payload)
+
+      timeout = http_timeout
+      response = with_own_request do
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https",
+                                                open_timeout: timeout, read_timeout: timeout,
+                                                write_timeout: timeout) do |http|
+          http.request(request)
+        end
+      end
+      status = response.code.to_i
+      pause_for(response["Retry-After"]) if [429, 503].include?(status)
+      Result.new(status: status, body: response.body)
+    rescue StandardError => exception
+      log("#{resource} delivery error: #{exception.class}: #{exception.message}")
+      Result.new(error: exception)
+    end
+
+    # Wait for queued payloads to be sent. Payloads waiting for a retry are
+    # not waited for.
+    def flush(timeout = FLUSH_TIMEOUT)
+      deadline = monotonic + timeout
+      @mutex.synchronize do
+        until @queue.empty? && @in_flight.zero?
+          remaining = deadline - monotonic
+          break if remaining <= 0 || !@worker&.alive?
+
+          @idle.wait(@mutex, remaining)
+        end
+      end
+      nil
+    end
+
+    def paused?
+      until_time = @paused_until
+      !until_time.nil? && monotonic < until_time
+    end
+
+    # True while this thread is sending to errorgap, so instrumentation can
+    # leave the SDK's own requests out of the app's spans.
+    def self.sending?
+      Thread.current[:errorgap_sending] == true
+    end
+
+    private
+
+    def with_own_request
+      previous = Thread.current[:errorgap_sending]
+      Thread.current[:errorgap_sending] = true
+      yield
+    ensure
+      Thread.current[:errorgap_sending] = previous
+    end
+
+    # Called with the mutex held. A forked child (Puma workers, Sidekiq,
+    # Passenger) has the parent's queue but not its thread: start clean.
+    def ensure_worker
+      if @pid != Process.pid
+        @pid = Process.pid
+        @queue = []
+        @backlog = []
+        @in_flight = 0
+        @worker = nil
+        install_exit_flush
+      end
+      return if @worker&.alive?
+
+      @worker = Thread.new { run }
+      @worker.name = "errorgap-delivery" if @worker.respond_to?(:name=)
+      @worker.report_on_exception = false if @worker.respond_to?(:report_on_exception=)
+    end
+
+    def install_exit_flush
+      pid = Process.pid
+      at_exit { flush if Process.pid == pid }
+    end
+
+    def run
+      loop do
+        item = next_item
+        result = post(item.resource, item.payload)
+        @mutex.synchronize do
+          retry_later(item) if retryable?(result)
+          @in_flight -= 1
+          @idle.broadcast if @queue.empty? && @in_flight.zero?
+        end
+      end
+    rescue StandardError => exception
+      log("delivery worker stopped: #{exception.class}: #{exception.message}")
+    end
+
+    def next_item
+      @mutex.synchronize do
+        loop do
+          promote_due
+          unless @queue.empty?
+            @in_flight += 1
+            return @queue.shift
+          end
+          @idle.broadcast
+          @work.wait(@mutex, next_due_in)
+        end
+      end
+    end
+
+    def promote_due
+      return if @backlog.empty?
+
+      now = monotonic
+      due, @backlog = @backlog.partition { |item| item.due_at <= now }
+      @queue.concat(due)
+    end
+
+    def next_due_in
+      return nil if @backlog.empty?
+
+      [@backlog.map(&:due_at).min - monotonic, 0.05].max
+    end
+
+    # Network failures and 5xx responses are worth another try. A 4xx is not:
+    # the server understood and refused, and after a 429 the payload is
+    # dropped so a limited project is not sent the same burst again.
+    def retryable?(result)
+      return false if result.error.is_a?(RateLimited)
+      return true if result.error
+
+      result.status.to_i >= 500
+    end
+
+    def retry_later(item)
+      return if item.attempt >= MAX_ATTEMPTS
+      return if @backlog.length >= BACKLOG_SIZE
+
+      @backlog << Item.new(item.resource, item.payload, item.attempt + 1,
+                           monotonic + (RETRY_DELAY * item.attempt))
+    end
+
+    def pause_for(header)
+      seconds = header.to_s.strip.match?(/\A\d+\z/) ? header.to_i : DEFAULT_RETRY_AFTER
+      seconds = [[seconds, 1].max, MAX_RETRY_AFTER].min
+      @paused_until = monotonic + seconds
+      log("rate limited, pausing delivery for #{seconds}s")
+    end
+
+    def base_url
+      endpoint = @configuration.endpoint.to_s
+      endpoint.end_with?("/") ? endpoint : "#{endpoint}/"
+    end
+
+    def http_timeout
+      value = @configuration.timeout.to_f
+      value.positive? ? value : 5
+    end
+
+    def queue_size
+      size = @configuration.queue_size.to_i
+      size.positive? ? size : 100
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def log(message)
+      @configuration.logger&.warn("[errorgap] #{message}")
+    rescue StandardError
+      nil
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.empty?
+    end
+  end
+end

data/lib/errorgap/integrations/active_job.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Errorgap
+  module Integrations
+    # ActiveJob, whatever the queue adapter: every job runs as a `job`
+    # transaction and an error it raises is reported with the job's class,
+    # queue, id and arguments, then re-raised so `retry_on` / `discard_on` and
+    # the adapter's own retries work as before. The Rails railtie installs it.
+    module ActiveJob
+      class << self
+        def install
+          return false unless defined?(::ActiveSupport) && ::ActiveSupport.respond_to?(:on_load)
+          return true if @installed
+
+          ::ActiveSupport.on_load(:active_job) do
+            around_perform { |job, block| Errorgap::Integrations::ActiveJob.perform(job, &block) }
+          end
+          @installed = true
+        end
+
+        def installed?
+          @installed == true
+        end
+
+        def perform(job, &block)
+          Errorgap.track_job(job.class.name.to_s, queue: job.queue_name.to_s) do
+            run(job, &block)
+          end
+        ensure
+          Errorgap.clear_user
+        end
+
+        private
+
+        def run(job)
+          yield
+        rescue Exception => exception # rubocop:disable Lint/RescueException
+          Errorgap.notify_once(
+            exception,
+            context: { component: "active_job", action: job.class.name.to_s },
+            environment: { queue: job.queue_name.to_s, job_id: job.job_id, executions: job.executions }.compact,
+            params: { "arguments" => arguments(job) }
+          )
+          raise
+        end
+
+        # Records and other GlobalID arguments are named, not serialized.
+        def arguments(job)
+          Array(job.arguments).map do |argument|
+            argument.respond_to?(:to_global_id) ? argument.to_global_id.to_s : argument
+          end
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/errorgap/integrations/delayed_job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Errorgap
+  module Integrations
+    # Delayed Job: every job runs as a `job` transaction and an error it
+    # raises is reported with the job's class, queue, id and attempt count,
+    # then re-raised so Delayed Job's retries work as before.
+    #
+    #   Errorgap::Integrations::DelayedJob.install   # after Delayed Job is loaded
+    module DelayedJob
+      ACTIVE_JOB_WRAPPER = "ActiveJob::QueueAdapters::DelayedJobAdapter::JobWrapper"
+
+      class << self
+        def install
+          return false unless defined?(::Delayed::Plugin) && defined?(::Delayed::Worker)
+          return true if @installed
+
+          ::Delayed::Worker.plugins << plugin
+          @installed = true
+        end
+
+        def plugin
+          @plugin ||= Class.new(::Delayed::Plugin) do
+            callbacks do |lifecycle|
+              lifecycle.around(:invoke_job) do |job, *args, &block|
+                Errorgap::Integrations::DelayedJob.invoke(job) { block.call(job, *args) }
+              end
+            end
+          end
+        end
+
+        def invoke(job, &block)
+          job_class = job_name(job)
+          # An ActiveJob run by Delayed Job is covered by the ActiveJob
+          # integration, which knows the real job class and its arguments.
+          return yield if job_class == ACTIVE_JOB_WRAPPER && ActiveJob.installed?
+
+          Errorgap.track_job(job_class, queue: (job.respond_to?(:queue) && job.queue) || "default") do
+            run(job, job_class, &block)
+          end
+        ensure
+          Errorgap.clear_user
+        end
+
+        private
+
+        def run(job, job_class)
+          yield
+        rescue Exception => exception # rubocop:disable Lint/RescueException
+          Errorgap.notify_once(
+            exception,
+            context: { component: "delayed_job", action: job_class },
+            environment: {
+              queue: job.respond_to?(:queue) ? job.queue : nil,
+              job_id: job.respond_to?(:id) ? job.id : nil,
+              attempts: job.respond_to?(:attempts) ? job.attempts : nil
+            }.compact
+          )
+          raise
+        end
+
+        # `Mailer.delay.welcome(user)` is a PerformableMethod: name it by
+        # what it calls rather than by the wrapper.
+        def job_name(job)
+          payload = job.payload_object
+          return payload.display_name.to_s if payload.respond_to?(:display_name)
+
+          payload.class.name.to_s
+        rescue StandardError
+          "Delayed::Job"
+        end
+      end
+    end
+  end
+end