bugwatch-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d791f28771211d583f75d081bab1ac2a669f8cd5e023f8ec4a54045588955781
+  data.tar.gz: 5194c786bf49b7549fdf52c3b32fa3a8b2e8b285000f7339828e49bf2f6972d9
+SHA512:
+  metadata.gz: e7100cf66b34e6fbf8851d36851e9b9aab6376b8a9eebfd9d08a3f701144a23f056bf17b972e61ca4af00430d1e26c57a24a4fd2b2811530b07ae83ba6e19c01
+  data.tar.gz: 915b85cd3c4ab144027c9ab7d6c8098e38dfbf52429adb6c27070045eca8dd9889e82c71613c82653c0ee679182a8c4105421aaf90866c3e5d0babe890ce011c

data/README.md

@@ -0,0 +1,96 @@
+# bugwatch-ruby
+
+Official Ruby/Rails SDK for [BugWatch](https://bugwatch.io) — open-source error monitoring.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "bugwatch-ruby"
+```
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+# config/initializers/bugwatch.rb
+Bugwatch.configure do |c|
+  c.api_key               = ENV["BUGWATCH_API_KEY"]
+  c.endpoint              = ENV["BUGWATCH_ENDPOINT"]   # e.g. "https://your-app.herokuapp.com"
+  c.release_stage         = Rails.env.to_s
+  c.notify_release_stages = ["production", "staging"]
+  c.ignore_classes        = ["ActionController::RoutingError"]
+  c.app_version           = ENV["GIT_REV"]             # optional git SHA
+end
+```
+
+## User context
+
+```ruby
+# app/controllers/application_controller.rb
+before_action :set_bugwatch_user
+
+private
+
+def set_bugwatch_user
+  return unless current_user
+  Bugwatch.set_user(
+    id:    current_user.id,
+    email: current_user.email,
+    name:  current_user.name
+  )
+end
+```
+
+## Breadcrumbs
+
+```ruby
+Bugwatch.leave_breadcrumb("User clicked checkout", type: "ui", metadata: { cart_id: 42 })
+```
+
+## Manual notification
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  Bugwatch.notify(e)
+  raise
+end
+```
+
+## How it works
+
+1. `Bugwatch::Middleware` wraps your entire Rack stack.
+2. When an unhandled exception propagates out of a request, the middleware:
+   - Captures the exception, full backtrace (with 3 lines of source context per in-app frame), request details, user context, and breadcrumbs.
+   - POSTs the payload to your BugWatch instance in a background thread (fire-and-forget, 3s timeout).
+   - Re-raises the exception so Rails error handling fires normally.
+3. Thread-local user context and breadcrumbs are cleared automatically after each request by the Rails around_action hook.
+
+## What gets sent
+
+| Field | Description |
+|-------|-------------|
+| `exception.error_class` | Exception class name |
+| `exception.message` | Exception message |
+| `exception.backtrace` | Array of frames with `file`, `line`, `method`, `in_app`, `source_context` |
+| `request.*` | Method, URL, params (filtered), headers (filtered), IP |
+| `app.*` | Rails env, Ruby version, Rails version, git SHA, hostname |
+| `user.*` | ID, email, name, any custom fields |
+| `breadcrumbs` | Last 50 breadcrumbs with timestamp, type, message, metadata |
+| `duration_ms` | Request duration in milliseconds |
+
+Sensitive params (`password`, `token`, `secret`, `key`, `auth`, `credit`, `card`, `cvv`, `ssn`) are automatically filtered from request params and never sent.
+
+## Publishing
+
+```bash
+cd /home/max/bugwatch-ruby
+gem build bugwatch-ruby.gemspec
+gem signin
+gem push bugwatch-ruby-0.1.0.gem
+```

data/lib/bugwatch/backtrace_cleaner.rb

@@ -0,0 +1,63 @@
+module Bugwatch
+  class BacktraceCleaner
+    STDLIB_PATHS = [
+      RbConfig::CONFIG["rubylibdir"],
+      RbConfig::CONFIG["rubyarchdir"],
+      Gem.default_dir
+    ].compact.map { |p| Regexp.escape(p) }
+
+    GEM_PATH_RE = /\/gems\//
+    STDLIB_RE   = Regexp.union(*STDLIB_PATHS) unless STDLIB_PATHS.empty?
+
+    def self.clean(backtrace)
+      return [] unless backtrace
+
+      backtrace.map do |line|
+        path, lineno, label = parse_frame(line)
+        in_app = in_app?(path)
+
+        frame = {
+          file:   path,
+          line:   lineno,
+          method: label,
+          in_app: in_app
+        }
+
+        if in_app && path && File.exist?(path)
+          frame[:source_context] = read_source_context(path, lineno)
+        end
+
+        frame
+      end
+    end
+
+    def self.parse_frame(line)
+      if line =~ /\A(.+?):(\d+):in `(.*)'\z/
+        [$1, $2.to_i, $3]
+      elsif line =~ /\A(.+?):(\d+)\z/
+        [$1, $2.to_i, nil]
+      else
+        [line, 0, nil]
+      end
+    end
+
+    def self.in_app?(path)
+      return false if path.nil?
+      return false if path.match?(GEM_PATH_RE)
+      return false if defined?(STDLIB_RE) && path.match?(STDLIB_RE)
+      true
+    end
+
+    def self.read_source_context(path, lineno, context_lines: 3)
+      lines = File.readlines(path)
+      first = [lineno - context_lines - 1, 0].max
+      last  = [lineno + context_lines - 1, lines.size - 1].min
+
+      lines[first..last].each_with_object({}).with_index(first + 1) do |(source_line, hash), n|
+        hash[n] = source_line.chomp
+      end
+    rescue Errno::ENOENT, Errno::EACCES
+      {}
+    end
+  end
+end

data/lib/bugwatch/breadcrumb_collector.rb

@@ -0,0 +1,25 @@
+module Bugwatch
+  module BreadcrumbCollector
+    THREAD_KEY  = :bugwatch_breadcrumbs
+    MAX_CRUMBS  = 50
+
+    def self.add(message, type: "manual", metadata: {})
+      crumbs = Thread.current[THREAD_KEY] ||= []
+      crumbs << {
+        timestamp: Time.now.utc.iso8601(3),
+        type:      type,
+        message:   message.to_s,
+        metadata:  metadata
+      }
+      crumbs.shift if crumbs.size > MAX_CRUMBS
+    end
+
+    def self.all
+      Thread.current[THREAD_KEY] || []
+    end
+
+    def self.clear
+      Thread.current[THREAD_KEY] = []
+    end
+  end
+end

data/lib/bugwatch/configuration.rb

@@ -0,0 +1,32 @@
+module Bugwatch
+  class Configuration
+    attr_accessor :api_key,
+                  :endpoint,
+                  :release_stage,
+                  :notify_release_stages,
+                  :ignore_classes,
+                  :app_version,
+                  :logger
+
+    def initialize
+      @endpoint              = nil
+      @release_stage         = "production"
+      @notify_release_stages = ["production"]
+      @ignore_classes        = []
+      @logger                = Logger.new($stdout) if defined?(Logger)
+    end
+
+    def notify_for_release_stage?
+      notify_release_stages.include?(release_stage.to_s)
+    end
+
+    def ignore?(exception)
+      ignore_classes.any? do |klass|
+        klass = Object.const_get(klass) if klass.is_a?(String)
+        exception.is_a?(klass)
+      rescue NameError
+        false
+      end
+    end
+  end
+end

data/lib/bugwatch/error_builder.rb

@@ -0,0 +1,75 @@
+module Bugwatch
+  class ErrorBuilder
+    def initialize(exception, rack_env = nil, config: Bugwatch.configuration)
+      @exception = exception
+      @rack_env  = rack_env
+      @config    = config
+    end
+
+    def build
+      {
+        exception: exception_payload,
+        request:   request_payload,
+        app:       app_payload,
+        user:      UserContext.get,
+        breadcrumbs: BreadcrumbCollector.all
+      }
+    end
+
+    private
+
+    def exception_payload
+      {
+        error_class: @exception.class.name,
+        message:     @exception.message,
+        backtrace:   BacktraceCleaner.clean(@exception.backtrace)
+      }
+    end
+
+    def request_payload
+      return {} unless @rack_env
+
+      req = Rack::Request.new(@rack_env)
+
+      {
+        method:  req.request_method,
+        url:     req.url,
+        params:  safe_params(req),
+        headers: extract_headers(@rack_env),
+        ip:      req.ip
+      }
+    rescue StandardError
+      {}
+    end
+
+    def app_payload
+      payload = {
+        environment: @config.release_stage,
+        version:     @config.app_version,
+        hostname:    Socket.gethostname
+      }
+
+      if defined?(RUBY_VERSION)
+        payload[:ruby_version] = RUBY_VERSION
+      end
+
+      if defined?(Rails)
+        payload[:rails_version] = Rails.version
+      end
+
+      payload
+    end
+
+    def safe_params(req)
+      req.params.reject { |k, _| k.to_s.downcase.match?(/password|secret|token|key|auth|credit|card|cvv|ssn/) }
+    rescue StandardError
+      {}
+    end
+
+    def extract_headers(env)
+      env.select { |k, _| k.start_with?("HTTP_") }
+         .transform_keys { |k| k.sub(/^HTTP_/, "").split("_").map(&:capitalize).join("-") }
+         .reject { |k, _| k.downcase.match?(/cookie|authorization/) }
+    end
+  end
+end

data/lib/bugwatch/middleware.rb

@@ -0,0 +1,28 @@
+module Bugwatch
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      BreadcrumbCollector.clear
+      UserContext.clear
+
+      begin
+        status, headers, body = @app.call(env)
+        [status, headers, body]
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+
+        unless Bugwatch.configuration.ignore?(e)
+          payload = ErrorBuilder.new(e, env).build
+          payload[:duration_ms] = duration_ms
+          Notification.new(payload).deliver
+        end
+
+        raise
+      end
+    end
+  end
+end

data/lib/bugwatch/notification.rb

@@ -0,0 +1,49 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Bugwatch
+  class Notification
+    TIMEOUT = 3
+
+    def initialize(payload, config: Bugwatch.configuration)
+      @payload = payload
+      @config  = config
+    end
+
+    def deliver
+      return unless @config.api_key
+      return unless @config.endpoint
+      return unless @config.notify_for_release_stage?
+
+      Thread.new do
+        post_to_api
+      rescue StandardError
+        # Fire-and-forget: swallow all errors so the gem never affects the app
+      end
+    end
+
+    private
+
+    def post_to_api
+      uri = URI.parse("#{@config.endpoint.chomp("/")}/api/v1/errors")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl       = uri.scheme == "https"
+      http.open_timeout  = TIMEOUT
+      http.read_timeout  = TIMEOUT
+      http.write_timeout = TIMEOUT
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"]    = "application/json"
+      request["X-Api-Key"]       = @config.api_key
+      request["X-BugWatch-Ruby"] = Bugwatch::VERSION
+
+      request.body = JSON.generate(@payload)
+
+      http.request(request)
+    rescue StandardError
+      # Silently discard network errors
+    end
+  end
+end

data/lib/bugwatch/railtie.rb

@@ -0,0 +1,32 @@
+module Bugwatch
+  class Railtie < Rails::Railtie
+    initializer "bugwatch.middleware" do |app|
+      app.middleware.use Bugwatch::Middleware
+    end
+
+    initializer "bugwatch.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include Bugwatch::ControllerMethods
+      end
+    end
+  end
+
+  module ControllerMethods
+    extend ActiveSupport::Concern
+
+    included do
+      around_action :bugwatch_reset_context
+    end
+
+    private
+
+    def bugwatch_reset_context
+      Bugwatch::UserContext.clear
+      Bugwatch::BreadcrumbCollector.clear
+      yield
+    ensure
+      Bugwatch::UserContext.clear
+      Bugwatch::BreadcrumbCollector.clear
+    end
+  end
+end

data/lib/bugwatch/user_context.rb

@@ -0,0 +1,17 @@
+module Bugwatch
+  module UserContext
+    THREAD_KEY = :bugwatch_user_context
+
+    def self.set(id: nil, email: nil, name: nil, **custom)
+      Thread.current[THREAD_KEY] = { id: id, email: email, name: name }.merge(custom).compact
+    end
+
+    def self.get
+      Thread.current[THREAD_KEY] || {}
+    end
+
+    def self.clear
+      Thread.current[THREAD_KEY] = nil
+    end
+  end
+end

data/lib/bugwatch/version.rb

@@ -0,0 +1,3 @@
+module Bugwatch
+  VERSION = "0.1.0"
+end

data/lib/bugwatch.rb

@@ -0,0 +1,41 @@
+require "logger"
+require "socket"
+
+require_relative "bugwatch/version"
+require_relative "bugwatch/configuration"
+require_relative "bugwatch/user_context"
+require_relative "bugwatch/breadcrumb_collector"
+require_relative "bugwatch/backtrace_cleaner"
+require_relative "bugwatch/error_builder"
+require_relative "bugwatch/notification"
+require_relative "bugwatch/middleware"
+require_relative "bugwatch/railtie" if defined?(Rails::Railtie)
+
+module Bugwatch
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def notify(exception, context: {})
+      return if configuration.ignore?(exception)
+      return unless configuration.notify_for_release_stage?
+
+      payload = ErrorBuilder.new(exception).build
+      payload.merge!(context)
+      Notification.new(payload).deliver
+    end
+
+    def set_user(id: nil, email: nil, name: nil, **custom)
+      UserContext.set(id: id, email: email, name: name, **custom)
+    end
+
+    def leave_breadcrumb(message, type: "manual", metadata: {})
+      BreadcrumbCollector.add(message, type: type, metadata: metadata)
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: bugwatch-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- BugWatch
+bindir: bin
+cert_chain: []
+date: 2026-04-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Automatically captures and reports exceptions from your Rails app to
+  BugWatch, with request context, user context, breadcrumbs, and source code snippets.
+email:
+- support@bugwatch.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/bugwatch.rb
+- lib/bugwatch/backtrace_cleaner.rb
+- lib/bugwatch/breadcrumb_collector.rb
+- lib/bugwatch/configuration.rb
+- lib/bugwatch/error_builder.rb
+- lib/bugwatch/middleware.rb
+- lib/bugwatch/notification.rb
+- lib/bugwatch/railtie.rb
+- lib/bugwatch/user_context.rb
+- lib/bugwatch/version.rb
+homepage: https://github.com/bugwatch/bugwatch-ruby
+licenses:
+- MIT
+metadata: {}
+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: 3.6.2
+specification_version: 4
+summary: Official Ruby/Rails SDK for BugWatch error monitoring
+test_files: []