errsight 0.2.2

data/lib/errsight/integrations/rails_error_reporter.rb

@@ -0,0 +1,107 @@
+module Errsight
+  module Integrations
+    # Subscriber for Rails.error (ActiveSupport::ErrorReporter), the
+    # canonical error-reporting hook in Rails 7+. Catches errors from
+    # places our existing middleware + controller-notifications subscriber
+    # don't reach:
+    #   - Active Job after retries are exhausted (Rails 7.1+ wraps job
+    #     errors via Rails.error.report on death)
+    #   - Active Storage analyzer/identifier errors
+    #   - Action Mailer delivery failures
+    #   - Action Cable channel errors
+    #   - Anywhere app code calls Rails.error.handle / .record / .report
+    #
+    # The thread-local seen-set used by CaptureMiddleware and the
+    # process_action.action_controller subscriber dedups the overlap on
+    # controller errors — Rails internally calls Rails.error.report on
+    # controller exceptions too on Rails 7+, so without this dedup a
+    # single 500 would create two issues.
+    class RailsErrorReporter
+      MAX_CONTEXT_KEYS        = 20
+      MAX_CONTEXT_VALUE_BYTES = 1_024
+
+      class << self
+        # Idempotent — Rails initializers can fire twice during certain
+        # boot paths (engines, some test harnesses) and we don't want each
+        # report to fan out to N copies of ourselves.
+        def install!
+          return if @installed
+          @installed = true
+          ::Rails.error.subscribe(new)
+        end
+
+        # Test-only: lets a test reset state and reinstall against a fresh
+        # ActiveSupport::ErrorReporter mock.
+        def reset!
+          @installed = false
+        end
+      end
+
+      # ActiveSupport::ErrorReporter signature has been stable across
+      # Rails 7.0–8.x. Trailing **kwargs swallows any additions in future
+      # versions so a Rails minor bump can't crash our subscriber.
+      def report(error, handled:, severity:, context: {}, source: nil, **)
+        return unless error.is_a?(Exception)
+        return if duplicate?(error)
+
+        Errsight.capture_exception(
+          error,
+          metadata: build_metadata(context, source, handled, severity),
+          tags:     build_tags(severity, source, handled)
+        )
+      rescue StandardError
+        # Never let our reporter take down the host's request, job, or
+        # mail delivery — a missed event is far less bad than a crashed
+        # response.
+      end
+
+      private
+
+      def duplicate?(exception)
+        seen = Thread.current[:errsight_captured_exceptions] ||= []
+        return true if seen.include?(exception.object_id)
+        seen << exception.object_id
+        false
+      end
+
+      def build_tags(severity, source, handled)
+        tags = {
+          "rails.error.severity" => severity.to_s,
+          "rails.error.handled"  => handled.to_s
+        }
+        tags["rails.error.source"] = source.to_s if source
+        tags
+      end
+
+      def build_metadata(context, source, handled, severity)
+        meta = {
+          rails_error: {
+            severity: severity.to_s,
+            handled:  handled,
+            source:   source&.to_s
+          }.compact
+        }
+        meta[:rails_error_context] = sanitize_context(context) if context.is_a?(Hash) && !context.empty?
+        meta
+      end
+
+      def sanitize_context(context)
+        out = {}
+        context.first(MAX_CONTEXT_KEYS).each do |k, v|
+          out[k.to_s] = truncate(v)
+        end
+        out
+      end
+
+      def truncate(value)
+        case value
+        when Hash, Array
+          value
+        else
+          str = value.to_s
+          str.bytesize > MAX_CONTEXT_VALUE_BYTES ? "[truncated #{value.class.name}]" : value
+        end
+      end
+    end
+  end
+end

data/lib/errsight/logger.rb

