errsight 0.2.2

data/lib/errsight/sidekiq.rb

@@ -0,0 +1,248 @@
+module Errsight
+  # Sidekiq integration. Three pieces:
+  #
+  #   1. ClientMiddleware — runs on enqueue, snapshots the current scope
+  #      (user/tags/breadcrumbs) into the job payload so the worker side can
+  #      restore it when the job runs.
+  #   2. ServerMiddleware — runs around `perform`, rehydrates the snapshot,
+  #      reports any exception with structured Sidekiq context, and re-raises
+  #      so Sidekiq's retry/death machinery still fires.
+  #   3. error_handlers entry — Sidekiq's safety net for exceptions raised
+  #      *outside* the middleware chain (fetch errors, middleware itself
+  #      raising). Dedup-aware so middleware-captured exceptions aren't
+  #      reported twice.
+  #
+  # We do NOT enqueue Errsight's HTTP delivery as Sidekiq jobs. Delivery
+  # stays on the SDK's own background flush thread so error reporting still
+  # works when the customer's Sidekiq is broken (Redis down, workers stuck).
+  module Sidekiq
+    # Cap propagated breadcrumbs so we don't bloat job payloads in Redis. A
+    # job carrying 50 crumbs × 200 bytes × 1M jobs/day = 10 GB/day, which is
+    # not a cost we should silently impose on the customer's Redis bill.
+    MAX_PROPAGATED_BREADCRUMBS = 20
+
+    # Hard cap on per-arg serialized size. Jobs occasionally carry large
+    # payloads (file blobs, base64 images) and we'd rather drop them than
+    # blow past the API's 512KB ingestion limit.
+    MAX_ARG_BYTES = 4_096
+
+    class << self
+      # Idempotent. Safe to call multiple times: the @configured flag and
+      # chain.exists? guards prevent double-registration if the host requires
+      # us once via Bundler and once via the Railtie.
+      def configure_integration!
+        return unless defined?(::Sidekiq)
+        return if @configured
+        @configured = true
+
+        ::Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            # Prepend so we wrap *all* other server middleware — exceptions
+            # raised by other middleware are caught here too.
+            chain.prepend(ServerMiddleware) unless chain.exists?(ServerMiddleware)
+          end
+          config.client_middleware do |chain|
+            chain.add(ClientMiddleware) unless chain.exists?(ClientMiddleware)
+          end
+          register_error_handler(config)
+        end
+
+        ::Sidekiq.configure_client do |config|
+          config.client_middleware do |chain|
+            chain.add(ClientMiddleware) unless chain.exists?(ClientMiddleware)
+          end
+        end
+      end
+
+      private
+
+      # Sidekiq 7+ exposes per-config error_handlers; pre-7 used the global
+      # Sidekiq.error_handlers array. Support both so users on older Sidekiq
+      # don't have to wire the safety net manually.
+      def register_error_handler(config)
+        # The 3rd arg (config) was added in Sidekiq 7. Default it so the
+        # same proc works under Sidekiq 6.
+        handler = proc do |exception, ctx, _config = nil|
+          next unless exception.is_a?(Exception)
+          # If the server middleware already reported this exception, skip —
+          # otherwise a single failed job lands in the issue list twice.
+          seen = Thread.current[:errsight_captured_exceptions] ||= []
+          next if seen.include?(exception.object_id)
+          seen << exception.object_id
+
+          Errsight.capture_exception(
+            exception,
+            metadata: { sidekiq_context: stringify_keys(ctx) },
+            tags: { "sidekiq.source" => "error_handler" }
+          )
+        rescue StandardError
+          # Never let our handler tip Sidekiq into a meta-error loop.
+        end
+
+        if config.respond_to?(:error_handlers)
+          config.error_handlers << handler
+        elsif ::Sidekiq.respond_to?(:error_handlers)
+          ::Sidekiq.error_handlers << handler
+        end
+      end
+
+      def stringify_keys(hash)
+        return {} unless hash.is_a?(Hash)
+        hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+
+    class ClientMiddleware
+      include ::Sidekiq::ClientMiddleware if defined?(::Sidekiq::ClientMiddleware)
+
+      def call(_worker_class, job, _queue, _redis_pool)
+        snapshot = scope_snapshot
+        job["errsight_scope"] = snapshot unless snapshot.empty?
+        yield
+      end
+
+      private
+
+      # Delegate to Scope#to_h, which encodes the "user breadcrumbs only;
+      # DB crumbs stay process-local" propagation rule. Cap the propagated
+      # crumbs to keep job payloads small in Redis on high-throughput queues.
+      def scope_snapshot
+        hash = Errsight.current_scope.to_h
+        if hash["breadcrumbs"].is_a?(Array) && hash["breadcrumbs"].size > MAX_PROPAGATED_BREADCRUMBS
+          hash["breadcrumbs"] = hash["breadcrumbs"].last(MAX_PROPAGATED_BREADCRUMBS)
+        end
+        hash
+      end
+    end
+
+    class ServerMiddleware
+      include ::Sidekiq::ServerMiddleware if defined?(::Sidekiq::ServerMiddleware)
+
+      def call(worker, job, queue)
+        Errsight.with_scope(scope_for_job(job)) do
+          run_with_capture(worker, job, queue) { yield }
+        end
+      ensure
+        # Match the dedup-set lifecycle from CaptureMiddleware: cleared at
+        # job boundary so the next job on the same Sidekiq thread starts
+        # fresh and isn't tricked into skipping a legitimately new error.
+        Thread.current[:errsight_captured_exceptions] = nil
+      end
+
+      private
+
+      # Start from the worker thread's root scope (which carries any
+      # process-wide tags set at boot) and overlay the snapshot shipped by
+      # the enqueuing process. Job context wins on conflicts because the
+      # enqueuer knew which user/request triggered the work.
+      def scope_for_job(job)
+        scope = Errsight.hub.current_scope.dup
+        snapshot = job["errsight_scope"]
+        scope.merge!(::Errsight::Scope.from_h(snapshot)) if snapshot.is_a?(Hash)
+        scope
+      end
+
+      def run_with_capture(worker, job, queue)
+        yield
+      rescue Exception => exception
+        capture(exception, worker, job, queue)
+        raise
+      end
+
+      def capture(exception, worker, job, queue)
+        seen = Thread.current[:errsight_captured_exceptions] ||= []
+        return if seen.include?(exception.object_id)
+        seen << exception.object_id
+
+        Errsight.capture_exception(
+          exception,
+          tags: build_tags(worker, job, queue),
+          metadata: { sidekiq: build_metadata(job) }
+        )
+      rescue StandardError
+        # Never let our own capture failure suppress the job's exception —
+        # Sidekiq still needs to see the original to retry.
+      end
+
+      def build_tags(worker, job, queue)
+        {
+          "sidekiq.worker"      => worker_name(job, worker),
+          "sidekiq.queue"       => queue.to_s,
+          "sidekiq.jid"         => job["jid"].to_s,
+          "sidekiq.retry_count" => job["retry_count"].to_s
+        }.reject { |_, v| v.to_s.strip.empty? }
+      end
+
+      def build_metadata(job)
+        {
+          "args"        => filter_args(args_for_metadata(job)),
+          "queue"       => job["queue"],
+          "jid"         => job["jid"],
+          "enqueued_at" => job["enqueued_at"],
+          "created_at"  => job["created_at"],
+          "retry"       => job["retry"],
+          "retry_count" => job["retry_count"]
+        }.compact
+      end
+
+      def worker_name(job, worker)
+        # ActiveJob jobs land here with class = "ActiveJob::QueueAdapters::
+        # SidekiqAdapter::JobWrapper" and the real class in `wrapped`.
+        # Surface the real class so the issues UI doesn't group every AJ job
+        # under a single useless wrapper name.
+        job["wrapped"] || job["class"] || worker&.class&.name || "Unknown"
+      end
+
+      def args_for_metadata(job)
+        if job["wrapped"]
+          # ActiveJob: real args live at args[0]["arguments"].
+          wrapper = Array(job["args"]).first
+          wrapper.is_a?(Hash) ? (wrapper["arguments"] || []) : []
+        else
+          job["args"] || []
+        end
+      end
+
+      def filter_args(args)
+        return [] unless args.is_a?(Array)
+        args.map { |arg| filter_one(arg) }
+      end
+
+      def filter_one(arg)
+        case arg
+        when Hash  then filter_hash(arg)
+        when Array then arg.map { |a| filter_one(a) }
+        else            truncate_value(arg)
+        end
+      end
+
+      def filter_hash(hash)
+        filter = self.class.parameter_filter
+        normalized = hash.transform_keys(&:to_s)
+        filtered = filter ? filter.filter(normalized) : normalized
+        filtered.transform_values { |v| filter_one(v) }
+      rescue StandardError
+        { "_unfilterable" => "[#{hash.class.name}]" }
+      end
+
+      def truncate_value(value)
+        str = value.to_s
+        return value if str.bytesize <= MAX_ARG_BYTES
+        "[truncated #{value.class.name} #{str.bytesize}b]"
+      end
+
+      # Cached at class level — Rails.application.config.filter_parameters
+      # is effectively immutable after boot; rebuilding the ParameterFilter
+      # per job is wasted allocation on the hot path.
+      def self.parameter_filter
+        return @parameter_filter if defined?(@parameter_filter)
+        @parameter_filter =
+          if defined?(::ActiveSupport::ParameterFilter) && defined?(::Rails) && ::Rails.application
+            ::ActiveSupport::ParameterFilter.new(::Rails.application.config.filter_parameters)
+          end
+      end
+    end
+  end
+end
+
+Errsight::Sidekiq.configure_integration! if defined?(::Sidekiq)

