railscope 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 365fa77a20cf2375e26da9f92c52dae76d20ff8cce31a793f921e7e392208149
-  data.tar.gz: 838667bc52bf55f90c2372d713d4677407675f2ec8b27cdcc460eb701ea89931
+  metadata.gz: 407d8ab344bde0dfb68984086462f3aef07114a6d372ce5f6a2a4fb4ca4c5fd1
+  data.tar.gz: 1dff09145783ff05482bf3d9d118401d325d2373e0bdc8fa3a1ae74885713623
 SHA512:
-  metadata.gz: 25d34d2449ae7cd8c9b0940438a93de8357cb4f5a73b85fab3f762bbd46cb0a41f87e905c474d467b15330f83ce7c35f3e7d9adbaf4a3bd88a8f0c0f8ee683b1
-  data.tar.gz: 392dfb08fe6a2fbda012364e0a0e705a913337626e4fef890deb1bff469cb009ee68e8bb851988e8814a7e7f578cd04df6295e0f821dd5364205b337af2c30b8
+  metadata.gz: 3283c7964a1b56b8b89ee354204394d8d5aff9b1d0d7c36d49e2ed45d1d3a0c0382da567e869b9b3b836fbf4a4d9c261beed24efee8931f96e529e8e04d329e0
+  data.tar.gz: 8ef7eaf49c58775642fa9c0cb8a05c451d7f9e07b87315dbdb5c5990eed590c2d66a8d889b40feef213c97cf0ebb6f18edd3606fcc9215dde30e5ae578a43905

data/README.md

@@ -13,7 +13,8 @@ Railscope provides insight into the requests, exceptions, database queries, jobs
 - **Context Correlation** - Link all events from the same request via `request_id`
 - **Sensitive Data Filtering** - Automatic masking of passwords, tokens, and secrets
 - **Dark Mode UI** - Beautiful GitHub-inspired dark interface
-- **Zero Dependencies** - Works with any Rails 7+ application
+- **Storage Backends** - Direct database writes or Redis buffer with batch flush
+- **Zero Dependencies** - Works with any Rails 7+ application (Redis optional)
 
 ## Installation
 
@@ -55,6 +56,9 @@ Create `config/initializers/railscope.rb`:
 
 ```ruby
 Railscope.configure do |config|
+  # Storage backend: :database (default) or :redis (buffer)
+  config.storage_backend = :database
+
   # Data retention (default: 7 days)
   config.retention_days = 30
 
@@ -66,11 +70,49 @@ Railscope.configure do |config|
 end
 ```
 
+### Storage Backends
+
+Railscope supports two storage modes:
+
+| Mode | Write | Read | Requires |
+|------|-------|------|----------|
+| `:database` | Direct INSERT (sync) | PostgreSQL | PostgreSQL |
+| `:redis` | Redis buffer (async) | PostgreSQL | PostgreSQL + Redis |
+
+**`:database`** (default) -- Entries are written directly to PostgreSQL during the request. Simplest setup, no Redis needed.
+
+**`:redis`** -- Entries are buffered in Redis (~0.1ms per write) and batch-flushed to PostgreSQL periodically. Reduces request latency in high-throughput applications.
+
+When using `:redis`, you need to flush the buffer periodically:
+
+```ruby
+# From a background job (Sidekiq, GoodJob, SolidQueue, etc.)
+class RailscopeFlushJob < ApplicationJob
+  queue_as :low
+
+  def perform
+    Railscope::FlushService.call
+  end
+end
+
+# From a cron/scheduler
+every 5.seconds do
+  runner "Railscope::FlushService.call"
+end
+
+# Or via rake
+# $ rake railscope:flush
+```
+
+> **Note:** Entries only appear in the dashboard after being flushed to PostgreSQL.
+
 ### Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `RAILSCOPE_ENABLED` | Enable/disable recording | `false` |
+| `RAILSCOPE_STORAGE` | Storage backend (`database` or `redis`) | `database` |
+| `RAILSCOPE_REDIS_URL` | Redis connection URL | Falls back to `REDIS_URL` |
 | `RAILSCOPE_RETENTION_DAYS` | Days to keep entries | `7` |
 
 ## Authorization
@@ -144,6 +186,16 @@ Entries are automatically tagged:
 - **Exceptions**: `exception`, exception class name
 - **Jobs**: `job`, `enqueue`/`perform`, queue name, `failed`
 
+### Rake Tasks
+
+```bash
+# Flush buffered entries from Redis to database (redis mode only)
+rake railscope:flush
+
+# Purge expired entries (older than retention_days)
+rake railscope:purge
+```
+
 ### Purging Old Entries
 
 Run the purge job to remove entries older than `retention_days`:
