railswatch_gem 0.1.0

data/lib/railswatch_gem/instrumentation/requests_instrumenter.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class RequestsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Subscribe to the standard Rails controller event.
+        # This event includes details like status, path, duration, and DB runtime.
+        ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+
+        # Retrieve request ID for correlation
+        request_id = payload[:request_id] || Thread.current[:railswatch_request_id]
+
+        # Filter parameters to prevent PII leakage
+        raw_params = payload[:params] || {}
+        safe_params = filter_parameters(raw_params)
+
+        # Extract extra context (Headers, Session, User)
+        headers_obj = payload[:headers]
+
+        safe_headers = extract_headers(headers_obj)
+        safe_session = extract_session(headers_obj)
+        user_info    = extract_user(headers_obj)
+
+        data = {
+          event_type: "request",
+          # Fix: Ensure timestamp is a Time object before calling utc
+          timestamp: Time.at(event.end).utc.iso8601,
+          request_id: request_id,
+
+          # HTTP Context
+          method: payload[:method],
+          path: payload[:path],
+          status: payload[:status] || 500,
+          format: payload[:format].to_s,
+
+          # Inputs & State
+          params: safe_params,
+          headers: safe_headers,
+          session: safe_session,
+          user: user_info,
+
+          # Rails Context
+          controller: payload[:controller],
+          action: payload[:action],
+
+          # Performance Metrics
+          duration_ms: event.duration.round(2),
+          view_runtime_ms: payload[:view_runtime]&.round(2),
+          db_runtime_ms: payload[:db_runtime]&.round(2),
+          allocations: event.allocations
+        }
+
+        # Capture Exception Details if the request failed
+        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 request event: #{e.message}"
+      end
+
+      # --- Extraction Helpers ---
+
+      def extract_headers(headers)
+        return {} unless headers.respond_to?(:env)
+
+        interesting_headers = %w[
+          CONTENT_TYPE CONTENT_LENGTH
+          HTTP_AUTHORIZATION HTTP_USER_AGENT HTTP_REFERER HTTP_ACCEPT
+          HTTP_X_REQUEST_ID HTTP_X_FORWARDED_FOR
+        ]
+
+        headers.env.select { |k, _| interesting_headers.include?(k) }.transform_keys do |k|
+          k.sub(/^HTTP_/, "").split("_").map(&:capitalize).join("-")
+        end
+      end
+
+      def extract_session(headers)
+        return {} unless headers.respond_to?(:env)
+
+        raw_session = headers.env["rack.session"]
+        return {} unless raw_session
+
+        session_hash = raw_session.to_hash
+        filter_parameters(session_hash)
+      rescue
+        { error: "Could not serialize session" }
+      end
+
+      def extract_user(headers)
+        return nil unless headers.respond_to?(:env)
+
+        warden = headers.env["warden"]
+        if warden && warden.user
+          user = warden.user
+          {
+            id: user.respond_to?(:id) ? user.id : nil,
+            email: user.respond_to?(:email) ? user.email : nil,
+            class: user.class.name
+          }
+        else
+          nil
+        end
+      rescue
+        nil
+      end
+
+      def filter_parameters(params)
+        if defined?(::ActiveSupport::ParameterFilter) && defined?(::Rails.application)
+          filter = ::ActiveSupport::ParameterFilter.new(::Rails.application.config.filter_parameters)
+          return filter.filter(params)
+        end
+
+        if defined?(::ActionDispatch::Http::ParameterFilter) && defined?(::Rails.application)
+          filter = ::ActionDispatch::Http::ParameterFilter.new(::Rails.application.config.filter_parameters)
+          return filter.filter(params)
+        end
+
+        sensitive = %w[password password_confirmation token secret credit_card]
+        params.select { |k, _v| !sensitive.include?(k.to_s) }
+      rescue
+        { error: "Could not filter parameters" }
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/scheduled_tasks_instrumenter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class ScheduledTasksInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Only instrument Rake if it is loaded.
+        # This prevents errors if the gem is used in a context where Rake isn't present.
+        if defined?(::Rake::Task)
+          patch_rake_tasks
+
+          ActiveSupport::Notifications.subscribe("task.rake") do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            process_event(event)
+          end
+        end
+      end
+
+      private
+
+      def patch_rake_tasks
+        # Ensure we only patch once
+        return if ::Rake::Task.include?(RakeTaskPatch)
+
+        ::Rake::Task.prepend(RakeTaskPatch)
+      end
+
+      def process_event(event)
+        payload = event.payload
+        task_name = payload[:name]
+
+        # Optional: Ignore internal Railswatch tasks to prevent noise
+        return if task_name.to_s.start_with?("railswatch:")
+
+        data = {
+          event_type: "scheduled_task",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Task Identity
+          name: task_name,
+          args: payload[:args].to_a, # Rake args come as a wrapper, convert to array
+
+          # 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 scheduled task event: #{e.message}"
+      end
+
+      # ----------------------------------------------------------------
+      # Internal Patch for Rake::Task
+      # ----------------------------------------------------------------
+      module RakeTaskPatch
+        def execute(args = nil)
+          # We explicitly capture 'name' here because it's available on the task instance
+          ActiveSupport::Notifications.instrument("task.rake", { name: name, args: args }) do
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/middleware/request_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RailswatchGem
+  module Middleware
+    class RequestContext
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # 1. Try ActionDispatch's ID (standard Rails)
+        # 2. Try HTTP header (load balancers)
+        # 3. Fallback to random UUID
+        req_id = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"] || SecureRandom.uuid
+
+        # Store in thread local so LogsInstrumenter can read it deeper in the stack
+        Thread.current[:railswatch_request_id] = req_id
+
+        @app.call(env)
+      ensure
+        # Clean up to prevent leakage between requests in threaded web servers (Puma/Unicorn)
+        Thread.current[:railswatch_request_id] = nil
+      end
+    end
+  end
+end

data/lib/railswatch_gem/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "middleware/request_context"
+
+module RailswatchGem
+  class Railtie < ::Rails::Railtie
+    # Insert our middleware at the very top (index 0) to ensure we catch everything,
+    # including potential errors in other middlewares.
+    initializer "railswatch.middleware" do |app|
+      app.middleware.insert_before 0, RailswatchGem::Middleware::RequestContext
+    end
+
+    # Automatically boot the instrumentation when Rails finishes initializing.
+    config.after_initialize do
+      # Only boot if the user hasn't disabled auto_boot in their config
+      if RailswatchGem.configuration.auto_boot
+        RailswatchGem.boot!
+      end
+    end
+  end
+end

data/lib/railswatch_gem/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  VERSION = "0.1.0"
+end

data/lib/railswatch_gem.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "railswatch_gem/version"
+require_relative "railswatch_gem/configuration"
+require_relative "railswatch_gem/client"
+require_relative "railswatch_gem/instrumentation/registry"
+require_relative "railswatch_gem/instrumentation/requests_instrumenter"
+require_relative "railswatch_gem/instrumentation/queries_instrumenter"
+require_relative "railswatch_gem/instrumentation/jobs_instrumenter"
+require_relative "railswatch_gem/instrumentation/cache_instrumenter"
+require_relative "railswatch_gem/instrumentation/mail_instrumenter"
+require_relative "railswatch_gem/instrumentation/outgoing_requests_instrumenter"
+require_relative "railswatch_gem/instrumentation/scheduled_tasks_instrumenter"
+require_relative "railswatch_gem/instrumentation/commands_instrumenter"
+require_relative "railswatch_gem/instrumentation/notifications_instrumenter"
+require_relative "railswatch_gem/instrumentation/logs_instrumenter"
+require_relative "railswatch_gem/instrumentation/errors_instrumenter"
+require_relative "railswatch_gem/instrumentation/models_instrumenter"
+require_relative "railswatch_gem/middleware/request_context"
+require_relative "railswatch_gem/helpers"
+
+# Load the Railtie if we are inside a Rails application.
+# We wrap this in a rescue block because sometimes 'Rails' is defined
+# (e.g. in test mocks or specific environments) but the 'rails/railtie' file
+# is not actually available in the load path.
+if defined?(Rails)
+  begin
+    require_relative "railswatch_gem/railtie"
+  rescue LoadError
+    # Rails constant was defined, but we couldn't load rails/railtie.
+    # Proceeding without Railtie integration.
+  end
+end
+
+module RailswatchGem
+  class << self
+    def configure
+      yield(configuration) if block_given?
+
+      # Automatically boot if configured, or allow manual booting
+      # Ideally, you might want to call boot! explicitly in a Railtie
+      boot! if configuration.auto_boot && !defined?(Rails) # If Rails, Railtie handles it
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new(
+        ingest_url: configuration.ingest_url,
+        env_token: configuration.env_token,
+        batch_size: configuration.batch_size,
+        flush_interval: configuration.flush_interval
+      )
+    end
+
+    def instrumentation_registry
+      @instrumentation_registry ||= Instrumentation::Registry.new
+    end
+
+    # Safe to call multiple times
+    def boot!
+      return if @booted
+
+      instrumentation_registry.boot!(client, configuration)
+      @booted = true
+    end
+
+    def record(event)
+      # Ensure client is initialized
+      client.record(event)
+    end
+  end
+end

data/manual_test.rb

@@ -0,0 +1,103 @@
+require "socket"
+require "json"
+require "thread"
+require "logger"
+
+# Since we are running this script standalone (outside of Rails), we need to
+# manually load ActiveSupport parts that the gem expects to be present.
+# Ideally, your gem files should require what they need, but in a Rails gem
+# it is common to assume these are available.
+require "active_support"
+require "active_support/concern"
+require "active_support/core_ext"
+require "active_support/notifications"
+
+# --- MOCK RAILS ENVIRONMENT ---
+# The LogsInstrumenter and ErrorsInstrumenter expect Rails to be present
+# and configured. We mock the minimal requirements here.
+unless defined?(Rails)
+  module Rails; end
+end
+
+# Add logger if missing (ActiveSupport defines the Module, but not the method)
+unless Rails.respond_to?(:logger)
+  def Rails.logger
+    @logger ||= Logger.new($stdout)
+  end
+end
+
+# Add error reporter mock for ErrorsInstrumenter
+unless Rails.respond_to?(:error)
+  def Rails.error
+    @error_mock ||= Class.new do
+      def subscribe(subscriber); end
+    end.new
+  end
+end
+
+# Add application config mock for RequestsInstrumenter (parameter filtering)
+unless Rails.respond_to?(:application)
+  def Rails.application
+    Struct.new(:config).new(
+      Struct.new(:filter_parameters).new([])
+    )
+  end
+end
+# -----------------------------
+
+# 1. Load your gem files (adjust paths if necessary)
+require_relative "lib/railswatch_gem"
+
+# 2. Spin up a tiny TCP server to act as the "Ingestion API"
+#    This lets us see exactly what the gem sends over the network.
+server = TCPServer.new(0) # 0 assigns a random available port
+port = server.addr[1]
+puts "--- 📡 Mock Ingestion Server started on port #{port} ---"
+
+server_thread = Thread.new do
+  loop do
+    client = server.accept
+
+    # Read the HTTP headers and body
+    request_lines = []
+    while (line = client.gets) && line !~ /^\s*$/
+      request_lines << line
+    end
+
+    # Parse Content-Length to read the body
+    content_length = request_lines.find { |l| l =~ /^Content-Length:/ }&.split(":")&.last&.to_i || 0
+    body = client.read(content_length)
+
+    # Acknowledge receipt to the gem (202 Accepted)
+    client.print "HTTP/1.1 202 Accepted\r\n"
+    client.print "Content-Type: application/json\r\n"
+    client.print "\r\n"
+    client.print '{"status":"ok"}'
+    client.close
+
+    puts "\n--- 📦 Payload Received ---"
+    puts JSON.pretty_generate(JSON.parse(body))
+    puts "---------------------------\n"
+  end
+end
+
+# 3. Configure the Gem to point to our mock server
+RailswatchGem.configure do |config|
+  config.ingest_url = "http://localhost:#{port}/ingest"
+  config.env_token = "test-token-123"
+  config.batch_size = 1        # Flush immediately for testing
+  config.flush_interval = 0.1  # Check queue rapidly
+  config.auto_boot = true      # Ensure systems are go
+end
+
+# Manually boot since we aren't in Rails
+RailswatchGem.boot!
+
+# 4. Trigger an event using your new helper
+puts "firing event..."
+RailswatchGem.rw("Hello, World!", { user_id: 42, role: "admin" })
+
+# 5. Wait a moment for the thread to flush
+sleep 2
+
+puts "Done."

data/sig/railswatch_gem.rbs

@@ -0,0 +1,4 @@
+module RailswatchGem
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: railswatch_gem
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Hammett
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-08 00:00:00.000000000 Z
+dependencies: []
+description: Railswatch Gem
+email:
+- thammett@railswatch.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/railswatch_gem.rb
+- lib/railswatch_gem/client.rb
+- lib/railswatch_gem/configuration.rb
+- lib/railswatch_gem/helpers.rb
+- lib/railswatch_gem/instrumentation/cache_instrumenter.rb
+- lib/railswatch_gem/instrumentation/commands_instrumenter.rb
+- lib/railswatch_gem/instrumentation/errors_instrumenter.rb
+- lib/railswatch_gem/instrumentation/jobs_instrumenter.rb
+- lib/railswatch_gem/instrumentation/logs_instrumenter.rb
+- lib/railswatch_gem/instrumentation/mail_instrumenter.rb
+- lib/railswatch_gem/instrumentation/models_instrumenter.rb
+- lib/railswatch_gem/instrumentation/notifications_instrumenter.rb
+- lib/railswatch_gem/instrumentation/outgoing_requests_instrumenter.rb
+- lib/railswatch_gem/instrumentation/queries_instrumenter.rb
+- lib/railswatch_gem/instrumentation/registry.rb
+- lib/railswatch_gem/instrumentation/requests_instrumenter.rb
+- lib/railswatch_gem/instrumentation/scheduled_tasks_instrumenter.rb
+- lib/railswatch_gem/middleware/request_context.rb
+- lib/railswatch_gem/railtie.rb
+- lib/railswatch_gem/version.rb
+- manual_test.rb
+- sig/railswatch_gem.rbs
+homepage: https://github.com/railswatch/railswatch_gem
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/railswatch/railswatch_gem
+  source_code_uri: https://github.com/railswatch/railswatch_gem
+  changelog_uri: https://github.com/railswatch/railswatch_gem/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Railswatch Gem
+test_files: []