errsight 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a7079dd5ddd0a725362a26c5d27610b7b45211ba86d3536bd47bae927a63880
+  data.tar.gz: 4b8343248a41207ff06a94785dda20f055c9fef026904ee9fc37ff9ccc45e45b
+SHA512:
+  metadata.gz: 35f7f650aa33896bb8438481f0982f7d9222e9027e29a481505f33f17b6c4100e4de9d654e044bd82554788f74d1362b5a615eb941637a6ab06291d5040bb597
+  data.tar.gz: dd8dc8cdff1cdfedce818896e6c1deb8c871969ed01f4cafe639eb6d6b4067bc90ae208b9523c80adef46ed2f655645f753209b75859298200da4b7f3835be04

data/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+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.2.0] - 2026-05-05
+
+A foundational release that hardens the SDK for production Rails apps and
+adds the integrations that distinguish ErrSight as a Rails-native error
+tracker. Several long-standing bugs that silently dropped events on
+Puma cluster mode and during shutdown are fixed, and PII handling is
+significantly stricter.
+
+Recommended for everyone on `0.1.x` — there are no breaking API changes
+beyond a default behavior flip on `attach_to_rails_logger` (see Changed).
+
+### Added
+
+- **Sidekiq integration.** Server middleware captures job exceptions with
+  structured context (`sidekiq.worker`, `sidekiq.queue`, `sidekiq.jid`,
+  `sidekiq.retry_count`) plus filtered job args and timestamps. Client
+  middleware propagates `user`, `tags`, and manual breadcrumbs from the
+  enqueueing request into the job payload so a job's errors carry the
+  right context. Auto-wired by the Railtie when Sidekiq is loaded; no
+  manual configuration required. Job args are scrubbed through
+  `ActiveSupport::ParameterFilter` honoring the host's
+  `Rails.application.config.filter_parameters`. Args > 4 KB and runs of
+  arbitrary objects are truncated defensively.
+
+- **SQL breadcrumbs via `sql.active_record`.** Every non-cached,
+  non-schema query becomes a breadcrumb on the current scope, so a
+  captured `ActiveRecord::RecordNotFound` ships with the queries that
+  ran before it. SQL is truncated at 2 KB. Bind values are *off* by
+  default — they often carry PII (emails, tokens, customer IDs) — and
+  can be enabled with `breadcrumbs_active_record_capture_binds = true`.
+  Disable entirely with `breadcrumbs_active_record = false`.
+
+- **`Rails.error.subscribe` integration on Rails 7+.** Catches errors
+  from Active Job (after retries are exhausted), Active Storage, Action
+  Mailer, Action Cable, and any explicit `Rails.error.handle / .record /
+  .report` call in app code. Tags each capture with
+  `rails.error.severity`, `rails.error.handled`, `rails.error.source`.
+  Caller-supplied `context:` flows into `metadata[:rails_error_context]`.
+  Deduplicated against the existing middleware/notifications path via the
+  thread-local seen-set so a single 500 doesn't fan out into multiple
+  issues.
+
+- **Exception cause chain.** `capture_exception` now walks
+  `Exception#cause` (depth-capped at 5, cycle-protected) and ships each
+  cause as `metadata[:exception_causes]` with `class`, `message`, and
+  the first 20 backtrace frames. A `RuntimeError` rescued from a
+  `Net::ReadTimeout` now reports both, not just the outer wrapper.
+
+- **`before_send` callback** for final-mile filtering. Receives the
+  event hash, returns a (possibly modified) hash to send, or `nil` to
+  drop. If the callback raises, the event is sent through unmodified
+  rather than silently dropped — a buggy filter shouldn't mask
+  production errors. Enables PII scrubbing, error suppression, and
+  per-tenant routing without touching the SDK.
+
+      Errsight.configure do |c|
+        c.before_send = ->(event) {
+          event[:metadata].delete(:credit_card)
+          event
+        }
+      end
+
+- **Per-thread scope stack with `Errsight.with_scope { … }`.** Push/pop
+  primitive that lets callers isolate `set_user` / `set_tag` /
+  `add_breadcrumb` to a block. The Rails request middleware and Sidekiq
+  server middleware use this internally to scope state to a single
+  request or job.
+
+- **`Errsight::Scope`** and **`Errsight::Hub`** as public classes for
+  scope management, with `Scope#to_h` / `Scope.from_h` for cross-process
+  propagation.
+
+- **`configuration.shutdown_timeout`** (default `5` seconds) — bound on
+  how long `Errsight.client.shutdown!` will wait for the flush thread
+  to drain before killing it.
+
+### Changed
+
+- **`attach_to_rails_logger` now defaults to `false`.** Previously
+  `true`, which forwarded every `Rails.logger.warn` call as an event.
+  In practice this buried genuine errors under framework deprecation
+  noise and burned customer event quota for what belongs in a log
+  aggregator, not an error tracker. Customers who want log forwarding
+  can opt back in:
+
+      Errsight.configure { |c| c.attach_to_rails_logger = true }
+
+- **Breadcrumbs split into two ring buffers** (50 manual + 30 DB)
+  instead of a single 50-cap ring. A request that runs 500 queries can
+  no longer evict the user's manual breadcrumbs. `Scope#breadcrumbs`
+  returns a merged, timestamp-sorted view; the split is internal.
+
+- **`set_user` / `set_tag` / `add_breadcrumb` operate on the current
+  scope** (top of the hub stack) rather than `Thread.current` directly.
+  Existing code keeps working — the public API is unchanged — but state
+  no longer leaks across requests on long-lived Puma threads.
+
+- **Cross-process scope propagation only ships manual breadcrumbs.** DB
+  breadcrumbs stay process-local — the receiving worker collects its
+  own from its own queries. Affects Sidekiq job payloads.
+
+### Fixed
+
+- **PII leak across requests.** `Errsight.set_user(user)` previously
+  stored on `Thread.current` and was never auto-cleared. On long-lived
+  Puma threads, request B's exceptions could be tagged with request A's
+  user. Now scoped to a per-request scope frame that's pushed by the
+  Rack middleware and popped on exit — even if the controller raises
+  and never calls `clear_user`. **This was a real cross-user PII bug
+  in `0.1.x`.**
+
+- **Puma cluster mode silently dropped all events.** The SDK's flush
+  thread is started in `Client#initialize`, which runs in the Puma
+  primary at boot. Threads don't survive `fork()`, so worker processes
+  inherited a dead thread reference and never delivered any captured
+  event. The client now detects fork via `Process.pid` change at
+  `enqueue` time and rebuilds the queue, mutexes, HTTP connection, and
+  flush thread. Verified end-to-end with a real `fork()` test.
+
+- **Brutal shutdown via `flush_thread.exit`.** On `SIGTERM`, the old
+  code killed the flush thread mid-execution — possibly mid-HTTP
+  request — and called `flush!` on whatever queue state was left. Now
+  signals shutdown via a `Mutex + ConditionVariable`, joins with a
+  `shutdown_timeout` cap, falls back to `kill` only if a send is hung,
+  and runs a final drain on the way out so events queued during the
+  last flush interval aren't lost.
+
+- **429 rate-limit response parked the flush thread for up to 60 s.**
+  `sleep retry_after` blocked the only worker; new events filled the
+  queue past `max_queue_size` and were silently dropped via
+  `enqueue`'s overflow path. The 429 path now sets a
+  `@rate_limited_until` timestamp; the flush thread keeps ticking and
+  stays responsive to shutdown. `Retry-After` is capped at 600 s as
+  defense against an upstream returning an absurd value.
+
+- **`shutdown!` raised `NoMethodError`** when no HTTP request had ever
+  fired (the lazily-initialized `@http_mutex` was nil). Now goes
+  through the `http_mutex` accessor that lazy-inits.
+
+- **Sidekiq client middleware** was building its own scope snapshot and
+  would have leaked DB breadcrumbs across process boundaries. Now
+  delegates to `Scope#to_h`, which is the canonical serializer.
+
+### Security
+
+- **PII scrubbing hook** (`before_send`) lets compliance-conscious
+  customers strip sensitive fields before events leave the process.
+- **Sidekiq job args** are filtered through
+  `ActiveSupport::ParameterFilter` so passwords, tokens, and other
+  filtered fields configured by the host don't leak into error reports.
+- **Bind values in SQL breadcrumbs** are off by default. They often
+  carry PII; opt in only when the customer has confirmed the use case.
+
+## [0.1.6] - 2026-04-XX
+
+Earlier releases — see git history.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Errsight
+
+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,120 @@
+# errsight-ruby
+
+Ruby/Rails client for [ErrSight](https://errsight.com) error tracking. Captures exceptions and log entries and ships them to the ErrSight API in a background thread.
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails 6+ (optional — also works in plain Ruby)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "errsight"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Configuration
+
+### Rails
+
+Create an initializer at `config/initializers/errsight.rb`:
+
+```ruby
+Errsight.configure do |config|
+  config.api_key     = ENV["ERRSIGHT_API_KEY"]   # required
+  config.environment = Rails.env                  # default: ENV["ERRSIGHT_ENV"] || "production"
+end
+```
+
+That is all you need. The Railtie handles the rest automatically:
+
+- Attaches to `Rails.logger` so every log line is forwarded to ErrSight.
+- Subscribes to `process_action.action_controller` notifications to capture unhandled exceptions with request context (controller, action, path, params, current user).
+- Calls `Errsight.client.shutdown!` on process exit to drain the queue.
+
+### Plain Ruby
+
+```ruby
+require "errsight"
+
+Errsight.configure do |config|
+  config.api_key     = ENV["ERRSIGHT_API_KEY"]
+  config.environment = "production"
+end
+```
+
+### Environment variables
+
+| Variable          | Default                  | Description                          |
+|-------------------|--------------------------|--------------------------------------|
+| `ERRSIGHT_API_KEY` | —                        | Your project API key (required)      |
+| `ERRSIGHT_ENV`    | `"production"`           | Environment tag attached to events   |
+
+### All configuration options
+
+```ruby
+Errsight.configure do |config|
+  config.api_key                = ENV["ERRSIGHT_API_KEY"]
+  config.environment            = "production"
+  config.min_level              = :warning   # :debug | :info | :warning | :error | :fatal
+  config.host                   = "https://errsight.com"
+  config.timeout                = 5          # HTTP timeout in seconds
+  config.batch_size             = 10         # events per HTTP request
+  config.flush_interval         = 2          # background flush cadence in seconds
+  config.max_queue_size         = 1_000      # drop events when queue exceeds this
+  config.attach_to_rails_logger = true       # broadcast Rails.logger to ErrSight
+end
+```
+
+## Usage
+
+### Capture an exception
+
+```ruby
+begin
+  do_something_risky
+rescue => e
+  Errsight.capture_exception(e, metadata: { user_id: current_user.id })
+end
+```
+
+### Log a message directly
+
+```ruby
+Errsight.log(level: :error, message: "Payment gateway timeout", metadata: { order_id: 42 })
+```
+
+### Use as a Logger sink
+
+```ruby
+logger = Errsight::Logger.new          # standalone — forwards to API only
+logger = Errsight::Logger.new($stdout) # tee — writes to $stdout AND the API
+
+logger.warn  "Cache miss"
+logger.error "Unprocessable entity"
+```
+
+### Rails — automatic exception capture
+
+In a Rails app the Railtie automatically captures every unhandled exception raised during a controller action. Each event ships with:
+
+- **User context** (top-level `user` block): `id`, `email`, `username` from the signed-in Devise/Warden user (any scope, including ActiveAdmin), plus `ip_address` from `request.remote_ip` — populated even for anonymous requests.
+- **Tags** (filterable in the UI): `controller`, `action`, `request_method`, `status`, `ruby_version`, `rails_version`, `hostname`.
+- **Metadata**: `path`, `full_path`, `format`, `duration`, filtered `params` (respects Rails' `filter_parameters`), `exception_class`.
+- **Backtrace**: full `exception.backtrace`.
+
+No additional code is required.
+
+## How it works
+
+Events are pushed onto an in-memory queue and flushed to the API in batches by a background thread every `flush_interval` seconds (default: 2 s). A flush also triggers immediately when the queue reaches `batch_size`. On process exit the queue is drained synchronously before the process terminates.
+
+The HTTP transport uses `Net::HTTP` with no extra dependencies beyond `concurrent-ruby` for thread-safe queue operations.

data/errsight.gemspec

@@ -0,0 +1,26 @@
+require_relative "lib/errsight/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "errsight"
+  spec.version       = Errsight::VERSION
+  spec.authors       = ["Errsight"]
+  spec.email         = ["support@errsight.com"]
+
+  spec.summary       = "Ruby/Rails client for Errsight error tracking"
+  spec.description   = "A lightweight Ruby gem that hooks into Rails.logger and sends logs/errors to the Errsight API."
+  spec.homepage      = "https://errsight.com"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.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"
+  }
+
+  spec.files         = Dir["lib/**/*", "LICENSE", "README.md", "CHANGELOG.md", "errsight.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "concurrent-ruby", "~> 1.0"
+end

data/lib/errsight/backtrace.rb

@@ -0,0 +1,117 @@
+module Errsight
+  # Parses Ruby backtrace strings into structured frames and classifies each
+  # frame as in_app (customer code) vs framework/gem.
+  #
+  # Sentry-ruby was the reference for the parser regex and in_app strategy
+  # (study + reimplement, not copy). Their `Sentry::Backtrace` handles the
+  # same edge cases — JIT frames, eval'd code, native extensions — so the
+  # patterns are similar by necessity. The implementation is ours; the bug
+  # surface is ours to maintain.
+  module Backtrace
+    # Ruby 3.4+ formats methods with single quotes — "in 'method'".
+    # Earlier Ruby uses backticks — "in `method'". The character class
+    # accepts either opener; the closer is always a single quote.
+    RUBY_FRAME = %r{
+      \A
+      (?<file>.+?)
+      :(?<line>\d+)
+      (?::in\s+
+        ['`](?<method>.+)'
+      )?
+      \z
+    }x
+
+    # Cap on frames per event. A pathological infinite-recursion crash can
+    # produce 10k+ frames; without a cap the event blows past the 512 KB
+    # ingestion limit and gets rejected. Sentry caps at 50; we match.
+    MAX_FRAMES = 50
+
+    class << self
+      # Parses an Array<String> backtrace into Array<Hash> structured frames,
+      # most-recent-first (matching exception.backtrace's natural order).
+      def parse(lines, project_root: nil, gem_paths: nil)
+        return [] unless lines.is_a?(Array)
+        project_root ||= default_project_root
+        gem_paths    ||= default_gem_paths
+
+        lines.first(MAX_FRAMES).filter_map do |line|
+          parse_line(line, project_root: project_root, gem_paths: gem_paths)
+        end
+      end
+
+      def parse_line(line, project_root:, gem_paths:)
+        return nil unless line.is_a?(String)
+        match = RUBY_FRAME.match(line)
+        return nil unless match
+
+        abs_path = match[:file]
+        {
+          filename: relative_filename(abs_path, project_root),
+          abs_path: abs_path,
+          lineno:   match[:line].to_i,
+          function: match[:method],
+          in_app:   in_app?(abs_path, project_root, gem_paths)
+        }
+      end
+
+      # An "in_app" frame is customer code — the kind of frame the issue UI
+      # should highlight, expand, and show source context for. Framework
+      # frames (Rails, gems) collapse into a "show 14 framework frames"
+      # group so the eye lands on what actually broke.
+      #
+      # The order of checks matters: gem_paths first because Bundler can
+      # vendor gems inside the project tree (vendor/bundle), so a frame at
+      # /app/vendor/bundle/gems/foo/foo.rb starts with project_root but is
+      # not in_app.
+      def in_app?(abs_path, project_root, gem_paths)
+        return false if abs_path.nil? || abs_path.empty?
+        # Internal frames (<internal:...>, <main>, (eval)) aren't files we
+        # can show source context for — treat as not-in-app.
+        return false if abs_path.start_with?("<", "(")
+        return false if gem_paths.any? { |p| p && abs_path.start_with?(p) }
+        return false if project_root.nil? || project_root.empty?
+        abs_path.start_with?(project_root)
+      end
+
+      def relative_filename(abs_path, project_root)
+        return abs_path if abs_path.nil?
+        return abs_path if project_root.nil? || project_root.empty?
+        return abs_path unless abs_path.start_with?(project_root)
+        # Strip "<project_root>/" prefix; leaves "app/models/user.rb" etc.
+        rest = abs_path[project_root.size..]
+        rest.sub(%r{\A/}, "")
+      end
+
+      def default_project_root
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          ::Rails.root.to_s
+        else
+          Dir.pwd
+        end
+      end
+
+      # Bundler.bundle_path can sit inside the project (vendor/bundle), so
+      # we include it AND Gem.path. Anything inside any of these is "not
+      # customer code." Memoization is per-process; these paths don't move
+      # at runtime.
+      def default_gem_paths
+        return @default_gem_paths if defined?(@default_gem_paths)
+        paths = []
+        paths.concat(Gem.path.map(&:to_s)) if defined?(::Gem)
+        begin
+          paths << ::Bundler.bundle_path.to_s if defined?(::Bundler) && ::Bundler.respond_to?(:bundle_path)
+        rescue StandardError
+          # Bundler.bundle_path can raise if Bundler isn't fully loaded
+          # (some test harnesses, gem-from-source setups). Ignore.
+        end
+        @default_gem_paths = paths.compact.uniq
+      end
+
+      # Test/dev only: drop the memoized paths so a test that mutates
+      # Rails.root or Bundler can re-derive.
+      def reset_defaults!
+        remove_instance_variable(:@default_gem_paths) if defined?(@default_gem_paths)
+      end
+    end
+  end
+end

data/lib/errsight/capture_middleware.rb

@@ -0,0 +1,95 @@
+module Errsight
+  # Catches exceptions raised by any inner middleware/controller before
+  # ActionDispatch::DebugExceptions converts them into an HTTP response, so
+  # errors that occur outside the controller (e.g. ActiveRecord::Migration::
+  # CheckPending, Rack middleware, routing) are still reported with a real
+  # backtrace. Inserted *after* DebugExceptions in the stack so the dev/error
+  # page still renders normally on re-raise.
+  class CaptureMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      # Push a per-request scope so set_user/set_tag/add_breadcrumb calls made
+      # by app code are isolated to this request. Capture happens *inside* the
+      # block so the exception is tagged with the request's scope before pop.
+      Errsight.with_scope do
+        begin
+          @app.call(env)
+        rescue Exception => exception
+          capture(exception, env, started)
+          raise
+        end
+      end
+    ensure
+      Thread.current[:errsight_captured_exceptions] = nil
+    end
+
+    private
+
+    def capture(exception, env, started_monotonic)
+      seen = Thread.current[:errsight_captured_exceptions] ||= []
+      return if seen.include?(exception.object_id)
+      seen << exception.object_id
+
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_monotonic) * 1000).round(2)
+      request = build_request(env)
+
+      metadata = build_metadata(request, env, duration_ms)
+      user_ctx = (Errsight::Railtie.build_user_context(request) if defined?(Errsight::Railtie) && request)
+      tags     = build_tags(request, env)
+
+      Errsight.capture_exception(exception, metadata: metadata, user: user_ctx, tags: tags)
+    rescue StandardError
+      # Never let our own capture failure suppress the original exception.
+    end
+
+    def build_request(env)
+      return nil unless defined?(ActionDispatch::Request)
+      ActionDispatch::Request.new(env)
+    rescue StandardError
+      nil
+    end
+
+    def build_metadata(request, env, duration_ms)
+      meta = { duration: duration_ms }
+
+      if request
+        meta[:path]      = request.path
+        meta[:full_path] = (request.url rescue nil)
+        meta[:format]    = (request.formats.first&.to_s rescue nil)
+
+        if %w[POST PATCH PUT DELETE].include?(request.request_method)
+          begin
+            filtered = request.filtered_parameters
+                              .except("controller", "action", "format", "authenticity_token")
+            meta[:params] = filtered unless filtered.empty?
+          rescue StandardError
+            # filtered_parameters can raise on malformed bodies — ignore
+          end
+        end
+      else
+        meta[:path] = env["PATH_INFO"]
+      end
+
+      meta.compact
+    end
+
+    def build_tags(request, env)
+      params = env["action_dispatch.request.path_parameters"] || {}
+      tags = {
+        "controller"     => params[:controller],
+        "action"         => params[:action],
+        "request_method" => request&.request_method || env["REQUEST_METHOD"],
+        "ruby_version"   => RUBY_VERSION
+      }
+      tags["rails_version"] = Rails.version if defined?(Rails) && Rails.respond_to?(:version)
+      if defined?(Errsight::Railtie) && Errsight::Railtie::HOSTNAME
+        tags["hostname"] = Errsight::Railtie::HOSTNAME
+      end
+      tags.compact.reject { |_, v| v.to_s.strip.empty? }
+    end
+  end
+end