railscope 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 259570e86e958b91b577337b9b1dd6f57f667f72999589a3976b9a86a3450c78
-  data.tar.gz: bbf6d0de9fdce6901383c8d60c39c07310a3da0d64593904d55a85412deba2b1
+  metadata.gz: c7b44de114284ee8955d48c35c4966b45e8b798b1624d6a8abefb2212b9e4cd5
+  data.tar.gz: 44ba0061f1987733edf5a5dde93ce591fc9eb2ff63f3aae59854051313b59d84
 SHA512:
-  metadata.gz: 2d358d6d57809e3b6d30bebfab973060d8c3086a929c8d47dd3fc230be5ad72f0cca7ed84f0431466b80f3b5d863e8f1d37c0d26eb6df14301d7ef307fcc05a5
-  data.tar.gz: 41b79ac66a21145f5ca9fe18a07a6706bf06751a87eb26bd1739a816526d7e851c43d784146cb2bf6391ce47e7e73bbfe91443e883e8f868d45a039e30b66dec
+  metadata.gz: 3b054e8e101d09dcd88c954eaf82452c9e18629398eb2270d2eddcd89769562eac8325a0c55c77505d5a1f2ecf5f2c7fa644d65e9eec318045c37832dbc3d92f
+  data.tar.gz: 9c7feb08613c99ef5fb206170dedb9e841a846e6d7077f4e06c8fa0673f19764f0ea5acff74da590e4879f7e78cb72213b9ceea35e76990f6b38e1aebabef26f

data/README.md

@@ -65,6 +65,15 @@ Railscope.configure do |config|
   # Paths to ignore (defaults: /railscope, /assets, /packs, /cable)
   config.add_ignore_paths("/health", "/ping", "/metrics")
 
+  # Jobs to ignore (class names or regex patterns)
+  config.add_ignore_jobs("SomeFrequentJob", "Turbo::Streams::.*")
+
+  # Rake tasks to ignore (task names or regex patterns)
+  config.add_ignore_commands("db:.*", "assets:.*", "tmp:.*")
+
+  # Use an existing Redis connection (useful for SSL/connection sharing)
+  # config.redis = $redis
+
   # Additional sensitive keys to filter
   config.add_sensitive_keys(:cpf, :ssn, :bank_account)
 end
