railswatch_gem 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc820b02199b2d925bc18397d3cb039a3e9e332cd8e7ea668863144fc3a23452
+  data.tar.gz: a24e3915898b0365269ba6ef2291740b4625e34e4bd3f427e9c594e0dec089e2
+SHA512:
+  metadata.gz: bb6b2f5080c931110063a5bb83ab768263cb4da8cdcd73d8a4fdf49a967e5ec32be74f6410dd4bb520c18c3d58b88eda0e720b8dbbca3ae0de83baf52e1f7211
+  data.tar.gz: 745f55a53664c95d0ae86a415d58a02eaa47c0200db63e2cc101273db5b13c4ae31d40ea2d2ed4568c684429f494ca683866077c3d77825e140072af57b5aa06

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+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,130 @@
+# RailsWatch Gem
+
+RailsWatch is a lightweight, high-performance observability probe for Ruby on Rails applications. It captures requests, SQL queries, background jobs, logs, and exceptions in real-time and forwards them to your RailsWatch dashboard.
+
+Designed to be the Rails equivalent of Laravel Nightwatch/Telescope, it provides deep insight into your application's lifecycle without the overhead of heavy APM tools.
+
+## 🚀 Features
+
+- **Zero-Config**: Automatically hooks into Rails via ActiveSupport::Notifications.
+
+- **Full Lifecycle Tracking**:
+  - HTTP Requests (Headers, Session, Params)
+  - Database Queries (SQL, Duration)
+  - Background Jobs (Sidekiq, ActiveJob)
+  - Mail Deliveries
+  - Cache Hits/Misses (Redis, Memcached)
+  - Outgoing HTTP Requests (Net::HTTP)
+  - Rake Tasks & CLI Commands
+
+- **Active Debugging**: Includes a global `rw()` helper to dump variables to your dashboard instantly.
+
+- **Performance First**: Uses a background thread and buffered queue to ensure your application performance is never impacted by monitoring.
+
+- **Safe**: Handles thread-safety and swallows internal errors to prevent bringing down your app.
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'railswatch_gem'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## ⚙️ Configuration
+
+Create an initializer file at `config/initializers/railswatch.rb`. You will need your Project Token from your RailsWatch dashboard settings.
+
+```ruby
+# config/initializers/railswatch.rb
+
+RailswatchGem.configure do |config|
+  # The URL of your Railswatch SaaS instance (or self-hosted)
+  config.ingest_url = "https://api.railswatch.com/api/v1/ingest"
+
+  # Your unique Project Token
+  config.env_token  = ENV.fetch("RAILSWATCH_TOKEN", "your-project-token")
+
+  # Optional: Fine-tune performance
+  # config.batch_size = 100       # Max events to send in one HTTP request
+  # config.flush_interval = 2.0   # Send data every 2 seconds
+end
+```
+
+That's it! Restart your application, and data will start flowing to your dashboard.
+
+## 🛠 Usage
+
+### The rw() Helper
+
+Stop using `puts` or `binding.pry` in production. Use the global `rw()` helper (aliased as `railswatch_dump`) to send any variable directly to your "Dumps" dashboard tab.
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new(user_params)
+
+    # Inspect the user object in your dashboard without stopping the request
+    rw(@user)
+
+    if @user.save
+      # ...
+    end
+  end
+end
+```
+
+It returns the original object, so you can wrap expressions transparently:
+
+```ruby
+# The result is assigned to 'result' AND sent to the dashboard
+result = rw(ComplexCalculation.perform(x, y))
+```
+
+### Manual Logging
+
+RailsWatch automatically captures standard Rails.logger output. However, you can also manually record specific events if needed:
+
+```ruby
+RailswatchGem.record({
+  event_type: "custom_alert",
+  message: "Something interesting happened",
+  metadata: { user_id: 123 }
+})
+```
+
+## 🔒 Security
+
+- **Parameter Filtering**: RailsWatch respects your `Rails.application.config.filter_parameters`. Passwords and secrets defined there are scrubbed before leaving your server.
+
+- **Async Processing**: Data is buffered in memory and sent asynchronously. If the ingestion API is down, your app continues running smoothly.
+
+## 🧩 Supported Instrumenters
+
+RailsWatch automatically instruments the following libraries if they are loaded:
+
+| Instrumenter | Description |
+|-------------|-------------|
+| Requests | Controller actions, status codes, paths, IP addresses. |
+| Queries | ActiveRecord SQL queries (filters out SCHEMA/EXPLAIN). |
+| Jobs | ActiveJob & Sidekiq execution, latency, and retries. |
+| Mail | ActionMailer deliveries, recipients, and subjects. |
+| Cache | ActiveSupport::Cache reads, writes, and hit rates. |
+| Outbound | Net::HTTP requests to external APIs. |
+| Models | ActiveRecord Create/Update/Destroy events with changesets. |
+| Exceptions | Unhandled exceptions and Rails.error.report calls. |
+| Commands | Rake tasks and Thor CLI commands. |
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/railswatch_gem. This project is intended to be a safe, welcoming space for collaboration.
+
+## 📄 License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/railswatch_gem/client.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "thread"
+
+module RailswatchGem
+  class Client
+    # Maximum number of events to hold in memory before dropping to prevent OOM.
+    MAX_QUEUE_SIZE = 10_000
+
+    def initialize(ingest_url:, env_token:, batch_size:, flush_interval:, logger: nil)
+      @ingest_uri = URI(ingest_url)
+      @env_token = env_token
+      @batch_size = batch_size
+      @flush_interval = flush_interval
+      @logger = logger || default_logger
+
+      # Use SizedQueue for backpressure. If the consumer falls behind,
+      # we don't want to consume infinite memory.
+      @queue = SizedQueue.new(MAX_QUEUE_SIZE)
+
+      @running = true
+      start_worker_thread
+
+      # Ensure we flush on process exit
+      at_exit { stop_and_flush }
+    end
+
+    def record(event)
+      return unless @running
+
+      normalized = normalize_event(event)
+
+      # Non-blocking push. If queue is full, we drop the event to protect the app.
+      begin
+        @queue.push(normalized, true)
+      rescue ThreadError
+        # Queue is full. Log warning periodically or increment a metric.
+        # Avoid logging every failure to prevent disk fill-up.
+        log_error("RailswatchGem buffer full. Dropping event.")
+      end
+    end
+
+    def stop_and_flush
+      @running = false
+      flush
+    end
+
+    private
+
+    def normalize_event(event)
+      event = event.dup
+      event[:timestamp] ||= Time.now.utc.iso8601
+      event[:event_type] ||= "custom"
+      event
+    end
+
+    def start_worker_thread
+      @worker_thread = Thread.new do
+        while @running
+          # Wait for events or timeout (interval)
+          # We use a simple sleep loop here for simplicity,
+          # but a ConditionVariable could be used for smarter waking.
+          current_batch = []
+
+          # Drain queue up to batch size
+          while current_batch.size < @batch_size && !@queue.empty?
+            begin
+              current_batch << @queue.pop(true)
+            rescue ThreadError
+              break
+            end
+          end
+
+          if current_batch.any?
+            send_batch(current_batch)
+          else
+            # If no events, sleep to avoid hot loop
+            sleep @flush_interval
+          end
+        end
+
+        # Final flush on exit
+        flush_remaining
+      end
+
+      @worker_thread.name = "railswatch_gem_worker" if @worker_thread.respond_to?(:name=)
+    end
+
+    # Explicit flush (used at exit)
+    def flush
+      flush_remaining
+    end
+
+    def flush_remaining
+      all_events = []
+      loop do
+        begin
+          all_events << @queue.pop(true)
+        rescue ThreadError
+          break
+        end
+      end
+
+      # Send in chunks of batch_size
+      all_events.each_slice(@batch_size) do |batch|
+        send_batch(batch)
+      end
+    end
+
+    def send_batch(events)
+      # Using Net::HTTP.start with a block handles opening/closing cleanly.
+      # For higher performance, keep the connection open in an instance variable,
+      # but handle timeouts and reconnection logic.
+      Net::HTTP.start(@ingest_uri.host, @ingest_uri.port, use_ssl: @ingest_uri.scheme == "https") do |http|
+        request = Net::HTTP::Post.new(@ingest_uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["Environment-Token"] = @env_token
+        request.body = { events: events }.to_json
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess) || response.code.to_i == 202
+          log_error("RailswatchGem::Client#send_batch non-success: #{response.code} #{response.body}")
+        end
+      end
+    rescue => e
+      log_error("RailswatchGem::Client#send_batch failed: #{e.class} - #{e.message}")
+    end
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        Logger.new($stdout)
+      end
+    end
+
+    def log_error(message)
+      @logger&.error("[Railswatch] #{message}")
+    end
+  end
+end

data/lib/railswatch_gem/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  class Configuration
+    attr_accessor :env_token, :batch_size, :flush_interval, :ingest_url, :auto_boot
+    attr_reader :enabled_events, :custom_event_blocks
+
+    DEFAULT_EVENTS = %i[
+      requests
+      queries
+      outgoing_requests
+      jobs
+      scheduled_tasks
+      commands
+      cache
+      mail
+      notifications
+      logs
+      errors
+      models
+    ].freeze
+
+    DEFAULT_INGEST_URL = "https://api.railswatch.com/ingest".freeze
+
+    def initialize
+      @env_token = nil
+      @batch_size = 200
+      @flush_interval = 2.0
+      @ingest_url = DEFAULT_INGEST_URL
+      @auto_boot = true # Defaults to true for ease of use
+
+      # all default event families enabled
+      @enabled_events = DEFAULT_EVENTS.dup
+
+      # user-supplied instrumentation hooks
+      @custom_event_blocks = []
+    end
+
+    def enable_event(name)
+      name = name.to_sym
+      @enabled_events << name unless @enabled_events.include?(name)
+    end
+
+    def disable_event(name)
+      @enabled_events.delete(name.to_sym)
+    end
+
+    # for custom subscriptions using the client
+    def on_custom_event(&block)
+      @custom_event_blocks << block if block
+    end
+  end
+end

data/lib/railswatch_gem/helpers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  module Helpers
+    # Usage: rw(user, params) or railswatch_dump(variable)
+    def railswatch_dump(*args)
+      # 1. Capture the location where this was called (file:line)
+      call_site = caller(1, 1).first
+
+      # 2. Correlate with request if inside one
+      request_id = Thread.current[:railswatch_request_id]
+
+      # 3. Format the arguments for display
+      formatted_args = args.map do |arg|
+        format_dump_arg(arg)
+      end
+
+      payload = {
+        event_type: "dump",
+        timestamp: Time.now.utc.iso8601,
+        values: formatted_args,
+        location: call_site,
+        request_id: request_id
+      }
+
+      # Send to client
+      RailswatchGem.record(payload)
+
+      # 4. Return original args to allow debugging without breaking chains:
+      #    return rw(result)
+      if args.size == 1
+        args.first
+      else
+        args
+      end
+    rescue => e
+      warn "RailswatchGem: Dump failed: #{e.message}"
+      # Always return args so we don't break the app flow on error
+      args.size == 1 ? args.first : args
+    end
+
+    # Short alias for ease of use
+    alias_method :rw, :railswatch_dump
+
+    private
+
+    def format_dump_arg(arg)
+      case arg
+      when Hash
+        # Attempt to keep hashes as structures for the JSON viewer in the dashboard
+        begin
+          arg.transform_keys(&:to_s)
+        rescue
+          arg.inspect
+        end
+      when Array
+        arg.map { |item| format_dump_arg(item) }
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        arg
+      else
+        # For Active Record models or complex objects, .inspect gives the string representation
+        # which is usually what developers want to see.
+        arg.inspect
+      end
+    end
+  end
+end
+
+# Automatically mix into the top-level Object so it's available everywhere
+# (Models, Controllers, Views, Console, Irb)
+Object.include(RailswatchGem::Helpers) if defined?(Object)

data/lib/railswatch_gem/instrumentation/cache_instrumenter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class CacheInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Subscribe to all cache events (read, write, delete, fetch_hit, generate, etc.)
+        ActiveSupport::Notifications.subscribe(/cache_.*\.active_support/) do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+        name = event.name # e.g., "cache_read.active_support"
+
+        # Extract action from name: cache_read.active_support -> read
+        # Common actions: read, write, delete, fetch_hit, generate
+        action = name.split(".").first.sub("cache_", "")
+
+        data = {
+          event_type: "cache",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+          action: action,
+          key: payload[:key],
+
+          # Performance
+          duration_ms: event.duration.round(2)
+        }
+
+        # 'hit' is often present on read/fetch operations (true/false)
+        if payload.key?(:hit)
+          data[:hit] = payload[:hit]
+        end
+
+        # 'super_operation' exists in Rails 6.1+ for nested fetch calls
+        if payload[:super_operation]
+          data[:super_operation] = payload[:super_operation].to_s
+        end
+
+        # Error handling
+        if payload[:exception]
+          data[:error_class] = payload[:exception].first.to_s
+          data[:error_message] = payload[:exception].last.to_s
+        end
+
+        @client.record(data)
+      rescue => e
+        warn "RailswatchGem: Failed to process cache event: #{e.message}"
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/commands_instrumenter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class CommandsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Hook into Thor to capture CLI commands (e.g., rails runner, rails generate, custom CLI tools)
+        if defined?(::Thor::Command)
+          patch_thor_commands
+
+          ActiveSupport::Notifications.subscribe("command.thor") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            process_event(event)
+          end
+        end
+      end
+
+      private
+
+      def patch_thor_commands
+        # Ensure we only patch once
+        return if ::Thor::Command.include?(ThorCommandPatch)
+
+        ::Thor::Command.prepend(ThorCommandPatch)
+      end
+
+      def process_event(event)
+        payload = event.payload
+        command_name = payload[:name]
+
+        data = {
+          event_type: "command",
+          # FIX: Handle Float timestamps safely using Time.at()
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Command Identity
+          name: command_name,
+          args: payload[:args],
+          options: payload[:options],
+
+          # Context (Optional: class name of the tool running, e.g., 'Rails::Generators::ModelGenerator')
+          tool: payload[:tool_class],
+
+          # Performance
+          duration_ms: event.duration.round(2)
+        }
+
+        # Error handling
+        if payload[:exception]
+          data[:error_class] = payload[:exception].first.to_s
+          data[:error_message] = payload[:exception].last.to_s
+          data[:status] = "failed"
+        else
+          data[:status] = "success"
+        end
+
+        @client.record(data)
+      rescue => e
+        warn "RailswatchGem: Failed to process command event: #{e.message}"
+      end
+
+      # ----------------------------------------------------------------
+      # Internal Patch for Thor::Command
+      # ----------------------------------------------------------------
+      module ThorCommandPatch
+        def run(instance, args = [])
+          # Thor::Command#run(instance, args)
+          # 'name' is available on the command object
+
+          # Capture options if available on the instance (parsed flags)
+          opts = instance.respond_to?(:options) ? instance.options : nil
+          tool_class = instance.class.name
+
+          ActiveSupport::Notifications.instrument("command.thor", {
+            name: name,
+            args: args,
+            options: opts,
+            tool_class: tool_class
+          }) do
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/errors_instrumenter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  module Instrumentation
+    class ErrorsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # This instrumenter relies on the Rails 7.0+ Error Reporter interface.
+        # It allows capturing both unhandled exceptions and manually reported errors
+        # (e.g., via Rails.error.handle { ... }).
+        if defined?(::Rails) && ::Rails.respond_to?(:error)
+          ::Rails.error.subscribe(ErrorSubscriber.new(@client))
+        end
+      end
+
+      class ErrorSubscriber
+        def initialize(client)
+          @client = client
+        end
+
+        # The signature required by Rails.error.subscribe
+        def report(error, handled:, severity:, context:, source: nil)
+          # 1. Infinite Loop Protection:
+          # Don't report errors originating from our own gem to prevent recursion.
+          return if error.class.name.start_with?("RailswatchGem::")
+
+          # 2. Context Correlation:
+          # Try to link this error to the current HTTP request if possible.
+          # We check the passed context first, then fall back to our thread-local storage.
+          request_id = context[:request_id] || Thread.current[:railswatch_request_id]
+
+          data = {
+            event_type: "error",
+            timestamp: Time.now.utc.iso8601,
+
+            # Exception Details
+            class: error.class.name,
+            message: error.message,
+            # Limit backtrace to save bandwidth; the dashboard usually only needs the top frames.
+            backtrace: (error.backtrace || []).first(25),
+
+            # Rails Error Reporter Context
+            handled: handled,
+            severity: severity,
+            source: source, # e.g., "application.job"
+
+            # Correlation
+            request_id: request_id,
+
+            # Extra context passed to Rails.error.report(e, context: { user_id: 1 })
+            context: context
+          }
+
+          @client.record(data)
+        rescue => e
+          # Absolute safety net: If reporting the error fails, print to stderr and move on.
+          warn "RailswatchGem: Failed to report error event: #{e.message}"
+        end
+      end
+    end
+  end
+end