rails_performance-alerts 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cc172f0cc721a2a1aa349f9df6ae0ac5d888b85b4075e7d24db94fcd3e27457
+  data.tar.gz: b1ae3e85f458a871ff5f73e8a7582309dd85b8647b5c5947bde0c1a4f0bd45f0
+SHA512:
+  metadata.gz: 7284b5d1210c3dd1545e53418efe55fe1e34ac8f42cdd8e76a932317715513631ccddb53576eb6a135777a38f2e29dbbf3ba9272bb4fc6c70a2e6dcca0219978
+  data.tar.gz: 00cbdbc9646511eb19d39c95e6ad6bed55db4fdda018c15c581e3607bac1281c4f8758c80d860ea8d31accfecf5f730cc548edbb5273693ef859b3d3c5e8c59e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2025
+
+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,308 @@
+# RailsPerformance::Alerts
+
+Customizable alerts for [rails_performance](https://github.com/igorkasyanchuk/rails_performance) metrics.
+
+Monitor your Rails application and receive alerts when metrics exceed configured thresholds.
+
+## Setup
+
+Assuming you already have rails_performance set up, follow these steps:
+
+1. Add to your Gemfile and run `bundle install`:
+
+```ruby
+gem "rails_performance-alerts"
+```
+
+2. Update `config/initializers/rails_performance.rb`:
+
+```ruby
+RailsPerformance.setup do |config|
+  # ... existing rails_performance config ...
+
+  # example alerts:
+  config.alert_rules = [
+    # Request-based alerts
+    {
+      name: "High Response Time",
+      report: "ResponseTimeReport",          # RailsPerformance::Reports::ResponseTimeReport
+      threshold: ->(value) { value > 500 },  # Alert when > 500ms
+      time_window: 5.minutes,                # Calculate average from last 5 minutes
+      duration: 3.minutes                    # Alert if breached for 3 consecutive minutes
+    },
+    {
+      name: "Low Throughput",
+      report: "ThroughputReport",
+      threshold: ->(value) { value < 10 },   # Alert when < 10 requests/min
+      time_window: 3.minutes,
+      duration: 2.minutes
+    },
+    {
+      name: "High Error Count",
+      report: "ThroughputReport",
+      query: { status: 500 },                # Filter to 500 errors only
+      threshold: ->(value) { value > 5 },
+      time_window: 5.minutes,
+      duration: 1.minute
+    },
+    # System resource alerts (requires rails_performance's system monitoring to be enabled)
+    {
+      name: "High CPU Load",
+      report: "CPULoad",                     # RailsPerformance::SystemMonitor::CPULoad
+      threshold: ->(value) { value > 80 },   # Alert when CPU > 80%
+      time_window: 5.minutes,
+      duration: 3.minutes
+    },
+    {
+      name: "High Memory Usage",
+      report: "MemoryUsage",
+      threshold: ->(value) { value > 1.gigabyte },  # Alert when > 1GB
+      time_window: 5.minutes,
+      duration: 2.minutes
+    },
+    {
+      name: "Disk Space Exhaustion",
+      report: "DiskUsage",
+      threshold: ->(value) { value < 5.gigabytes }, # Alert when < 5GB free
+      time_window: 10.minutes,
+      duration: 5.minutes,
+    },
+  ]
+
+  config.alert_handler = RailsPerformance::Alerts::EmailNotifier.new(
+    recipients: ["team@yourapp.com", "ops@yourapp.com"],
+    from: "alerts@yourapp.com",
+    smtp_settions: { ... } # defaults to Rails ActionMailer config if omitted
+  )
+end
+```
+
+3. Run the checks periodically using either ActiveJob, cron, or a standalone daemon:
+
+* ActiveJob: `RailsPerformance::Alerts::CheckerJob`
+* Rake task for cron: `rails_performance:alerts:check`
+* Rake task for daemon: `rails_performance:alerts:monitor`
+
+## How It Works
+
+Alerts can be configured for two types of metrics:
+
+### Request-Based Reports
+
+Any report class from `RailsPerformance::Reports::*`:
+- `ResponseTimeReport` - Average response time in milliseconds
+- `ThroughputReport` - Requests per minute
+- `PercentileReport` - P50, P90, P95, P99 response times
+- Any custom report you create
+
+### System Resource Charts
+
+Monitor system resources with `RailsPerformance::SystemMonitor::*` classes:
+- `CPULoad` - CPU load average
+- `MemoryUsage` - Application memory usage (in bytes)
+- `DiskUsage` - Available disk space (in bytes)
+- Any custom system monitor you create
+
+The `threshold` parameter accepts a lambda that receives the calculated metric value and returns true when the threshold is breached.
+
+## Understanding `time_window` vs `duration`
+
+- **`time_window`**: Period of historical data to analyze (lookback period)
+- **`duration`**: How long the threshold must be exceeded before alerting
+
+Example: `time_window: 5.minutes, duration: 3.minutes` means:
+> "Calculate the average over the last 5 minutes of data. If that average exceeds the threshold for 3 consecutive checks, trigger the alert."
+
+This prevents false alarms from brief spikes while still detecting sustained problems.
+
+## Running Alert Checks
+
+### With ActiveJob (recommended)
+
+Schedule with your preferred job scheduler:
+
+#### With Solid Queue (config/recurring.yml):
+
+```yaml
+rails_performance_alerts:
+  class: RailsPerformance::Alerts::CheckerJob
+  schedule: every minute
+```
+
+#### With whenever gem (config/schedule.rb):
+
+```ruby
+every 1.minute do
+  runner "RailsPerformance::Alerts::CheckerJob.perform_later"
+end
+```
+
+### With cron and rake
+
+Add to your crontab:
+```bash
+* * * * * cd /app && bundle exec rake rails_performance:alerts:check
+```
+
+### Run as its own process
+
+You can run the alert monitor continuously as a daemon process. It will check alerts every minute.
+```bash
+bundle exec rake rails_performance:alerts:monitor
+```
+
+## Filtering Alerts by Query Parameters
+
+You can scope alerts to specific controllers, actions, status codes, or any other attribute:
+
+```ruby
+{
+  name: "Slow API Endpoint",
+  report: RailsPerformance::Reports::ResponseTimeReport,
+  query: {
+    controller: "Api::UsersController",
+    action: "index"
+  },
+  threshold: ->(value) { value > 1000 },
+  time_window: 3.minutes,
+  duration: 2.minutes
+}
+```
+
+The `query` parameter is passed directly to the RailsPerformance DataSource, so you can filter by any attribute available in your performance data.
+
+## Monitoring Specific Servers
+
+For system resource alerts, you can monitor a specific server by providing the `server` parameter:
+
+```ruby
+{
+  name: "High Memory on Production Web Server",
+  report: RailsPerformance::SystemMonitor::MemoryUsage,
+  server: "web-server-1///production///web",  # Format: hostname///context///role
+  threshold: ->(value) { value > 2_000_000_000 },
+  time_window: 5.minutes,
+  duration: 2.minutes
+}
+```
+
+If no `server` is specified, the alert will monitor the first available server in the ResourcesReport.
+
+## Alerting on Missing Data
+
+By default, alerts will trigger when metric data is missing (e.g., no server reporting resource metrics). This is useful for detecting when servers go offline or stop reporting data.
+
+```ruby
+{
+  name: "Server Offline",
+  report: RailsPerformance::SystemMonitor::CPULoad,
+  threshold: ->(value) { value > 80 },
+  time_window: 5.minutes,
+  duration: 2.minutes,
+  alert_on_missing_data: true  # Default: true
+}
+```
+
+If you want to ignore missing data and only alert on threshold breaches:
+
+```ruby
+{
+  name: "High CPU (ignore missing data)",
+  report: RailsPerformance::SystemMonitor::CPULoad,
+  threshold: ->(value) { value > 80 },
+  time_window: 5.minutes,
+  duration: 2.minutes,
+  alert_on_missing_data: false  # Don't alert when data is missing
+}
+```
+
+**Note**: For request-based reports, missing data typically means no requests were recorded, which returns a value of `0.0` rather than `nil`.
+
+## Custom Alert Handlers
+
+While the built-in `EmailNotifier` (shown in the configuration example above) handles most use cases, you can create custom alert handlers for other notification systems.
+
+### Post to Slack
+
+```ruby
+config.alert_handler = proc do |alert|
+  slack = Slack::Notifier.new(ENV['SLACK_WEBHOOK_URL'])
+
+  case alert[:action]
+  when :triggered
+    slack.ping("🚨 *Alert Triggered*: #{alert[:name]}\n" \
+               "Current value: #{alert[:current_value]}")
+  when :resolved
+    slack.ping("✅ *Alert Resolved*: #{alert[:name]}")
+  when :error
+    slack.ping("⚠️ *Alert System Error*: #{alert[:error].message}")
+  end
+end
+```
+
+### Create PagerDuty Incident
+
+```ruby
+config.alert_handler = proc do |alert|
+  pagerduty = Pagerduty.build(
+    integration_key: ENV['PAGERDUTY_INTEGRATION_KEY']
+  )
+
+  case alert[:action]
+  when :triggered
+    pagerduty.trigger(
+      summary: "#{alert[:name]}: value is #{alert[:current_value]}",
+      severity: 'error',
+      custom_details: alert
+    )
+  when :resolved
+    pagerduty.resolve
+  when :error
+    pagerduty.trigger(
+      summary: "Alert system error: #{alert[:error].message}",
+      severity: 'critical',
+      custom_details: alert
+    )
+  end
+end
+```
+
+### Custom Email Mailer
+
+```ruby
+config.alert_handler = proc do |alert|
+  case alert[:action]
+  when :triggered
+    MyAlertMailer.alert_triggered(alert).deliver_later
+  when :resolved
+    MyAlertMailer.alert_resolved(alert).deliver_later
+  when :error
+    MyAlertMailer.alert_error(alert).deliver_later
+  end
+end
+```
+
+### Alert Handler Actions
+
+Your alert handler will receive alerts with three possible actions:
+
+- **`:triggered`** - An alert threshold has been exceeded
+  - Contains: `:name`, `:current_value`, `:time_window`, `:duration`, `:triggered_at`
+- **`:resolved`** - An alert has returned to normal
+  - Contains: `:name`, `:current_value`, `:resolved_at`, `:was_triggered_at`
+- **`:error`** - An error occurred while checking alerts
+  - Contains: `:error` (exception object), `:rule_config` (may be nil)
+
+## Rake Tasks
+
+```bash
+# Check alerts once
+rake rails_performance:alerts:check
+
+# Run alert monitor continuously as a daemon
+rake rails_performance:alerts:monitor
+```
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: :test

data/lib/rails_performance/alerts/checker.rb

@@ -0,0 +1,84 @@
+module RailsPerformance
+  module Alerts
+    class Checker
+      def self.check_all
+        new.check_all
+      end
+
+      def check_all
+        RailsPerformance.alert_rules.map do |rule_config|
+          begin
+            rule = Rule.new(rule_config)
+            check_rule(rule)
+          rescue => e
+            RailsPerformance.log "Error checking alert rule: #{e.message}"
+            notify_error e, rule_config
+            nil
+          end
+        end.compact
+      end
+
+      def check_rule rule
+        current_value, breaching = rule.evaluate
+
+        # Only skip if value is nil AND not breaching (alert_on_missing_data: false)
+        return nil if current_value.nil? && !breaching
+
+        state = State.new(rule.id)
+
+        if breaching
+          state.record_breach
+          duration_met = state.breaching_duration >= rule.duration
+
+          if duration_met && !state.triggered?
+            trigger_alert rule, current_value, state
+            return { action: :triggered, rule: rule, value: current_value }
+          end
+        else
+          if state.triggered?
+            resolve_alert rule, current_value, state
+            return { action: :resolved, rule: rule, value: current_value }
+          end
+          state.clear_breaches
+        end
+
+        nil
+      end
+
+      private
+
+      def trigger_alert rule, current_value, state
+        state.mark_triggered!
+
+        RailsPerformance.alert_handler&.call({
+          action: :triggered,
+          name: rule.name,
+          current_value: current_value,
+          time_window: rule.time_window,
+          duration: rule.duration,
+          triggered_at: Time.now
+        })
+      end
+
+      def resolve_alert rule, current_value, state
+        state.mark_resolved!
+
+        RailsPerformance.alert_handler&.call({
+          action: :resolved,
+          name: rule.name,
+          current_value: current_value,
+          resolved_at: Time.now,
+          was_triggered_at: state.triggered_at
+        })
+      end
+
+      def notify_error(exception, rule_config)
+        RailsPerformance.alert_handler&.call({
+          action: :error,
+          error: exception,
+          rule_config: rule_config
+        })
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/checker_job.rb

@@ -0,0 +1,11 @@
+module RailsPerformance
+  module Alerts
+    class CheckerJob < ActiveJob::Base
+      queue_as :default
+
+      def perform
+        Checker.check_all
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/email_notifier.rb

@@ -0,0 +1,36 @@
+require_relative "mailer"
+
+module RailsPerformance
+  module Alerts
+    class EmailNotifier < Data.define(:recipients, :from, :smtp_settings)
+      def initialize recipients:, from:, smtp_settings: ::Rails.application.config.action_mailer.smtp_settings
+        recipients = Array(recipients)
+        super
+      end
+
+      def call alert
+        configure_mailer
+        deliver_emails alert
+      end
+
+      private
+
+      def deliver_emails alert
+        case alert[:action]
+        when :triggered
+          recipients.each do |recipient|
+            Mailer.triggered(alert, to: recipient, from: from).deliver_now
+          end
+        when :resolved
+          recipients.each do |recipient|
+            Mailer.resolved(alert, to: recipient, from: from).deliver_now
+          end
+        end
+      end
+
+      def configure_mailer
+        Mailer.smtp_settings = smtp_settings
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/mailer.rb

@@ -0,0 +1,57 @@
+module RailsPerformance
+  module Alerts
+    class Mailer < ActionMailer::Base
+      prepend_view_path File.expand_path("views", __dir__)
+      layout "rails_performance/alerts/layouts/mailer"
+
+      def triggered alert_data, to:, from:
+        @alert = alert_data
+        @name = alert_data[:name]
+        @current_value = alert_data[:current_value]
+        @time_window = format_duration(alert_data[:time_window])
+        @duration = format_duration(alert_data[:duration])
+        @triggered_at = alert_data[:triggered_at]
+
+        mail(
+          to: to,
+          from: from,
+          subject: "🚨 Alert Triggered: #{@name}",
+        )
+      end
+
+      def resolved alert_data, to:, from:
+        @alert = alert_data
+        @name = alert_data[:name]
+        @current_value = alert_data[:current_value]
+        @resolved_at = alert_data[:resolved_at]
+        @was_triggered_at = alert_data[:was_triggered_at]
+        @duration_triggered = calculate_duration(@was_triggered_at, @resolved_at)
+
+        mail(
+          to: to,
+          from: from,
+          subject: "✅ Alert Resolved: #{@name}",
+        )
+      end
+
+      private
+
+      def format_duration seconds
+        return "N/A" unless seconds
+
+        if seconds < 60
+          "#{seconds.to_i} seconds"
+        elsif seconds < 3600
+          "#{(seconds / 60).to_i} minutes"
+        else
+          "#{(seconds / 3600).to_i} hours"
+        end
+      end
+
+      def calculate_duration start_time, end_time
+        return "N/A" unless start_time && end_time
+        format_duration(end_time - start_time)
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/railtie.rb

@@ -0,0 +1,9 @@
+module RailsPerformance
+  module Alerts
+    class Railtie < ::Rails::Railtie
+      rake_tasks do
+        load File.expand_path("tasks.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/rule.rb

@@ -0,0 +1,126 @@
+module RailsPerformance
+  module Alerts
+    class Rule
+      attr_reader :name, :time_window, :duration, :report, :query, :threshold, :server, :alert_on_missing_data
+
+      def initialize(options = {})
+        @name = options[:name] || "Unnamed Alert"
+        @time_window = options[:time_window] || 5.minutes
+        @duration = options[:duration] || 5.minutes
+        @report = options[:report]
+        @query = options[:query] || {}
+        @threshold = options[:threshold]
+        @server = options[:server]
+        @alert_on_missing_data = options.fetch(:alert_on_missing_data, true)
+
+        validate!
+      end
+
+      def id
+        @id ||= Digest::MD5.hexdigest("#{name}_#{report_class}_#{query}_#{server}_#{threshold.source_location}")
+      end
+
+      def evaluate
+        data = fetch_data
+
+        value = calculate_average_value(data)
+        breaching = if value.nil?
+          @alert_on_missing_data
+        else
+          @threshold.call(value)
+        end
+
+        [value, breaching]
+      end
+
+      def to_s
+        "#{name} (#{report})"
+      end
+
+      def report_class
+        return @report if @report.is_a?(Class)
+
+        unless @report.is_a?(String)
+          raise ArgumentError, "Invalid report class name: #{@report.inspect}"
+        end
+
+        # Try RailsPerformance::Reports namespace first
+        if RailsPerformance::Reports.const_defined?(@report, false)
+          return RailsPerformance::Reports.const_get(@report, false)
+        end
+
+        # Try RailsPerformance::SystemMonitor namespace
+        if RailsPerformance::SystemMonitor.const_defined?(@report, false)
+          return RailsPerformance::SystemMonitor.const_get(@report, false)
+        end
+
+        # Try top-level constant
+        if Object.const_defined?(@report, false)
+          return Object.const_get(@report, false)
+        end
+
+        raise ArgumentError, "Class #{@report} not found in RailsPerformance::Reports, RailsPerformance::SystemMonitor, or top level"
+      end
+
+      private
+
+      def resource_chart?
+        report_class.ancestors.include?(RailsPerformance::SystemMonitor::ResourceChart)
+      end
+
+      def fetch_data
+        if resource_chart?
+          fetch_resource_chart_data
+        else
+          fetch_report_data
+        end
+      end
+
+      def fetch_resource_chart_data
+        time_window_days = RailsPerformance::Utils.days(@time_window)
+        query_params = @query.merge({on: Date.today})
+        db = RailsPerformance::DataSource.new(type: :resources, q: query_params, days: time_window_days).db
+
+        resources_report = RailsPerformance::Reports::ResourcesReport.new(db)
+
+        target_server = if @server
+          resources_report.servers.find { |s| s.key == @server }
+        else
+          resources_report.servers.first
+        end
+
+        return nil if target_server.nil?
+
+        chart = report_class.new(target_server)
+        chart.data
+      end
+
+      def fetch_report_data
+        time_window_days = RailsPerformance::Utils.days(@time_window)
+        query_params = @query.merge({on: Date.today})
+        db = RailsPerformance::DataSource.new(type: :requests, q: query_params, days: time_window_days).db
+
+        report = report_class.new(db)
+        report.data
+      end
+
+      def calculate_average_value(data)
+        window_start = (Time.now - @time_window).to_i * 1000
+        recent_data = (data || []).select { |timestamp, value| timestamp >= window_start && value }
+        values = recent_data.map { |_, value| value }.compact
+
+        return nil if values.empty?
+
+        (values.sum.to_f / values.size).round(2)
+      end
+
+      def validate!
+        raise ArgumentError, "name is required" if @name.nil? || @name.empty?
+        raise ArgumentError, "report class is required" unless report_class.is_a?(Class)
+        raise ArgumentError, "threshold lambda is required" unless @threshold.is_a?(Proc)
+        raise ArgumentError, "time_window must be positive" unless @time_window.to_i > 0
+        raise ArgumentError, "duration must be positive" unless @duration.to_i > 0
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/state.rb

@@ -0,0 +1,80 @@
+module RailsPerformance
+  module Alerts
+    class State
+      REDIS_KEY_PREFIX = "rails_performance:alerts:state"
+      STATE_TTL = 7.days.to_i
+
+      attr_reader :rule_id
+
+      def initialize(rule_id)
+        @rule_id = rule_id
+      end
+
+      def triggered?
+        redis.get(triggered_key) == "true"
+      end
+
+      def mark_triggered!(timestamp = Time.now)
+        redis.setex(triggered_key, STATE_TTL, "true")
+        redis.setex(triggered_at_key, STATE_TTL, timestamp.to_i.to_s)
+      end
+
+      def mark_resolved!(timestamp = Time.now)
+        redis.del(triggered_key)
+        redis.setex(resolved_at_key, STATE_TTL, timestamp.to_i.to_s)
+      end
+
+      def triggered_at
+        timestamp = redis.get(triggered_at_key)
+        timestamp ? Time.at(timestamp.to_i) : nil
+      end
+
+      def resolved_at
+        timestamp = redis.get(resolved_at_key)
+        timestamp ? Time.at(timestamp.to_i) : nil
+      end
+
+      def first_breach_at
+        timestamp = redis.get(first_breach_key)
+        timestamp ? Time.at(timestamp.to_i) : nil
+      end
+
+      def record_breach(timestamp = Time.now)
+        unless first_breach_at
+          redis.setex(first_breach_key, STATE_TTL, timestamp.to_i.to_s)
+        end
+      end
+
+      def clear_breaches
+        redis.del(first_breach_key)
+      end
+
+      def breaching_duration
+        return 0 unless first_breach_at
+        Time.now - first_breach_at
+      end
+
+      private
+
+      def redis
+        RailsPerformance.redis
+      end
+
+      def triggered_key
+        "#{REDIS_KEY_PREFIX}:#{rule_id}:triggered"
+      end
+
+      def triggered_at_key
+        "#{REDIS_KEY_PREFIX}:#{rule_id}:triggered_at"
+      end
+
+      def resolved_at_key
+        "#{REDIS_KEY_PREFIX}:#{rule_id}:resolved_at"
+      end
+
+      def first_breach_key
+        "#{REDIS_KEY_PREFIX}:#{rule_id}:first_breach_at"
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/tasks.rake

@@ -0,0 +1,75 @@
+namespace :rails_performance do
+  namespace :alerts do
+    desc "Check all configured alerts"
+    task check: :environment do
+      unless RailsPerformance.enabled
+        puts "RailsPerformance is disabled. Skipping alert checks."
+        next
+      end
+
+      if RailsPerformance.alert_rules.empty?
+        puts "No alert rules configured. Skipping alert checks."
+        next
+      end
+
+      puts "Checking #{RailsPerformance.alert_rules.size} alert rule(s)..."
+
+      results = RailsPerformance::Alerts::Checker.check_all
+
+      if results.empty?
+        puts "All metrics are within normal thresholds."
+      else
+        results.each do |result|
+          case result[:action]
+          when :triggered
+            puts "ALERT TRIGGERED: #{result[:rule].name} - #{result[:rule].metric} is #{result[:value]} (threshold: #{result[:rule].threshold})"
+          when :resolved
+            puts "ALERT RESOLVED: #{result[:rule].name} - #{result[:rule].metric} is now #{result[:value]}"
+          end
+        end
+      end
+    end
+
+    desc "Run alert checker continuously (for background process)"
+    task monitor: :environment do
+      unless RailsPerformance.enabled
+        puts "RailsPerformance is disabled. Exiting."
+        exit
+      end
+
+      if RailsPerformance.alert_rules.empty?
+        puts "No alert rules configured. Exiting."
+        exit
+      end
+
+      puts "Starting alert monitor (checking every minute)..."
+      puts "Monitoring #{RailsPerformance.alert_rules.size} alert rule(s)"
+      puts "Press Ctrl+C to stop"
+
+      trap("INT") do
+        puts "\nStopping alert monitor..."
+        exit
+      end
+
+      loop do
+        begin
+          results = RailsPerformance::Alerts::Checker.check_all
+
+          results.each do |result|
+            case result[:action]
+            when :triggered
+              puts "[#{Time.now}] ALERT TRIGGERED: #{result[:rule].name}"
+            when :resolved
+              puts "[#{Time.now}] ALERT RESOLVED: #{result[:rule].name}"
+            end
+          end
+        rescue => e
+          puts "[#{Time.now}] Error checking alerts: #{e.message}"
+          puts e.backtrace.first(5).join("\n") if RailsPerformance.debug
+        end
+
+        sleep 1.minute
+      end
+    end
+  end
+end

data/lib/rails_performance/alerts/version.rb

@@ -0,0 +1,5 @@
+module RailsPerformance
+  module Alerts
+    VERSION = "0.1.0"
+  end
+end

data/lib/rails_performance/alerts/views/rails_performance/alerts/layouts/mailer.html.erb

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' />
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    .alert-box {
+      border-radius: 8px;
+      padding: 20px;
+      margin: 20px 0;
+    }
+    .alert-box.warning {
+      background-color: #fff3cd;
+      border: 2px solid #ffc107;
+    }
+    .alert-box.success {
+      background-color: #d4edda;
+      border: 2px solid #28a745;
+    }
+    .alert-header {
+      font-size: 24px;
+      font-weight: bold;
+      margin-bottom: 15px;
+    }
+    .alert-box.warning .alert-header {
+      color: #856404;
+    }
+    .alert-box.success .alert-header {
+      color: #155724;
+    }
+    .alert-details {
+      background-color: white;
+      border-radius: 4px;
+      padding: 15px;
+      margin: 15px 0;
+    }
+    .detail-row {
+      display: flex;
+      padding: 8px 0;
+      border-bottom: 1px solid #f0f0f0;
+    }
+    .detail-row:last-child {
+      border-bottom: none;
+    }
+    .detail-label {
+      font-weight: bold;
+      min-width: 150px;
+      color: #666;
+    }
+    .detail-value {
+      color: #333;
+    }
+    .footer {
+      margin-top: 30px;
+      padding-top: 20px;
+      border-top: 1px solid #ddd;
+      font-size: 12px;
+      color: #999;
+    }
+  </style>
+</head>
+<body>
+  <%= yield %>
+
+  <div class="footer">
+    This is an automated alert from RailsPerformance::Alerts
+  </div>
+</body>
+</html>

data/lib/rails_performance/alerts/views/rails_performance/alerts/mailer/resolved.html.erb

@@ -0,0 +1,30 @@
+<div class="alert-box success">
+  <div class="alert-header">
+    ✅ Alert Resolved
+  </div>
+
+  <p><strong><%= @name %></strong> <%= @current_value.nil? ? "data is now available." : "has returned to normal levels." %></p>
+
+  <div class="alert-details">
+    <div class="detail-row">
+      <div class="detail-label">Current Value:</div>
+      <div class="detail-value"><%= @current_value.nil? ? "No data available" : @current_value %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Was Triggered At:</div>
+      <div class="detail-value"><%= @was_triggered_at.strftime("%Y-%m-%d %H:%M:%S %Z") %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Resolved At:</div>
+      <div class="detail-value"><%= @resolved_at.strftime("%Y-%m-%d %H:%M:%S %Z") %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Duration:</div>
+      <div class="detail-value"><%= @duration_triggered %></div>
+    </div>
+  </div>
+
+  <p style="margin-top: 20px;">
+    The alert condition is no longer active.
+  </p>
+</div>

data/lib/rails_performance/alerts/views/rails_performance/alerts/mailer/resolved.text.erb

@@ -0,0 +1,15 @@
+✅ ALERT RESOLVED ✅
+
+<%= @name %> has returned to normal levels.
+
+Alert Details:
+----------------
+Current Value:     <%= @current_value %>
+Was Triggered At:  <%= @was_triggered_at.strftime("%Y-%m-%d %H:%M:%S %Z") %>
+Resolved At:       <%= @resolved_at.strftime("%Y-%m-%d %H:%M:%S %Z") %>
+Duration:          <%= @duration_triggered %>
+
+The alert condition is no longer active.
+
+---
+This is an automated alert from RailsPerformance::Alerts

data/lib/rails_performance/alerts/views/rails_performance/alerts/mailer/triggered.html.erb

@@ -0,0 +1,30 @@
+<div class="alert-box warning">
+  <div class="alert-header">
+    🚨 Alert Triggered
+  </div>
+
+  <p><strong><%= @name %></strong> <%= @current_value.nil? ? "has no data available." : "has exceeded its threshold." %></p>
+
+  <div class="alert-details">
+    <div class="detail-row">
+      <div class="detail-label">Current Value:</div>
+      <div class="detail-value"><%= @current_value.nil? ? "No data available" : @current_value %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Time Window:</div>
+      <div class="detail-value"><%= @time_window %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Duration:</div>
+      <div class="detail-value"><%= @duration %></div>
+    </div>
+    <div class="detail-row">
+      <div class="detail-label">Triggered At:</div>
+      <div class="detail-value"><%= @triggered_at.strftime("%Y-%m-%d %H:%M:%S %Z") %></div>
+    </div>
+  </div>
+
+  <p style="margin-top: 20px;">
+    Please investigate this issue as soon as possible.
+  </p>
+</div>

data/lib/rails_performance/alerts/views/rails_performance/alerts/mailer/triggered.text.erb

@@ -0,0 +1,15 @@
+🚨 ALERT TRIGGERED 🚨
+
+<%= @name %> <%= @current_value.nil? ? "has no data available." : "has exceeded its threshold." %>
+
+Alert Details:
+----------------
+Current Value: <%= @current_value.nil? ? "No data available" : @current_value %>
+Time Window:   <%= @time_window %>
+Duration:      <%= @duration %>
+Triggered At:  <%= @triggered_at.strftime("%Y-%m-%d %H:%M:%S %Z") %>
+
+Please investigate this issue as soon as possible.
+
+---
+This is an automated alert from RailsPerformance::Alerts

data/lib/rails_performance/alerts.rb

@@ -0,0 +1,52 @@
+require "rails_performance"
+require "active_support/core_ext/integer"
+require_relative "alerts/version"
+require_relative "alerts/rule"
+require_relative "alerts/state"
+require_relative "alerts/checker"
+require_relative "alerts/checker_job" if defined?(ActiveJob)
+require_relative "alerts/mailer" if defined?(ActionMailer)
+require_relative "alerts/email_notifier" if defined?(ActionMailer)
+require_relative "alerts/railtie" if defined?(Rails::Railtie)
+
+module RailsPerformance
+  module Alerts
+    class ConfigurationError < StandardError; end
+
+    class << self
+      def validate_configuration!
+        # Check if alert_rules exist without handler
+        if RailsPerformance.alert_rules.any? && RailsPerformance.alert_handler.nil?
+          raise ConfigurationError, "alert_rules are configured but alert_handler is not set"
+        end
+
+        # Validate handler is callable
+        if RailsPerformance.alert_handler && !RailsPerformance.alert_handler.respond_to?(:call)
+          raise ConfigurationError, "alert_handler must respond to :call"
+        end
+
+        # Validate each rule can be instantiated
+        RailsPerformance.alert_rules.each_with_index do |rule_config, index|
+          begin
+            Rule.new(rule_config)
+          rescue => e
+            raise ConfigurationError, "Invalid alert rule at index #{index}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+
+  mattr_accessor :alert_rules
+  @@alert_rules = []
+
+  mattr_accessor :alert_handler
+  @@alert_handler = nil
+
+  singleton_class.prepend Module.new {
+    def setup
+      super
+      RailsPerformance::Alerts.validate_configuration!
+    end
+  }
+end

data/lib/rails_performance-alerts.rb

@@ -0,0 +1 @@
+require "rails_performance/alerts"

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: rails_performance-alerts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails_performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Add user-configurable alerts to rails_performance gem for monitoring
+  response time, throughput, error rates, and system resources
+email:
+- micah@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/rails_performance-alerts.rb
+- lib/rails_performance/alerts.rb
+- lib/rails_performance/alerts/checker.rb
+- lib/rails_performance/alerts/checker_job.rb
+- lib/rails_performance/alerts/email_notifier.rb
+- lib/rails_performance/alerts/mailer.rb
+- lib/rails_performance/alerts/railtie.rb
+- lib/rails_performance/alerts/rule.rb
+- lib/rails_performance/alerts/state.rb
+- lib/rails_performance/alerts/tasks.rake
+- lib/rails_performance/alerts/version.rb
+- lib/rails_performance/alerts/views/rails_performance/alerts/layouts/mailer.html.erb
+- lib/rails_performance/alerts/views/rails_performance/alerts/mailer/resolved.html.erb
+- lib/rails_performance/alerts/views/rails_performance/alerts/mailer/resolved.text.erb
+- lib/rails_performance/alerts/views/rails_performance/alerts/mailer/triggered.html.erb
+- lib/rails_performance/alerts/views/rails_performance/alerts/mailer/triggered.text.erb
+homepage: https://github.com/username/rails_performance-alerts
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: Customizable alerts for rails_performance metrics
+test_files: []