@@ -208,6 +217,51 @@ Railscope::PurgeJob.perform_now
 Railscope::PurgeJob.perform_later
 ```
 
+## Filtering Entries
+
+### Ignore Paths
+
+Requests matching these path prefixes will not be recorded:
+
+```ruby
+# Defaults: /railscope, /assets, /packs, /cable
+config.add_ignore_paths("/health", "/ping", "/metrics", "/up")
+```
+
+### Ignore Jobs
+
+Background jobs matching these patterns will not be recorded (enqueue, perform, or exceptions). Accepts exact class names or regex patterns:
+
+```ruby
+# Exact match
+config.add_ignore_jobs("HeartbeatJob")
+
+# Regex patterns
+config.add_ignore_jobs("SolidQueue::.*", "Turbo::Streams::.*", "ActionMailbox::.*")
+```
+
+### Ignore Commands
+
+Rake tasks matching these patterns will not be instrumented. Accepts exact task names or regex patterns:
+
+```ruby
+# Exact match
+config.add_ignore_commands("db:migrate")
+
+# Regex patterns — ignore entire namespaces
+config.add_ignore_commands("db:.*", "assets:.*", "tmp:.*", "log:.*")
+```
+
+### Custom Redis Connection
+
+By default, Railscope creates its own Redis connection from `RAILSCOPE_REDIS_URL` or `REDIS_URL`. If your app already has a configured Redis instance (e.g., with SSL on Heroku), you can pass it directly:
+
+```ruby
+config.redis = $redis
+```
+
+This avoids SSL certificate issues and shares the existing connection configuration.
+
 ## Filtered Parameters
 
 Railscope automatically filters sensitive data:
@@ -279,8 +333,11 @@ Railscope is designed to have minimal impact:
 For high-traffic production environments, consider:
 - Using `:redis` backend for lower request latency
 - Shorter retention periods
-- Adding high-traffic paths to ignore list
+- Ignoring noisy paths (`/health`, `/ping`, polling endpoints)
+- Ignoring high-frequency jobs (`SolidQueue::.*`, `Turbo::Streams::.*`)
+- Ignoring routine rake tasks (`db:.*`, `assets:.*`)
 - Running purge job more frequently
+- Using `config.redis = $redis` to share the app's existing Redis connection
 
 ## License
 

data/lib/generators/railscope/templates/initializer.rb

@@ -49,6 +49,28 @@ Railscope.configure do |config|
   #
   # config.add_ignore_paths("/health", "/ping", "/metrics")
 
+  # Ignored Jobs
+  # ------------
+  # Jobs matching these patterns will not be recorded.
+  # Accepts class names or regex patterns.
+  #
+  # config.add_ignore_jobs("SomeFrequentJob", "Turbo::Streams::.*")
+
+  # Ignored Commands
+  # ----------------
+  # Rake tasks matching these patterns will not be recorded.
+  # Accepts task names or regex patterns.
+  #
+  # config.add_ignore_commands("db:.*", "assets:.*", "tmp:.*")
+
+  # Redis Connection
+  # ----------------
+  # By default, Railscope creates its own Redis connection from
+  # RAILSCOPE_REDIS_URL or REDIS_URL. You can pass an existing
+  # Redis instance instead (useful for SSL/connection sharing):
+  #
+  # config.redis = $redis
+
   # Sensitive Keys
   # --------------
   # Additional parameter names to filter from payloads.

data/lib/railscope/context.rb

@@ -87,5 +87,30 @@ module Railscope
     end
 
     delegate :empty?, to: :@store
+
+    # Conditional recording: buffer entries until a trigger fires
+
+    def pending_entries
+      self[:pending_entries] ||= []
+    end
+
+    def triggered?
+      self[:triggered] == true
+    end
+
+    def trigger!
+      self[:triggered] = true
+    end
+
+    def buffer_entry(entry_data)
+      pending_entries << entry_data
+    end
+
+    def flush_pending!
+      pending_entries.each do |entry_data|
+        Railscope.storage.write(**entry_data)
+      end
+      pending_entries.clear
+    end
   end
 end

data/lib/railscope/middleware.rb

@@ -18,17 +18,20 @@ module Railscope
       # Capture response body for recording
       context = Context.current
       if context[:recording]
-        # Read body from env (where Rails stores the response)
-        body_content = extract_body_from_env(env)
-
-        context_data = {
-          batch_id: context.batch_id,
-          env: env,
-          headers: headers
-        }
-
-        # Update entry with response data
-        update_entry_async(context_data, body_content)
+        # In conditional mode, skip persistence if trigger never fired
+        unless Railscope.conditional_recording? && !context.triggered?
+          # Read body from env (where Rails stores the response)
+          body_content = extract_body_from_env(env)
+
+          context_data = {
+            batch_id: context.batch_id,
+            env: env,
+            headers: headers
+          }
+
+          # Update entry with response data
+          update_entry_async(context_data, body_content)
+        end
       end
 
       [status, headers, response]

data/lib/railscope/subscribers/base_subscriber.rb

@@ -29,7 +29,7 @@ module Railscope
 
         filtered_payload = Railscope.filter(payload.merge(context_payload))
 
-        Railscope.storage.write(
+        entry_data = {
           entry_type: entry_type,
           batch_id: context.batch_id,
           family_hash: family_hash,
@@ -37,7 +37,13 @@ module Railscope
           payload: filtered_payload,
           tags: (tags + context_tags).uniq,
           occurred_at: Time.current
-        )
+        }
+
+        if Railscope.conditional_recording? && !context.triggered?
+          context.buffer_entry(entry_data)
+        else
+          Railscope.storage.write(**entry_data)
+        end
       end
 
       # Generate a family hash for grouping similar entries

data/lib/railscope/subscribers/command_subscriber.rb

@@ -23,6 +23,7 @@ module Railscope
 
         def instrument_task(task)
           return if task.name.start_with?("railscope:")
+          return if Railscope.ignore_command?(task.name)
           return if instrumented_tasks.include?(task.name)
 
           instrumented_tasks << task.name

data/lib/railscope/subscribers/job_subscriber.rb

@@ -76,7 +76,12 @@ module Railscope
         # Also create a separate exception entry if job failed
         create_exception_entry!(job, exception_object) if exception_object
 
-        # Clear context after job completes
+        # In conditional mode: flush if triggered, otherwise entries are discarded with context
+        if Railscope.conditional_recording? && context.triggered?
+          # Response update for jobs is already in the entry payload, nothing extra needed
+        end
+
+        # Clear context after job completes (discards any unflushed buffer)
         Railscope::Context.clear!
       rescue StandardError => e
         Rails.logger.error("[Railscope] Failed to record job perform: #{e.message}")
@@ -199,7 +204,7 @@ module Railscope
       end
 
       def ignore_job?(job)
-        job.class.name.start_with?("Railscope::")
+        job.class.name.start_with?("Railscope::") || Railscope.ignore_job?(job.class.name)
       end
 
       def setup_job_context(job)

data/lib/railscope/subscribers/model_subscriber.rb

@@ -42,6 +42,7 @@ module Railscope
         model_name = model.class.name
         return if model_name.nil?
         return if IGNORED_MODEL_PREFIXES.any? { |prefix| model_name.start_with?(prefix) }
+        return unless Railscope.should_track_model?(model_name)
 
         create_entry!(
           entry_type: "model",
@@ -50,6 +51,13 @@ module Railscope
           family_hash: build_family_hash(action, model),
           should_display_on_index: true
         )
+
+        # Conditional recording: flush buffered entries when trigger matches
+        if Railscope.conditional_recording? && !context.triggered? && Railscope.matches_trigger?(model_name, action)
+          context.trigger!
+          context.flush_pending!
+        end
+
         Rails.logger.debug("[Railscope] ModelSubscriber - entry created for #{model_name}")
       rescue StandardError => e
         Rails.logger.error("[Railscope] Failed to record model event: #{e.class}: #{e.message}")

data/lib/railscope/version.rb

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

data/lib/railscope.rb

@@ -27,7 +27,8 @@ module Railscope
   STORAGE_REDIS = :redis
 
   class << self
-    attr_writer :retention_days, :redis, :storage_backend, :ignore_paths
+    attr_writer :retention_days, :redis, :storage_backend, :ignore_paths, :ignore_jobs, :ignore_commands,
+                :ignore_models
     attr_accessor :authenticate_with
 
     def enabled=(value)
@@ -99,6 +100,67 @@ module Railscope
       @ignore_paths = ignore_paths.concat(paths.flatten).uniq
     end
 
+    def ignore_jobs
+      @ignore_jobs ||= []
+    end
+
+    def add_ignore_jobs(*job_classes)
+      @ignore_jobs = ignore_jobs.concat(job_classes.flatten.map(&:to_s)).uniq
+    end
+
+    def ignore_job?(job_class_name)
+      ignore_jobs.any? { |pattern| job_class_name.match?(pattern) }
+    end
+
+    def ignore_commands
+      @ignore_commands ||= []
+    end
+
+    def add_ignore_commands(*commands)
+      @ignore_commands = ignore_commands.concat(commands.flatten.map(&:to_s)).uniq
+    end
+
+    def ignore_command?(command_name)
+      ignore_commands.any? { |pattern| command_name.match?(pattern) }
+    end
+
+    # Model filtering (blocklist)
+
+    def ignore_models
+      @ignore_models ||= []
+    end
+
+    def add_ignore_models(*model_names)
+      @ignore_models = ignore_models.concat(model_names.flatten.map(&:to_s)).uniq
+    end
+
+    def should_track_model?(model_name)
+      return false if model_name.nil?
+
+      ignore_models.none? { |pattern| model_name.match?(pattern) }
+    end
+
+    # Conditional recording: only persist a batch when a watched model event fires
+
+    def watch_triggers
+      @watch_triggers ||= []
+    end
+
+    def add_watch_trigger(model_name, on:)
+      actions = Array(on).map(&:to_s)
+      @watch_triggers = watch_triggers.push({ model: model_name.to_s, on: actions }).uniq
+    end
+
+    def conditional_recording?
+      watch_triggers.any?
+    end
+
+    def matches_trigger?(model_name, action)
+      watch_triggers.any? do |trigger|
+        model_name.match?(trigger[:model]) && trigger[:on].include?(action.to_s)
+      end
+    end
+
     def context
       Context.current
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: railscope
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Phelipe Tussolini
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -155,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A debug assistant for Rails applications inspired by Laravel Telescope
 test_files: []