findbug 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca9a3e20d87733caff1807d5b89935d349a316cddf15ee2e7565f3b861cafc10
-  data.tar.gz: d135aae0a004b454448d2688e04cf22f6121ed3d64b743baf7663466ef5894b0
+  metadata.gz: bc983a190a0ac08221e7bbaf108e52d55ecc20a28712f5bdf380acf61a27e43d
+  data.tar.gz: 77bc4565c0686c4d60646b4e7d9dc65f4faae482c83d8df6b98a4c02f540c162
 SHA512:
-  metadata.gz: 00d61fb0d96254b5195951d9c55a0c459f896ad61b3f813ed1fbeb817856b186ee8ceac24d5d659934e3909cfaa9bb901f38cd3fc3bc68e8aa5df4d7e04c3627
-  data.tar.gz: 01c241d176885ea96d700623048bf1f7d8af8832057b722b6d23c8a079dedc61410322abb897313a4e7a3d937a0ce6197c248b6438197725ab6656333f1dc311
+  metadata.gz: c6d0d26042c62b4ea65bd5f574e6c43d588fdfa83914b416a44638dae85c97d3fa12d74d4ffa6bb08b8575d96daa11ed87aeaefc314ee319353cb4acf961a0d6
+  data.tar.gz: 3d8ef1a2aece7c33efb7b629aa5b19013fe96da2b6ec3ec741eba8447b2fa80b36a5c3b6f1be926c4f19cda0ff44388eebc0a6eede1ce42d4e5fe199b448a5b2

data/README.md

@@ -8,16 +8,20 @@
 
 FindBug provides Sentry-like functionality with all data stored on your own infrastructure using Redis and your database. Zero external dependencies, full data ownership.
 