@@ -212,12 +264,20 @@ Railscope::Entry.expired
 
 Railscope is designed to have minimal impact:
 
-- Events are recorded synchronously but quickly
 - Ignored paths skip all processing
 - Sensitive data filtering is done once before save
 - Purge job removes old entries to control database size
 
+**With `:database` backend:**
+- Entries are written synchronously via INSERT during the request
+
+**With `:redis` backend:**
+- Writes go to Redis (~0.1ms per entry), near-zero impact on request latency
+- `Entry.insert_all` batches up to 1000 records per flush for efficient persistence
+- Flush is safe to run concurrently (Redis `LPOP` is atomic)
+
 For high-traffic production environments, consider:
+- Using `:redis` backend for lower request latency
 - Shorter retention periods
 - Adding high-traffic paths to ignore list
 - Running purge job more frequently

data/app/models/railscope/application_record.rb

@@ -4,9 +4,30 @@ module Railscope
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
 
-    # Support for separate database connection when RAILSCOPE_DATABASE_URL is configured
-    # This isolates Railscope's writes from the main application database,
-    # preventing lock contention during high-traffic periods.
-    connects_to database: { writing: :railscope, reading: :railscope } if ENV["RAILSCOPE_DATABASE_URL"].present?
+    # Support for separate database connection.
+    # Activated when a "railscope" database is defined in database.yml
+    # or when RAILSCOPE_DATABASE_URL is set.
+    #
+    # Example database.yml:
+    #   development:
+    #     primary:
+    #       <<: *default
+    #       database: myapp_development
+    #       migrations_paths: db/migrate
+    #     railscope:
+    #       <<: *default
+    #       database: myapp_railscope_development
+    #       migrations_paths: db/railscope_migrate
+    #
+    def self.railscope_separate_database?
+      return true if ENV["RAILSCOPE_DATABASE_URL"].present?
+
+      configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+      configs.any? { |c| c.name == "railscope" }
+    rescue StandardError
+      false
+    end
+
+    connects_to database: { writing: :railscope, reading: :railscope } if railscope_separate_database?
   end
 end

data/lib/railscope/engine.rb

@@ -29,8 +29,23 @@ module Railscope
 
     initializer "railscope.migrations" do |app|
       unless app.root.to_s.match?(root.to_s)
-        config.paths["db/migrate"].expanded.each do |expanded_path|
-          app.config.paths["db/migrate"] << expanded_path
+        if railscope_separate_database?
+          # Separate database: copy migrations to db/railscope_migrate/
+          # so they only run against the railscope database
+          target_dir = app.root.join("db", "railscope_migrate")
+          config.paths["db/migrate"].expanded.each do |source_dir|
+            Dir[File.join(source_dir, "*.rb")].each do |migration|
+              target = target_dir.join(File.basename(migration))
+              next if target.exist?
+
+              FileUtils.mkdir_p(target_dir)
+              FileUtils.cp(migration, target)
+            end
+          end
+        else
+          config.paths["db/migrate"].expanded.each do |expanded_path|
+            app.config.paths["db/migrate"] << expanded_path
+          end
         end
       end
     end
@@ -84,5 +99,14 @@ module Railscope
       # Subscribe to rake tasks after they're loaded
       Railscope::Subscribers::CommandSubscriber.subscribe
     end
+
+    private
+
+    def railscope_separate_database?
+      configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env)
+      configs.any? { |c| c.name == "railscope" }
+    rescue StandardError
+      false
+    end
   end
 end

data/lib/railscope/storage/redis_buffer.rb

@@ -5,11 +5,13 @@ module Railscope
     class RedisBuffer < Base
       BUFFER_KEY = "railscope:buffer"
       UPDATES_KEY = "railscope:buffer:updates"
+      BUFFER_TTL = 4.hours.to_i
 
       # WRITE → Redis (fast, ~0.1ms)
       def write(attributes)
         entry = build_entry(attributes)
         redis.rpush(BUFFER_KEY, entry.to_json)
+        redis.expire(BUFFER_KEY, BUFFER_TTL)
         entry
       end
 
@@ -21,6 +23,7 @@ module Railscope
           payload_updates: payload_updates
         }
         redis.rpush(UPDATES_KEY, update.to_json)
+        redis.expire(UPDATES_KEY, BUFFER_TTL)
       end
 
       # READ → Database (source of truth)

data/lib/railscope/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railscope
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railscope
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Phelipe Tussolini