data/lib/errsight/source_context.rb

@@ -0,0 +1,107 @@
+module Errsight
+  # Reads source files to attach `pre_context`, `context_line`, and
+  # `post_context` to in_app backtrace frames — the snippet of code around
+  # the failing line that turns "stack trace at user.rb:42" into "here's
+  # what user.rb:42 looked like when it crashed."
+  #
+  # Reference: sentry-ruby's `Sentry::LineCache`. Their cache is per-process
+  # bounded LRU; ours is the same idea, smaller, no dependencies.
+  module SourceContext
+    # 5 lines before, 5 lines after — sentry's default and a comfortable
+    # debugging window. Larger values bloat events without adding value.
+    PRE_CONTEXT_LINES  = 5
+    POST_CONTEXT_LINES = 5
+
+    # Cap each emitted line to keep events bounded. A 1MB minified JS line
+    # accidentally landing in a Ruby backtrace (it happens via Sprockets
+    # asset pipeline errors) shouldn't blow our 512KB ingestion limit.
+    MAX_LINE_BYTES = 256
+
+    # LRU bound. 100 files × ~100 lines avg × ~80 bytes per line = ~800KB
+    # cache footprint per process. Cheap. A request typically reads <10
+    # unique files for context; the cache absorbs cross-request sharing.
+    CACHE_SIZE = 100
+
+    class << self
+      # Returns { pre_context:, context_line:, post_context: } or nil if the
+      # file can't be read (missing, eval'd, internal, permission denied,
+      # malformed encoding, …). Never raises — source-context failure must
+      # not cascade into a failed event capture.
+      def fetch(filename, lineno)
+        return nil unless filename.is_a?(String) && !filename.empty?
+        return nil unless lineno.is_a?(Integer) && lineno > 0
+        # Synthetic frames have no readable source.
+        return nil if filename.start_with?("<", "(")
+
+        lines = read_lines(filename)
+        return nil unless lines
+
+        idx = lineno - 1
+        return nil if idx < 0 || idx >= lines.size
+
+        {
+          pre_context:  slice_with_truncation(lines, [ idx - PRE_CONTEXT_LINES, 0 ].max, idx - 1),
+          context_line: truncate(lines[idx]),
+          post_context: slice_with_truncation(lines, idx + 1, [ idx + POST_CONTEXT_LINES, lines.size - 1 ].min)
+        }
+      rescue StandardError
+        nil
+      end
+
+      # Test-only: drop the cache so a test that mutates a fixture file
+      # gets the fresh contents on the next fetch.
+      def reset_cache!
+        @cache = nil
+        @order = nil
+      end
+
+      private
+
+      def read_lines(filename)
+        @cache ||= {}
+        @order ||= []
+
+        if @cache.key?(filename)
+          # LRU touch: move to most-recent end.
+          @order.delete(filename)
+          @order << filename
+          return @cache[filename]
+        end
+
+        return nil unless File.file?(filename) && File.readable?(filename)
+
+        # Force UTF-8; if the file has invalid bytes, fall back to binary
+        # so we don't raise. Source files in production should be clean
+        # UTF-8 but customer fixtures sometimes aren't.
+        contents = File.read(filename, mode: "r:utf-8")
+        contents = contents.scrub("?") unless contents.valid_encoding?
+
+        lines = contents.lines.map { |l| l.chomp }
+        @cache[filename] = lines
+        @order           << filename
+
+        # Evict oldest until we're at or below the cap.
+        while @order.size > CACHE_SIZE
+          evicted = @order.shift
+          @cache.delete(evicted)
+        end
+
+        lines
+      rescue StandardError
+        # File errors (permission denied, vanished mid-read, etc.) — return
+        # nil so fetch returns nil so the frame just lacks source context.
+        nil
+      end
+
+      def slice_with_truncation(lines, from, to)
+        return [] if to < from
+        lines[from..to].to_a.map { |l| truncate(l) }
+      end
+
+      def truncate(line)
+        return line.to_s if line.nil?
+        line.bytesize > MAX_LINE_BYTES ? line.byteslice(0, MAX_LINE_BYTES) + "…[truncated]" : line
+      end
+    end
+  end
+end