+📚 **Full documentation:** [findbug.dev/docs](https://findbug.dev/docs)
+
 ## Features
 
 - **Error Tracking** - Capture exceptions with full context, stack traces, and request data
 - **Performance Monitoring** - Track request timing, SQL queries, and automatic N+1 detection
-- **Self-Hosted** - All data stays on your infrastructure (Redis + PostgreSQL/MySQL)
+- **Self-Hosted** - All data stays on your infrastructure (Redis + your existing database)
+- **Database-Agnostic** - Works on PostgreSQL, MySQL, and SQLite — adapter detected automatically
 - **Zero Performance Impact** - Async writes via Redis buffer, never blocks your requests
 - **Built-in Dashboard** - Beautiful web UI for viewing errors and performance metrics
 - **Multi-channel Alerts** - Email, Slack, Discord, and custom webhooks
 - **Works Out of the Box** - Built-in background persister, no job scheduler required
 - **Rails 7+ Native** - Designed for modern Rails applications
+- **Tested** - Comprehensive RSpec suite covering every adapter path
 
 ## Why FindBug?
 
@@ -34,7 +38,7 @@ FindBug provides Sentry-like functionality with all data stored on your own infr
 - Ruby 3.1+
 - Rails 7.0+
 - Redis 4.0+
-- PostgreSQL or MySQL
+- A relational database — PostgreSQL, MySQL, or SQLite
 
 ## Installation
 
@@ -240,7 +244,7 @@ end
 │                                         └────────┬─────────┘   │
 │                                                  │              │
 │                                                  ▼              │
-│  Dashboard ◄──────────────────── Database (PostgreSQL/MySQL)   │
+│  Dashboard ◄──────────────────── Database (PostgreSQL/MySQL/SQLite) │
 │  (/findbug)                                                     │
 │                                                                 │
 └─────────────────────────────────────────────────────────────────┘
@@ -274,11 +278,44 @@ rails findbug:clear_buffers
 rails findbug:db:stats
 ```
 
-## Multi-Tenant Applications (Apartment/ros-apartment)
+## Database Support
+
+As of v0.5.0 FindBug is database-agnostic. The install generator's migrations and the model layer detect your `ActiveRecord::Base.connection.adapter_name` at runtime and pick the right column types and SQL functions automatically.
+
+| Adapter            | JSON column | Time bucketing SQL                 |
+|--------------------|-------------|------------------------------------|
+| PostgreSQL/PostGIS | `jsonb`     | `date_trunc(...)`                  |
+| MySQL/Mysql2       | `json`      | `DATE_FORMAT(...)` / `DATE(...)`   |
+| SQLite             | `text` (with JSON serialisation in the model) | `strftime(...)` / `DATE(...)` |
+
+The JSON accessors on the models normalise reads to a native Ruby `Hash` / `Array` regardless of the underlying column type, so your application code is identical across adapters.
+
+If you're writing your own migrations against the same multi-DB strategy, the `Findbug::AdapterHelper` module is part of the public API:
+
+```ruby
+Findbug::AdapterHelper.json_column_type      # :jsonb / :json / :text
+Findbug::AdapterHelper.json_default({})      # adapter-appropriate default
+Findbug::AdapterHelper.date_trunc_sql("hour", "captured_at")
+```
+
+## Multi-Tenant Applications
+
+Multi-tenant Rails apps are supported, but the setup depends on *how* your app isolates tenants. The matrix below shows what's possible per adapter:
+
+| Adapter                  | Tenancy model                                                | FindBug support                                                                  |
+|--------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------|
+| PostgreSQL               | Schema-per-tenant (Apartment's default)                      | ✅ First-class — keep FindBug tables in the `public` schema (see below).         |
+| PostgreSQL/MySQL/SQLite  | Row-level (`tenant_id` column)                               | ✅ Nothing special — FindBug's tables aren't tenant-scoped.                      |
+| MySQL                    | Database-per-tenant (Apartment with `use_schemas = false`)   | ⚠️ Doable but awkward — point FindBug at a separate connection via `connects_to`. |
+| SQLite                   | File-per-tenant                                              | ❌ Not practical — use row-level scoping instead.                                |
+
+For the full discussion (including MySQL setup options), see the [Multi-tenant section in the docs](https://findbug.dev/docs#multi-tenant).
+
+### PostgreSQL + Apartment (schema-per-tenant)
 
-If you're using [ros-apartment](https://github.com/rails-on-services/apartment) or similar multi-tenant gems with PostgreSQL schemas, FindBug's tables need to stay in the public schema and the dashboard path should be excluded from tenant switching.
+If you're using [ros-apartment](https://github.com/rails-on-services/apartment) with PostgreSQL schemas, FindBug's tables need to stay in the public schema and the dashboard path should be excluded from tenant switching.
 
-### 1. Exclude FindBug Models
+#### 1. Exclude FindBug Models
 
 Add FindBug models to the `excluded_models` list in `config/initializers/apartment.rb`:
 
@@ -293,7 +330,7 @@ Apartment.configure do |config|
 end
 ```
 
-### 2. Exclude FindBug Dashboard Path
+#### 2. Exclude FindBug Dashboard Path
 
 Add `/findbug` to your tenant switching middleware's excluded paths:
 
@@ -317,7 +354,7 @@ class SwitchTenantMiddleware < Apartment::Elevators::Generic
 end
 ```
 
-### 3. Run Migrations in Public Schema
+#### 3. Run Migrations in Public Schema
 
 Ensure FindBug migrations run in the public schema:
 

data/app/models/findbug/error_event.rb

@@ -27,14 +27,15 @@ module Findbug
   #     t.timestamps
   #   end
   #
-  # WHY JSONB FOR CONTEXT?
-  # ======================
+  # WHY OVERRIDE JSON ACCESSORS?
+  # =============================
   #
-  # Context is semi-structured - different errors have different context.
-  # JSONB (in PostgreSQL) or JSON (in other DBs) lets us store any shape
-  # of data without schema migrations.
+  # The column type for context/request_data varies by adapter:
+  #   PostgreSQL → jsonb  (AR returns Hash natively)
+  #   MySQL      → json   (AR returns Hash natively)
+  #   SQLite     → text   (AR returns raw JSON String)
   #
-  # For querying, we create GIN indexes on commonly queried paths.
+  # The overrides below normalise both cases so callers always get a Hash.
   #
   class ErrorEvent < ActiveRecord::Base
     self.table_name = "findbug_error_events"
@@ -55,6 +56,33 @@ module Findbug
     validates :status, inclusion: { in: [STATUS_UNRESOLVED, STATUS_RESOLVED, STATUS_IGNORED] }
     validates :severity, inclusion: { in: [SEVERITY_ERROR, SEVERITY_WARNING, SEVERITY_INFO] }
 
+    # JSON field accessors — normalise across adapters (jsonb/json/text).
+    # Reader always returns a Hash; writer stores a JSON string on text columns
+    # and the native object on json/jsonb columns.
+    %i[context request_data].each do |field|
+      define_method(field) do
+        val = read_attribute(field)
+        return {} if val.nil?
+        val.is_a?(String) ? JSON.parse(val) : val
+      rescue JSON::ParserError
+        {}
+      end
+
+      define_method(:"#{field}=") do |val|
+        col_type = self.class.columns_hash[field.to_s]&.type
+        if col_type == :text
+          serialized = case val
+                       when nil    then nil
+                       when String then val
+                       else             val.to_json
+                       end
+          write_attribute(field, serialized)
+        else
+          write_attribute(field, val)
+        end
+      end
+    end
+
     # Scopes
     scope :unresolved, -> { where(status: STATUS_UNRESOLVED) }
     scope :resolved, -> { where(status: STATUS_RESOLVED) }

data/app/models/findbug/performance_event.rb

@@ -17,11 +17,11 @@ module Findbug
   #     t.float :db_time_ms, default: 0
   #     t.float :view_time_ms, default: 0
   #     t.integer :query_count, default: 0
-  #     t.jsonb :slow_queries, default: []
-  #     t.jsonb :n_plus_one_queries, default: []
+  #     t.column :slow_queries, <json_type>, default: []
+  #     t.column :n_plus_one_queries, <json_type>, default: []
   #     t.boolean :has_n_plus_one, default: false
   #     t.integer :view_count, default: 0
-  #     t.jsonb :context, default: {}
+  #     t.column :context, <json_type>, default: {}
   #     t.string :environment
   #     t.string :release_version
   #     t.datetime :captured_at
@@ -48,6 +48,33 @@ module Findbug
     TYPE_CUSTOM = "custom"
     TYPE_JOB = "job"
 
+    # JSON field accessors — normalise across adapters (jsonb/json/text).
+    # Reader returns the native Array/Hash; writer serialises to JSON string
+    # for text columns and passes through to AR's type system otherwise.
+    { slow_queries: [], n_plus_one_queries: [], context: {} }.each do |field, empty|
+      define_method(field) do
+        val = read_attribute(field)
+        return empty.dup if val.nil?
+        val.is_a?(String) ? JSON.parse(val) : val
+      rescue JSON::ParserError
+        empty.dup
+      end
+
+      define_method(:"#{field}=") do |val|
+        col_type = self.class.columns_hash[field.to_s]&.type
+        if col_type == :text
+          serialized = case val
+                       when nil    then nil
+                       when String then val
+                       else             val.to_json
+                       end
+          write_attribute(field, serialized)
+        else
+          write_attribute(field, val)
+        end
+      end
+    end
+
     # Validations
     validates :transaction_name, presence: true
     validates :duration_ms, presence: true, numericality: { greater_than_or_equal_to: 0 }
@@ -181,28 +208,23 @@ module Findbug
     # @return [Array<Hash>] time series data
     #
     def self.throughput_over_time(since: 24.hours.ago, interval: "hour")
-      # This uses database-specific date truncation
-      # Works with PostgreSQL; adjust for other databases
-      time_column = case interval
-                    when "minute" then "date_trunc('minute', captured_at)"
-                    when "hour" then "date_trunc('hour', captured_at)"
-                    when "day" then "date_trunc('day', captured_at)"
-                    else "date_trunc('hour', captured_at)"
-                    end
+      time_sql = Findbug::AdapterHelper.date_trunc_sql(interval, "captured_at")
 
       where("captured_at >= ?", since)
-        .group(Arel.sql(time_column))
+        .group(Arel.sql(time_sql))
         .select(
-          Arel.sql("#{time_column} as time_bucket"),
+          Arel.sql("#{time_sql} as time_bucket"),
           "COUNT(*) as request_count",
           "AVG(duration_ms) as avg_duration"
         )
-        .order(Arel.sql(time_column))
+        .order(Arel.sql(time_sql))
         .map do |row|
+          time = row.time_bucket
+          time = Time.parse(time.to_s) unless time.respond_to?(:strftime)
           {
-            time: row.time_bucket,
+            time: time,
             count: row.request_count,
-            avg_duration_ms: row.avg_duration.round(2)
+            avg_duration_ms: row.avg_duration&.round(2) || 0
           }
         end
     end