@@ -0,0 +1,85 @@
+require "logger"
+
+module Errsight
+  # A Logger-compatible class that forwards log entries to Errsight
+  # and optionally delegates to a backing logger.
+  class Logger < ::Logger
+    LEVEL_MAP = {
+      DEBUG   => :debug,
+      INFO    => :info,
+      WARN    => :warning,
+      ERROR   => :error,
+      FATAL   => :fatal,
+      UNKNOWN => :info
+    }.freeze
+
+    LEVEL_ORDER = %i[debug info warning error fatal].freeze
+
+    # ActionDispatch::DebugExceptions logs a fully-formatted exception report
+    # via Rails.logger.fatal — class+msg, then a backtrace. Forwarding that
+    # blob as a single Event.message produces a giant title with no real
+    # backtrace column. The Rack CaptureMiddleware handles the underlying
+    # exception with structured fields, so we suppress these dumps here.
+    EXCEPTION_FRAME_RE = /:\d+:in ['`]/.freeze
+    EXCEPTION_FRAME_THRESHOLD = 3
+
+    def initialize(backing_logger = nil)
+      super(IO::NULL)
+      @backing_logger = backing_logger
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      # Duck-typed forward — when this Logger is used as a broadcast
+      # target by ActiveSupport::BroadcastLogger or the legacy
+      # Logger.broadcast extension, the constructor can be called with
+      # something that isn't a Logger (an IO, a Tagged-Logger wrapper,
+      # etc). Sending #add to an IO raises NoMethodError. Rather than
+      # try to enforce the type at construction (every host has its
+      # own quirks), we just skip forwarding if the target can't
+      # accept #add.
+      @backing_logger.add(severity, message, progname, &block) if @backing_logger.respond_to?(:add)
+
+      # Cheap early-return: skip all allocations when Errsight is disabled
+      # or this severity is below the configured threshold. Rails.logger can
+      # fire thousands of times per request at :debug; this path matters.
+      config = Errsight.configuration
+      return true unless config.enabled?
+
+      level = LEVEL_MAP[severity] || :info
+      return true if LEVEL_ORDER.index(level).to_i < LEVEL_ORDER.index(config.min_level).to_i
+
+      message = block_given? ? yield : message
+      message ||= progname
+      return true if message.nil?
+
+      message_str = message.to_s
+      return true if exception_dump?(message_str)
+
+      metadata = {}
+      if (request_id = Thread.current[:errsight_request_id])
+        metadata[:request_id] = request_id
+      end
+
+      # The Logger sits on Rails.logger's hot path. If Errsight.log raises
+      # for any reason — config drift, queue full mid-shutdown, a
+      # before_send callback bug — the customer's request handler must
+      # not crash because they happened to log a line. Swallow and move
+      # on; the original log line still went to @backing_logger above.
+      begin
+        Errsight.log(level: level, message: message_str, metadata: metadata)
+      rescue StandardError
+        # best-effort
+      end
+      true
+    end
+
+    alias log add
+
+    private
+
+    def exception_dump?(message)
+      return false unless message.include?("\n")
+      message.scan(EXCEPTION_FRAME_RE).size >= EXCEPTION_FRAME_THRESHOLD
+    end
+  end
+end

data/lib/errsight/middleware.rb

@@ -0,0 +1,16 @@
+module Errsight
+  # Rack middleware that stores the request_id on the current thread
+  # so the Errsight::Logger can tag every log line with it.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Thread.current[:errsight_request_id] = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+      @app.call(env)
+    ensure
+      Thread.current[:errsight_request_id] = nil
+    end
+  end
+end

data/lib/errsight/railtie.rb

@@ -0,0 +1,198 @@
+require "rails"
+require "socket"
+
+module Errsight
+  class Railtie < Rails::Railtie
+    # Captured once at boot — Socket.gethostname does a DNS lookup on some
+    # platforms and is called on the hot exception-capture path.
+    HOSTNAME = begin
+      Socket.gethostname
+    rescue StandardError
+      nil
+    end.freeze
+    initializer "errsight.configure_rails_initialization" do |app|
+      # Ensure the client shuts down cleanly on exit
+      at_exit { Errsight.client.shutdown! rescue nil }
+    end
+
+    # Insert middleware to capture request_id for log grouping
+    initializer "errsight.insert_middleware" do |app|
+      app.middleware.insert_after ActionDispatch::RequestId, Errsight::Middleware
+
+      # Sit just inside DebugExceptions so we see exceptions raised by any
+      # inner middleware (e.g. ActiveRecord::Migration::CheckPending) before
+      # they get converted into an HTTP error response. This is the only path
+      # that catches non-controller errors with a real backtrace.
+      app.middleware.insert_after ActionDispatch::DebugExceptions, Errsight::CaptureMiddleware
+    end
+
+    # Broadcast every Rails.logger call to Errsight so all log lines are captured,
+    # not just exceptions. Uses BroadcastLogger (Rails 7.1+) or the older broadcast
+    # extension. Respects config.min_level — set it to :debug/:info in the initializer
+    # to control how much noise is forwarded.
+    #
+    # MUST run `after: :load_config_initializers` so the user's
+    # `config/initializers/errsight.rb` has already executed by the time
+    # we read `attach_to_rails_logger`. Pre-0.2.0 the default was `true`
+    # so broadcasting wired up at boot regardless of user config; when
+    # the default flipped to `false` in 0.2.0 this initializer started
+    # running before the user could opt back in, and the broadcast
+    # never attached. Same hook the other 0.2.0 integrations use.
+    initializer "errsight.attach_to_rails_logger", after: :load_config_initializers do
+      next unless Errsight.configuration.attach_to_rails_logger
+
+      sink = Errsight::Logger.new  # no backing logger — just forwards to the API
+
+      if Rails.logger.respond_to?(:broadcast_to)
+        # Rails 7.1+ ActiveSupport::BroadcastLogger
+        Rails.logger.broadcast_to(sink)
+      else
+        Rails.logger.extend(ActiveSupport::Logger.broadcast(sink))
+      end
+    rescue StandardError => e
+      Rails.logger.warn("[Errsight] Could not attach to Rails.logger: #{e.message}")
+    end
+
+    # Configure Sidekiq integration after the host's own initializers run,
+    # so any custom middleware they add is already in the chain when we
+    # decide where to insert ours. Bundler.require has already happened by
+    # this point — defined?(::Sidekiq) is the truthful answer.
+    initializer "errsight.configure_sidekiq", after: :load_config_initializers do
+      if defined?(::Sidekiq)
+        require "errsight/sidekiq"
+        Errsight::Sidekiq.configure_integration!
+      end
+    end
+
+    # Subscribe to sql.active_record so every query becomes a breadcrumb
+    # on the current scope. When an exception fires, the event ships with
+    # the queries that ran in this request/job — which is the Rails
+    # debugging information customers actually need. Run after host
+    # initializers so the customer's filter_parameters / config tweaks are
+    # available to us.
+    initializer "errsight.subscribe_active_record_breadcrumbs", after: :load_config_initializers do
+      if defined?(::ActiveRecord) && Errsight.configuration.breadcrumbs_active_record
+        require "errsight/integrations/active_record"
+        Errsight::Integrations::ActiveRecord.subscribe!
+      end
+    end
+
+    # Hook into Rails.error (ActiveSupport::ErrorReporter) on Rails 7+ so
+    # we catch errors from Active Job, Active Storage, Action Mailer,
+    # Action Cable, and any explicit Rails.error.handle/record/report
+    # calls — error sources our middleware + controller-notifications
+    # subscriber don't reach.
+    initializer "errsight.subscribe_rails_error_reporter", after: :load_config_initializers do
+      if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
+        require "errsight/integrations/rails_error_reporter"
+        Errsight::Integrations::RailsErrorReporter.install!
+      end
+    end
+
+    # Include the ActiveJob integration into ::ActiveJob::Base so every
+    # job class picks up scope propagation (enqueue → run) and structured
+    # error capture. Adapter-agnostic: works for Solid Queue, GoodJob,
+    # Delayed::Job, and Sidekiq+ActiveJob. Sidekiq raw jobs (without
+    # ActiveJob) keep going through the dedicated Sidekiq middleware.
+    initializer "errsight.include_active_job_integration", after: :load_config_initializers do
+      if defined?(::ActiveJob::Base)
+        require "errsight/integrations/active_job"
+        ::ActiveJob::Base.include(Errsight::Integrations::ActiveJob)
+      end
+    end
+
+    # Hook into the Rails exception notification pipeline
+    initializer "errsight.subscribe_to_exceptions" do
+      ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+        # Fast-path: skip Event allocation when the action didn't raise.
+        # args = [name, started, finished, unique_id, payload]
+        payload = args[4]
+        next unless payload.is_a?(Hash) && payload[:exception_object]
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        exception = event.payload[:exception_object]
+        request = event.payload[:request]
+
+        metadata = {
+          path:       event.payload[:path],
+          full_path:  request&.url,
+          format:     event.payload[:format],
+          duration:   event.duration.round(2)
+        }
+
+        # Attach POST/PATCH/PUT/DELETE params (skip Rails internals)
+        if request && %w[POST PATCH PUT DELETE].include?(request.request_method)
+          begin
+            filtered = request.filtered_parameters
+                              .except("controller", "action", "format", "authenticity_token")
+            metadata[:params] = filtered unless filtered.empty?
+          rescue StandardError
+            # filtered_parameters can raise on malformed bodies — ignore
+          end
+        end
+
+        user_ctx = Errsight::Railtie.build_user_context(request)
+        tags     = Errsight::Railtie.build_tags(event.payload, request)
+
+        # Mark this exception so CaptureMiddleware (which sits below us in the
+        # Rack stack and will see the same object as it bubbles up) skips the
+        # duplicate capture. The middleware clears this thread-local per-req.
+        (Thread.current[:errsight_captured_exceptions] ||= []) << exception.object_id
+
+        Errsight.capture_exception(exception, metadata: metadata, user: user_ctx, tags: tags)
+      end
+    end
+
+    # Extracts a top-level user context the API stores in user_context /
+    # user_identifier. Falls through to just the request IP when no user is
+    # signed in so anonymous errors still carry some identity.
+    def self.build_user_context(request)
+      ctx = {}
+
+      # Warden-backed auth (Devise, ActiveAdmin, etc.). Walks every authenticated
+      # scope in the session rather than hard-coding :user.
+      begin
+        warden = request&.env&.fetch("warden", nil)
+        if warden
+          session = request.env["rack.session"] || {}
+          scopes  = session.keys
+                           .grep(/\Awarden\.user\.(.+)\.key\z/) { $1.to_sym }
+                           .then { |s| s.any? ? s : [ :user ] }
+
+          user = scopes.lazy.filter_map { |scope| warden.user(scope) rescue nil }.first
+
+          if user
+            ctx[:id]       = user.id.to_s       if user.respond_to?(:id)       && !user.id.to_s.strip.empty?
+            ctx[:email]    = user.email.to_s    if user.respond_to?(:email)    && !user.email.to_s.strip.empty?
+            ctx[:username] = user.username.to_s if user.respond_to?(:username) && !user.username.to_s.strip.empty?
+          end
+        end
+      rescue StandardError
+        # never let user-lookup failures suppress the event
+      end
+
+      if request.respond_to?(:remote_ip)
+        ip = request.remote_ip.to_s
+        ctx[:ip_address] = ip unless ip.empty?
+      end
+
+      ctx.empty? ? nil : ctx
+    end
+
+    # Top-level tags the UI uses for filtering. Rails env info is free at
+    # capture time and makes "errors on this controller/action/host" filters
+    # work without any app-side setup.
+    def self.build_tags(payload, request)
+      tags = {
+        "controller"     => payload[:controller],
+        "action"         => payload[:action],
+        "request_method" => request&.request_method,
+        "status"         => payload[:status]&.to_s,
+        "ruby_version"   => RUBY_VERSION,
+        "rails_version"  => Rails.version
+      }
+      tags["hostname"] = HOSTNAME if HOSTNAME
+      tags.compact.reject { |_, v| v.to_s.strip.empty? }
+    end
+  end
+end

data/lib/errsight/scope.rb

@@ -0,0 +1,166 @@
+module Errsight
+  # Holds the user, tags, and breadcrumbs that should be attached to events
+  # captured while this scope is on top of the hub stack.
+  #
+  # A scope is owned by a single thread of execution (a Rails request, a
+  # Sidekiq job, or an ad-hoc Errsight.with_scope block). Pushing a new scope
+  # forks a deep copy of the parent so child mutations don't bleed back up
+  # the stack.
+  #
+  # Breadcrumbs are split into two ring buffers — manual app crumbs and
+  # auto-collected DB crumbs — so a high-query request can't evict the
+  # user's manual context. The public `breadcrumbs` accessor returns a
+  # merged, timestamp-sorted view; consumers see one stream.
+  class Scope
+    MAX_USER_BREADCRUMBS = 50
+    MAX_DB_BREADCRUMBS   = 30
+    # Back-compat alias for callers that referenced the old single-cap name.
+    BREADCRUMB_LIMIT = MAX_USER_BREADCRUMBS
+
+    attr_reader :user, :tags
+
+    def initialize
+      @user             = nil
+      @tags             = {}
+      @user_breadcrumbs = []
+      @db_breadcrumbs   = []
+    end
+
+    # Merged, timestamp-sorted view across both rings. ISO-8601 strings sort
+    # lexicographically the same as chronologically, so a string sort is
+    # correct without parsing back into Time.
+    def breadcrumbs
+      return @user_breadcrumbs if @db_breadcrumbs.empty?
+      return @db_breadcrumbs   if @user_breadcrumbs.empty?
+      (@user_breadcrumbs + @db_breadcrumbs).sort_by { |b| b[:timestamp] }
+    end
+
+    def set_user(user)
+      @user = user.is_a?(Hash) ? user : nil
+    end
+
+    def clear_user
+      @user = nil
+    end
+
+    def set_tag(key, value)
+      return if key.nil?
+      @tags[key.to_s] = value.to_s
+    end
+
+    def set_tags(tags)
+      return unless tags.is_a?(Hash)
+      tags.each { |k, v| set_tag(k, v) }
+    end
+
+    def clear_tags
+      @tags = {}
+    end
+
+    def add_breadcrumb(category:, message:, level: :info, data: nil)
+      @user_breadcrumbs << build_crumb(category, message, level, data)
+      @user_breadcrumbs.shift while @user_breadcrumbs.size > MAX_USER_BREADCRUMBS
+    end
+
+    # Internal API for auto-instrumentation (sql.active_record subscriber
+    # today; future http subscribers will use the same ring or get their
+    # own). Separate cap from manual crumbs so a runaway-query request
+    # can't push out the app code's own context.
+    def add_db_breadcrumb(message:, data: nil)
+      @db_breadcrumbs << build_crumb("db", message, :info, data)
+      @db_breadcrumbs.shift while @db_breadcrumbs.size > MAX_DB_BREADCRUMBS
+    end
+
+    def clear_breadcrumbs
+      @user_breadcrumbs = []
+      @db_breadcrumbs   = []
+    end
+
+    # Overlay another scope's state onto this one. Used by Sidekiq server
+    # middleware to layer payload scope (user/tags shipped by the enqueuer)
+    # on top of process-wide root state (e.g. Errsight.set_tag("region",…)
+    # called once at boot). User from `other` wins; tags are merged with
+    # `other` taking precedence on key collisions; breadcrumbs are appended
+    # in order and clipped to the limit.
+    def merge!(other)
+      return self unless other.is_a?(Scope)
+      @user = other.user if other.user
+      @tags.merge!(other.tags) unless other.tags.empty?
+      other_user = other.instance_variable_get(:@user_breadcrumbs)
+      other_db   = other.instance_variable_get(:@db_breadcrumbs)
+      unless other_user.empty?
+        @user_breadcrumbs.concat(other_user.map(&:dup))
+        @user_breadcrumbs.shift while @user_breadcrumbs.size > MAX_USER_BREADCRUMBS
+      end
+      unless other_db.empty?
+        @db_breadcrumbs.concat(other_db.map(&:dup))
+        @db_breadcrumbs.shift while @db_breadcrumbs.size > MAX_DB_BREADCRUMBS
+      end
+      self
+    end
+
+    # Deep-ish copy used when pushing a child scope. Hashes/arrays are dup'd
+    # so child mutations don't bleed back up the stack.
+    def dup
+      copy = Scope.new
+      copy.send(:replace_state,
+                @user&.dup,
+                @tags.dup,
+                @user_breadcrumbs.map(&:dup),
+                @db_breadcrumbs.map(&:dup))
+      copy
+    end
+
+    # Serialize for cross-process propagation (Sidekiq client middleware will
+    # stash this in the job payload so the server middleware can rehydrate
+    # it before the job runs).
+    #
+    # Only manual user breadcrumbs travel across process boundaries. The
+    # receiving worker collects its own DB breadcrumbs from its own queries
+    # — propagating the parent's would mix DB events from two unrelated
+    # connection states and confuse debugging.
+    def to_h
+      hash = {}
+      hash["user"]        = @user             unless @user.nil?
+      hash["tags"]        = @tags             unless @tags.empty?
+      hash["breadcrumbs"] = @user_breadcrumbs unless @user_breadcrumbs.empty?
+      hash
+    end
+
+    def self.from_h(hash)
+      scope = new
+      return scope unless hash.is_a?(Hash)
+      tags = hash["tags"].is_a?(Hash) ? hash["tags"].transform_keys(&:to_s).transform_values(&:to_s) : {}
+      # dup each crumb so the rehydrated scope doesn't alias entries inside
+      # the caller's job payload — add_breadcrumb mutates @user_breadcrumbs
+      # in place and we don't want that mutation to flow back into job args.
+      crumbs = hash["breadcrumbs"].is_a?(Array) ? hash["breadcrumbs"].map { |c| c.is_a?(Hash) ? c.dup : c } : []
+      # send: replace_state is protected so external callers can't reach in,
+      # but a class-method factory needs to bypass that to build a new scope.
+      # DB breadcrumbs are intentionally not propagated; they start empty.
+      scope.send(:replace_state, hash["user"], tags, crumbs, [])
+      scope
+    end
+
+    protected
+
+    def replace_state(user, tags, user_breadcrumbs, db_breadcrumbs)
+      @user             = user
+      @tags             = tags
+      @user_breadcrumbs = user_breadcrumbs
+      @db_breadcrumbs   = db_breadcrumbs
+    end
+
+    private
+
+    def build_crumb(category, message, level, data)
+      {
+        timestamp: Time.now.iso8601(3),
+        category: category.to_s,
+        level: level.to_s,
+        message: message.to_s,
+        data: data.is_a?(Hash) ? data : nil
+      }.compact
+    end
+  end
+end