data/lib/errsight/version.rb

@@ -0,0 +1,3 @@
+module Errsight
+  VERSION = "0.2.2"
+end

data/lib/errsight.rb

@@ -0,0 +1,193 @@
+require "securerandom"
+require "errsight/version"
+require "errsight/configuration"
+require "errsight/scope"
+require "errsight/hub"
+require "errsight/backtrace"
+require "errsight/source_context"
+require "errsight/client"
+require "errsight/logger"
+require "errsight/middleware"
+require "errsight/capture_middleware"
+require "errsight/railtie" if defined?(Rails)
+
+module Errsight
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+      configuration
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def hub
+      Hub.current
+    end
+
+    def current_scope
+      hub.current_scope
+    end
+
+    # Push a fresh scope for the duration of the block, then pop on exit.
+    # Used by request and job middleware so user/tags/breadcrumbs set during
+    # one unit of work don't leak to the next one handled by the same thread.
+    # Pass an explicit Scope to install a pre-built one (e.g. rehydrated
+    # from a Sidekiq job payload).
+    def with_scope(scope = nil, &block)
+      hub.with_scope(scope, &block)
+    end
+
+    # Public scope mutators delegate to the current (top-of-stack) scope.
+    # Pre-scope-stack callers wrote directly to Thread.current and relied on
+    # the request middleware to clear; those reads bled across requests on
+    # long-lived Puma/Sidekiq threads. The stack guarantees cleanup at the
+    # block boundary regardless of caller hygiene.
+    def set_user(user);            current_scope.set_user(user); end
+    def clear_user;                current_scope.clear_user; end
+    def set_tag(key, value);       current_scope.set_tag(key, value); end
+    def set_tags(tags);            current_scope.set_tags(tags); end
+    def clear_tags;                current_scope.clear_tags; end
+    def add_breadcrumb(**kwargs);  current_scope.add_breadcrumb(**kwargs); end
+    def clear_breadcrumbs;         current_scope.clear_breadcrumbs; end
+
+    def log(level:, message:, backtrace: nil, environment: nil, metadata: {},
+            occurred_at: nil, fingerprint: nil, user: nil, tags: nil, release: nil)
+      return unless configuration.enabled?
+      return if level_below_threshold?(level)
+
+      scope = current_scope
+      event = {
+        ingestion_id: SecureRandom.uuid,
+        level: level.to_s,
+        message: message.to_s,
+        backtrace: backtrace,
+        environment: environment || configuration.environment,
+        metadata: metadata,
+        occurred_at: (occurred_at || Time.now).iso8601(3),
+        release: release || configuration.release,
+        user: user || scope.user,
+        tags: merge_tags(scope.tags, tags),
+        breadcrumbs: scope.breadcrumbs
+      }
+      event[:fingerprint] = fingerprint if fingerprint
+      event.compact!
+
+      event = run_before_send(event)
+      return if event.nil?
+
+      client.enqueue(event)
+    end
+
+    def capture_exception(exception, metadata: {}, fingerprint: nil, user: nil, tags: nil)
+      return unless exception.is_a?(Exception)
+
+      enriched_metadata = metadata.merge(exception_class: exception.class.to_s)
+      causes = walk_exception_causes(exception)
+      enriched_metadata[:exception_causes] = causes if causes.any?
+
+      frames = build_frames(exception)
+      enriched_metadata[:exception_frames] = frames if frames.any?
+
+      log(
+        level: :error,
+        message: "#{exception.class}: #{exception.message}",
+        backtrace: exception.backtrace&.join("\n"),
+        metadata: enriched_metadata,
+        fingerprint: fingerprint,
+        user: user,
+        tags: tags
+      )
+    end
+
+    private
+
+    # Hard cap on cause-chain depth. Exception#cause can technically loop if
+    # someone constructs a pathological chain manually; the seen-set guards
+    # against that, but the depth cap is the load-bearing protection.
+    MAX_CAUSE_DEPTH    = 5
+    MAX_CAUSE_BACKTRACE_FRAMES = 20
+
+    # Parse the exception's backtrace into structured frames + attach
+    # source context to in_app frames. Ships in metadata[:exception_frames]
+    # alongside the legacy `backtrace` string so the backend can render
+    # whichever it knows how to show. Source context is the
+    # debugging-experience differentiator: stacks become "here's the line
+    # of your code that failed, with 5 lines of surrounding context."
+    def build_frames(exception)
+      raw = exception.backtrace
+      return [] unless raw.is_a?(Array) && raw.any?
+
+      frames = Backtrace.parse(raw)
+      frames.each do |frame|
+        next unless frame[:in_app] && frame[:abs_path]
+        ctx = SourceContext.fetch(frame[:abs_path], frame[:lineno])
+        frame.merge!(ctx) if ctx
+      end
+      frames
+    rescue StandardError
+      # Frame parsing must never break capture. Fall back to no structured
+      # frames; the legacy backtrace string still ships.
+      []
+    end
+
+    # Ruby chains exceptions via #cause when one rescue raises another. The
+    # outer exception's class+message is what the user sees in the issue
+    # title, but the inner cause is usually what actually broke (Net::Read
+    # Timeout under PaymentGatewayError). Surface the chain so the issue
+    # detail page can show "rescued from <inner>".
+    def walk_exception_causes(exception)
+      causes = []
+      current = exception.cause
+      seen = { exception.object_id => true }
+      while current && causes.size < MAX_CAUSE_DEPTH && !seen[current.object_id]
+        seen[current.object_id] = true
+        causes << {
+          class:     current.class.to_s,
+          message:   current.message.to_s,
+          backtrace: current.backtrace&.first(MAX_CAUSE_BACKTRACE_FRAMES)
+        }
+        current = current.cause
+      end
+      causes
+    end
+
+    # Customer-supplied final-mile filter. If it returns nil, the event is
+    # dropped silently. If it raises, we log the error and pass the event
+    # through unmodified — silently dropping production errors because the
+    # customer's filter has a bug is worse than the bug itself.
+    def run_before_send(event)
+      filter = configuration.before_send
+      return event unless filter.respond_to?(:call)
+      result = filter.call(event)
+      result.is_a?(Hash) ? result : nil
+    rescue StandardError => e
+      configuration.logger&.warn(
+        "[Errsight] before_send raised #{e.class}: #{e.message} — passing event through unmodified"
+      )
+      event
+    end
+
+    def merge_tags(scope_tags, per_call)
+      return scope_tags if per_call.nil? || per_call.empty?
+      scope_tags.merge(per_call.transform_keys(&:to_s).transform_values(&:to_s))
+    end
+
+    def level_below_threshold?(level)
+      level_value(level) < level_value(configuration.min_level)
+    end
+
+    def level_value(level)
+      %i[debug info warning error fatal].index(level.to_sym) || 0
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: errsight
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+platform: ruby
+authors:
+- Errsight
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A lightweight Ruby gem that hooks into Rails.logger and sends logs/errors
+  to the Errsight API.
+email:
+- support@errsight.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- errsight.gemspec
+- lib/errsight.rb
+- lib/errsight/backtrace.rb
+- lib/errsight/capture_middleware.rb
+- lib/errsight/client.rb
+- lib/errsight/configuration.rb
+- lib/errsight/hub.rb
+- lib/errsight/integrations/active_job.rb
+- lib/errsight/integrations/active_record.rb
+- lib/errsight/integrations/rails_error_reporter.rb
+- lib/errsight/logger.rb
+- lib/errsight/middleware.rb
+- lib/errsight/railtie.rb
+- lib/errsight/scope.rb
+- lib/errsight/sidekiq.rb
+- lib/errsight/source_context.rb
+- lib/errsight/version.rb
+homepage: https://errsight.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://errsight.com
+  source_code_uri: https://github.com/errsight/errsight-ruby
+  bug_tracker_uri: https://github.com/errsight/errsight-ruby/issues
+  changelog_uri: https://github.com/errsight/errsight-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby/Rails client for Errsight error tracking
+test_files: []