railswatch_gem 0.1.0

data/lib/railswatch_gem/instrumentation/jobs_instrumenter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class JobsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Subscribe to the execution event.
+        # "enqueue.active_job" is also available if you want to track queue depth/latency separately.
+        ActiveSupport::Notifications.subscribe("perform.active_job") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+        job = payload[:job]
+
+        # Guard against malformed payloads (though rare in ActiveJob)
+        return unless job
+
+        data = {
+          event_type: "job",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Job Identity
+          job_class: job.class.name,
+          job_id: job.job_id,
+          queue_name: job.queue_name,
+          priority: job.priority,
+
+          # Execution Context
+          adapter: payload[:adapter]&.class&.name,
+          executions: job.executions,
+
+          # Performance
+          duration_ms: event.duration.round(2)
+        }
+
+        # Calculate Queue Latency: Time spent waiting in the queue
+        if job.enqueued_at
+          enqueued_time = Time.iso8601(job.enqueued_at) rescue nil
+          if enqueued_time
+            # Start of processing - Time enqueued
+            # FIX: Convert event.time (Float) to Time before subtraction
+            latency = (Time.at(event.time) - enqueued_time) * 1000
+            data[:queue_latency_ms] = latency.round(2)
+          end
+        end
+
+        # Error handling
+        if payload[:exception]
+          # payload[:exception] is [ClassName, Message]
+          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 job event: #{e.message}"
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/logs_instrumenter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module RailswatchGem
+  module Instrumentation
+    class LogsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Only attach if Rails logger is available
+        return unless defined?(::Rails) && ::Rails.logger
+
+        target_logger = ::Rails.logger
+
+        # Avoid double patching if called multiple times
+        return if target_logger.respond_to?(:_railswatch_instrumented?)
+
+        # Create the interception module bound to our client
+        interceptor = create_interceptor(@client)
+
+        # Extend the specific logger instance.
+        # This inserts the module into the object's singleton class inheritance chain,
+        # effectively wrapping the 'add' method.
+        target_logger.extend(interceptor)
+      end
+
+      private
+
+      def create_interceptor(client)
+        Module.new do
+          # FIX: We use define_method here to create a closure over the 'client' variable.
+          # Standard 'def' methods create a new scope and cannot access outer local variables.
+          # We expose client as a private method so 'add' can access it.
+          define_method(:_railswatch_client) { client }
+          private :_railswatch_client
+
+          # The primary entry point for Ruby Logger
+          def add(severity, message = nil, progname = nil, &block)
+            # PERFORMANCE: Check level first.
+            if respond_to?(:level) && severity < level
+              return super
+            end
+
+            begin
+              # Resolve the message content.
+              log_message = message
+              if log_message.nil?
+                if block_given?
+                  log_message = yield
+                else
+                  log_message = progname
+                end
+              end
+
+              # INFINITE LOOP PROTECTION
+              unless log_message.to_s.include?("[Railswatch]")
+
+                request_id = Thread.current[:railswatch_request_id]
+
+                # FIX: Access client via the closure-captured helper method
+                _railswatch_client.record({
+                  event_type: "log",
+                  timestamp: Time.now.utc.iso8601,
+                  severity: format_severity_level(severity),
+                  message: log_message.to_s,
+                  progname: progname,
+                  request_id: request_id
+                })
+              end
+
+              super(severity, log_message, nil)
+            rescue => e
+              # Fallback: If our instrumentation fails, ensure the app's logging continues.
+              $stderr.puts "RailswatchGem: LogsInstrumenter error: #{e.message}"
+              super
+            end
+          end
+
+          # Marker method to prevent double-patching
+          def _railswatch_instrumented?
+            true
+          end
+
+          private
+
+          def format_severity_level(severity)
+            case severity
+            when 0, ::Logger::DEBUG then "DEBUG"
+            when 1, ::Logger::INFO  then "INFO"
+            when 2, ::Logger::WARN  then "WARN"
+            when 3, ::Logger::ERROR then "ERROR"
+            when 4, ::Logger::FATAL then "FATAL"
+            else "UNKNOWN"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/mail_instrumenter.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class MailInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # Subscribe to the delivery event.
+        # "process.action_mailer" is also available if you want to track template rendering time separately.
+        ActiveSupport::Notifications.subscribe("deliver.action_mailer") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+
+        # Payload keys depend on Rails version, but generally include:
+        # :mailer, :message_id, :subject, :to, :from, :bcc, :cc, :date
+
+        # Calculate recipient count for metrics
+        to_count = Array(payload[:to]).size
+        cc_count = Array(payload[:cc]).size
+        bcc_count = Array(payload[:bcc]).size
+        total_recipients = to_count + cc_count + bcc_count
+
+        data = {
+          event_type: "mail",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Identity
+          mailer: payload[:mailer], # The class name of the mailer
+          message_id: payload[:message_id],
+
+          # Content (Be careful with PII here)
+          subject: payload[:subject],
+          from: Array(payload[:from]).join(", "),
+          to: Array(payload[:to]).join(", "),
+
+          # Metrics
+          recipient_count: total_recipients,
+          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
+        end
+
+        @client.record(data)
+      rescue => e
+        warn "RailswatchGem: Failed to process mail event: #{e.message}"
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/models_instrumenter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  module Instrumentation
+    class ModelsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        return unless defined?(::ActiveRecord::Base)
+
+        # Inject our tracking module into ActiveRecord
+        ::ActiveRecord::Base.include(Tracker)
+      end
+
+      module Tracker
+        extend ActiveSupport::Concern
+
+        included do
+          # We use after_commit to ensure we only report data that actually persisted.
+          # We pass 'self' to the callbacks.
+          after_commit :_railswatch_handle_create, on: :create
+          after_commit :_railswatch_handle_update, on: :update
+          after_commit :_railswatch_handle_destroy, on: :destroy
+        end
+
+        def _railswatch_handle_create
+          _railswatch_record_event("model_create")
+        end
+
+        def _railswatch_handle_update
+          _railswatch_record_event("model_update")
+        end
+
+        def _railswatch_handle_destroy
+          _railswatch_record_event("model_destroy")
+        end
+
+        private
+
+        def _railswatch_record_event(type)
+          # Guard: Avoid tracking internal Rails models or strict excludes
+          return if self.class.name.start_with?("ActiveRecord::", "RailswatchGem::")
+
+          # Retrieve Request ID if available for correlation
+          request_id = Thread.current[:railswatch_request_id]
+
+          # Calculate changes.
+          # Note: In after_commit, previous_changes is needed because changes is empty.
+          changes_hash = previous_changes.dup
+
+          # Filter sensitive attributes (naive approach, can be improved with Rails.application.config.filter_parameters)
+          _railswatch_filter_attributes!(changes_hash)
+
+          data = {
+            event_type: "model",
+            action: type, # model_create, etc.
+            timestamp: Time.now.utc.iso8601,
+
+            # Model Identity
+            model: self.class.name,
+            key: self.id,
+
+            # The actual data changed
+            changes: changes_hash,
+
+            # Correlation
+            request_id: request_id
+          }
+
+          RailswatchGem.record(data)
+        rescue => e
+          # Swallow errors to prevent model callbacks from aborting transactions
+          warn "RailswatchGem: Failed to record model event: #{e.message}"
+        end
+
+        def _railswatch_filter_attributes!(hash)
+          # Basic filtration of common sensitive fields
+          sensitive = %w[password password_digest token secret credit_card cc_number]
+          hash.each_key do |key|
+            if sensitive.any? { |s| key.to_s.include?(s) }
+              hash[key] = ["[FILTERED]", "[FILTERED]"]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/notifications_instrumenter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class NotificationsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        # This instrumenter allows users to track arbitrary ActiveSupport::Notifications.
+        # It relies on the user defining 'tracked_notifications' in the configuration.
+        #
+        # Example Config usage:
+        #   config.tracked_notifications = ["billing.checkout", /users\..*/]
+
+        patterns = if @config.respond_to?(:tracked_notifications)
+                     @config.tracked_notifications
+                   else
+                     []
+                   end
+
+        # FIX: Use .map instead of .each to return the array of subscribers.
+        # This allows tests (and apps) to keep track of subscriptions and unsubscribe if needed.
+        Array(patterns).map do |pattern|
+          ActiveSupport::Notifications.subscribe(pattern) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            process_event(event)
+          end
+        end
+      end
+
+      private
+
+      def process_event(event)
+        # Prevent infinite loops if the user accidentally subscribes to our own internal events
+        return if event.name.start_with?("railswatch_gem")
+
+        payload = event.payload
+
+        data = {
+          event_type: "notification",
+          name: event.name,
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+          duration_ms: event.duration.round(2)
+        }
+
+        # Safely merge primitive payload values to avoid serialization issues with complex objects
+        safe_payload = payload.select do |_, v|
+          v.is_a?(String) || v.is_a?(Numeric) || v.is_a?(TrueClass) || v.is_a?(FalseClass) || v.nil?
+        end
+
+        data[:payload] = safe_payload
+
+        # 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 notification event: #{e.message}"
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/outgoing_requests_instrumenter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "active_support/notifications"
+require "uri"
+
+module RailswatchGem
+  module Instrumentation
+    class OutgoingRequestsInstrumenter
+      def initialize(client, config)
+        @client = client
+        @config = config
+        # Cache ingestion URI components for fast comparison
+        @ingest_uri = URI(@config.ingest_url) rescue nil
+      end
+
+      def start
+        # Monkey-patch Net::HTTP if we haven't already.
+        # This wraps the low-level request method to emit an ActiveSupport notification.
+        unless Net::HTTP.include?(NetHttpPatch)
+          Net::HTTP.prepend(NetHttpPatch)
+        end
+
+        ActiveSupport::Notifications.subscribe("request.net_http") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+
+        # CRITICAL: Ignore requests to the ingestion endpoint.
+        # This prevents an infinite loop where reporting metrics generates more metrics.
+        if @ingest_uri &&
+           payload[:host] == @ingest_uri.host &&
+           payload[:port] == @ingest_uri.port
+          return
+        end
+
+        data = {
+          event_type: "outgoing_request",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Request Details
+          method: payload[:method],
+          url: payload[:uri].to_s,
+          host: payload[:host],
+          port: payload[:port],
+          scheme: payload[:scheme],
+          path: payload[:path],
+
+          # 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
+        end
+
+        @client.record(data)
+      rescue => e
+        warn "RailswatchGem: Failed to process outgoing request event: #{e.message}"
+      end
+
+      # ----------------------------------------------------------------
+      # Internal Patch for Net::HTTP
+      # ----------------------------------------------------------------
+      module NetHttpPatch
+        def request(req, body = nil, &block)
+          scheme = use_ssl? ? "https" : "http"
+
+          # Reconstruct basic URI for context
+          # Note: address and port are methods on the Net::HTTP instance
+          uri = URI("#{scheme}://#{address}:#{port}#{req.path}")
+
+          ActiveSupport::Notifications.instrument("request.net_http", {
+            host: address,
+            port: port,
+            scheme: scheme,
+            path: req.path,
+            method: req.method,
+            uri: uri
+          }) do
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/queries_instrumenter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module RailswatchGem
+  module Instrumentation
+    class QueriesInstrumenter
+      # We usually want to ignore internal Rails schema queries
+      IGNORED_NAMES = %w[SCHEMA EXPLAIN].freeze
+
+      def initialize(client, config)
+        @client = client
+        @config = config
+      end
+
+      def start
+        ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          process_event(event)
+        end
+      end
+
+      private
+
+      def process_event(event)
+        payload = event.payload
+
+        name = payload[:name]
+        return if name && IGNORED_NAMES.include?(name)
+
+        # Basic PII safety: You might want to sanitize SQL here depending on your needs.
+        # payload[:sql] usually contains the raw SQL with bound parameters injected
+        # if config.filter_parameters is not applied manually.
+
+        data = {
+          event_type: "query",
+          # FIX: Handle Float timestamps safely
+          timestamp: Time.at(event.end).utc.iso8601,
+
+          # Query Details
+          name: name || "SQL",
+          sql: payload[:sql],
+          cached: payload[:cached] || false,
+
+          # Performance
+          duration_ms: event.duration.round(2)
+        }
+
+        # Add connection_id if useful for debugging connection pool issues
+        data[:connection_id] = payload[:connection_id] if payload[:connection_id]
+
+        @client.record(data)
+      rescue => e
+        warn "RailswatchGem: Failed to process query event: #{e.message}"
+      end
+    end
+  end
+end

data/lib/railswatch_gem/instrumentation/registry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RailswatchGem
+  module Instrumentation
+    class Registry
+      def initialize
+        @instrumenters = {}
+        register_builtin_instrumenters
+      end
+
+      def register(name, klass)
+        @instrumenters[name.to_sym] = klass
+      end
+
+      def boot!(client, config)
+        config.enabled_events.each do |name|
+          klass = @instrumenters[name.to_sym]
+
+          if klass
+            klass.new(client, config).start
+          else
+            warn "RailswatchGem: Instrumenter '#{name}' enabled but class not registered."
+          end
+        end
+
+        config.custom_event_blocks.each do |block|
+          block.call(client)
+        end
+      end
+
+      private
+
+      def register_builtin_instrumenters
+        register :requests, RequestsInstrumenter
+        register :queries, QueriesInstrumenter
+        register :jobs, JobsInstrumenter
+        register :cache, CacheInstrumenter
+        register :mail, MailInstrumenter
+        register :outgoing_requests, OutgoingRequestsInstrumenter
+        register :scheduled_tasks, ScheduledTasksInstrumenter
+        register :commands, CommandsInstrumenter
+        register :notifications, NotificationsInstrumenter
+        register :logs, LogsInstrumenter
+        register :errors, ErrorsInstrumenter
+        register :models, ModelsInstrumenter
+      end
+    end
+  end
+end