error_radar 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 131362a3ccb1bd3de4242f28690bb60059555bee0357ff488fbcce86f9b04f37
-  data.tar.gz: 8f0218c89a83e54e514657dd1c7f9e25a28c39d0adfe284424efdb134bc58467
+  metadata.gz: 106881790c16306716c7588f317da722c0e589db0a0a2bbb6e7ad838c9a8d118
+  data.tar.gz: d4c9ccf1363b88637dc625418daf8553e15aad0796f42f79aadc6eafb3a4f554
 SHA512:
-  metadata.gz: 43ade7e6e0d65e66af9cc34bfa3ee6768fdd9cbad0d79772df01ea6f355b7647f1e5c7a8d8be4667a80abfa5e1c383becc4c97651709c21df2e58fb65a2fede0
-  data.tar.gz: ec4cf4f0863aa19ffa5639659b6a61642921d72462130caaff18a6c2bb2f9424594d9ebbab96dc65c974fab1e4b00b91db96573c3434949ec769ab7b46ef2918
+  metadata.gz: c880963d54ef38274dbc226b970f848f7a9ced038c6d88ababffe1b3eb71ef2d8490695a0a256775a500e707a72b9af2a017a066e8af1f66b17ab842a18ac726
+  data.tar.gz: ba612e7cc8a547cd1bf7ffb8704347636bccc7f763fba3a73fbfe1919b86573421873b61c88f6c8b44da0ed661cf8cf73d4da62a54998828dfe1a767642580ad

data/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-07-03
+
+### Added
+- **REST API** at `/api/*` for external integrations (CI/CD, dashboards, scripts):
+  - `GET  /api/errors` — paginated list with the same filters as the web UI
+    (`status`, `severity`, `category`, `q`, `from`, `to`, `sort`, `order`, `page`)
+  - `GET  /api/errors/:id` — full detail including context, backtrace, and
+    `github_issue_url` (if column is present)
+  - `PATCH /api/errors/:id` — update status; resolve accepts optional `note`
+    and `resolved_by` params
+  - `GET  /api/stats` — summary counts by status, severity, and category
+- **Bearer-token API auth**: set `config.api_token` to protect all `/api/*`
+  endpoints with `Authorization: Bearer <token>`.
+- **GitHub Issue integration**: "Create GitHub Issue" button on the error detail
+  page opens a pre-filled issue with error class, source, message, backtrace,
+  and a deep-link back to Error Radar. Requires `config.github_token` and
+  `config.github_repo`.
+- **`github_issue_url` column**: stored on the error row so the button becomes
+  "View GitHub Issue" once an issue exists. Requires running the upgrade
+  migration: `bin/rails generate error_radar:upgrade_v050 && bin/rails db:migrate`.
+- **`error_radar:upgrade_v050` generator**: generates the migration that adds
+  `github_issue_url` to `error_radar_error_logs`.
+
+### Notes
+- The GitHub column is optional — the integration is gracefully degraded when the
+  migration has not been run (button appears but URL is not persisted).
+- The API controllers live in `ErrorRadar::Api::*` to avoid polluting the host
+  app's controller namespace.
+
+## [0.4.0] - 2026-07-03
+
+### Added
+- **Slack notifications**: sends a Block Kit message with error details and a
+  deep-link button. Configure with `config.slack_webhook_url` and optional
+  `config.slack_channel`.
+- **Discord notifications**: sends a rich embed to any Discord webhook.
+  Configure with `config.discord_webhook_url`.
+- **Email notifications**: delivers an HTML + plain-text email via ActionMailer.
+  Configure `config.email_recipients` and `config.email_from`.
+- **Generic webhook**: POSTs a JSON payload to any URL (PagerDuty, OpsGenie,
+  custom scripts). Configure with `config.webhook_urls = [url1, url2]`.
+- **Custom callbacks**: `config.on_error { |log| ... }` for arbitrary alerting
+  logic (e.g. PagerDuty SDK, Telegram, SMS).
+- **`notify_on` rule set**: controls when alerts fire — `:new_error` (default,
+  first occurrence per fingerprint), `:critical` (any critical severity, 1/hour
+  throttle), `:all` (every occurrence, 1/hour throttle per fingerprint).
+- **In-memory throttle**: prevents notification storms for `:critical` and `:all`
+  rules — at most one alert per fingerprint per hour.
+- **Deep-links in notifications**: set `config.app_host` to include a link to
+  the error detail page in every notification.
+- **`ErrorLog#new_fingerprint?`**: transient predicate (not persisted) that is
+  `true` when the record was just created for the first time.
+
 ## [0.3.0] - 2026-07-03
 
 ### Added

data/app/controllers/error_radar/api/base_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  module Api
+    class BaseController < ActionController::Base
+      skip_before_action :verify_authenticity_token
+      before_action :authenticate_api!
+
+      private
+
+      def authenticate_api!
+        token = ErrorRadar.config.api_token
+        return if token.nil?
+
+        provided = request.headers['Authorization'].to_s.delete_prefix('Bearer ').strip
+        render json: { error: 'Unauthorized' }, status: :unauthorized unless provided == token
+      end
+    end
+  end
+end

data/app/controllers/error_radar/api/errors_controller.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  module Api
+    class ErrorsController < BaseController
+      PER_PAGE = 50
+
+      # GET /api/errors
+      def index
+        scope  = build_scope
+        total  = scope.count
+        page   = [params[:page].to_i, 1].max
+        total_pages = [(total.to_f / PER_PAGE).ceil, 1].max
+        page   = [page, total_pages].min
+
+        errors = scope.limit(PER_PAGE).offset((page - 1) * PER_PAGE)
+
+        render json: {
+          data: errors.map { |e| serialize(e) },
+          meta: { total: total, page: page, per_page: PER_PAGE, total_pages: total_pages }
+        }
+      end
+
+      # GET /api/errors/:id
+      def show
+        log = ErrorLog.find(params[:id])
+        render json: { data: serialize(log, detail: true) }
+      rescue ActiveRecord::RecordNotFound
+        render json: { error: 'Not found' }, status: :not_found
+      end
+
+      # PATCH /api/errors/:id
+      def update
+        log        = ErrorLog.find(params[:id])
+        new_status = params[:status].to_s
+
+        unless ErrorLog.statuses.key?(new_status)
+          return render json: { error: 'invalid status' }, status: :unprocessable_entity
+        end
+
+        if new_status == 'resolved'
+          log.resolve!(by: params[:resolved_by].presence, note: params[:note].presence)
+        else
+          log.update!(status: new_status, resolved_at: nil)
+        end
+
+        render json: { data: serialize(log) }
+      rescue ActiveRecord::RecordNotFound
+        render json: { error: 'Not found' }, status: :not_found
+      end
+
+      private
+
+      def build_scope
+        scope = ErrorLog.all
+        scope = scope.where(status: params[:status])     if params[:status].present?   && ErrorLog.statuses.key?(params[:status])
+        scope = scope.where(severity: params[:severity]) if params[:severity].present? && ErrorLog.severities.key?(params[:severity])
+        scope = scope.where(category: params[:category]) if params[:category].present? && ErrorLog.categories.key?(params[:category])
+
+        if params[:q].present?
+          q = "%#{params[:q].downcase}%"
+          scope = scope.where('lower(message) LIKE :q OR lower(error_class) LIKE :q OR lower(source) LIKE :q', q: q)
+        end
+
+        from = params[:from].present? ? (Date.parse(params[:from]) rescue nil) : nil
+        to   = params[:to].present?   ? (Date.parse(params[:to])   rescue nil) : nil
+        scope = scope.where('last_seen_at >= ?', from) if from
+        scope = scope.where('last_seen_at <= ?', to.end_of_day) if to
+
+        sort = %w[last_seen_at first_seen_at occurrences].include?(params[:sort]) ? params[:sort] : 'last_seen_at'
+        dir  = params[:order] == 'asc' ? :asc : :desc
+        scope.order(sort => dir)
+      end
+
+      def serialize(log, detail: false)
+        data = {
+          id:            log.id,
+          error_class:   log.error_class,
+          source:        log.source,
+          message:       log.message,
+          category:      log.category,
+          severity:      log.severity,
+          status:        log.status,
+          occurrences:   log.occurrences,
+          first_seen_at: log.first_seen_at&.iso8601,
+          last_seen_at:  log.last_seen_at&.iso8601,
+          resolved_at:   log.resolved_at&.iso8601,
+          resolved_by:   log.resolved_by
+        }
+
+        if detail
+          data.merge!(
+            fingerprint:     log.fingerprint,
+            resolution_note: log.resolution_note,
+            http_status:     log.http_status,
+            request_url:     log.request_url,
+            api_code:        log.api_code,
+            api_subcode:     log.api_subcode,
+            context:         log.context,
+            backtrace:       log.backtrace
+          )
+        end
+
+        if log.class.column_names.include?('github_issue_url')
+          data[:github_issue_url] = log.github_issue_url
+        end
+
+        data
+      end
+    end
+  end
+end

data/app/controllers/error_radar/api/stats_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  module Api
+    # GET /api/stats — summary counts for dashboards, CI gates, uptime monitors.
+    class StatsController < BaseController
+      def show
+        render json: {
+          total:       ErrorLog.count,
+          open:        ErrorLog.status_open.count,
+          in_progress: ErrorLog.status_in_progress.count,
+          resolved:    ErrorLog.status_resolved.count,
+          ignored:     ErrorLog.status_ignored.count,
+          unresolved:  ErrorLog.unresolved.count,
+          by_severity: ErrorLog.group(:severity).count,
+          by_category: ErrorLog.group(:category).count,
+          generated_at: Time.current.iso8601
+        }
+      end
+    end
+  end
+end

data/app/controllers/error_radar/errors_controller.rb

@@ -3,7 +3,7 @@
 module ErrorRadar
   class ErrorsController < ApplicationController
     before_action :authenticate_request!
-    before_action :set_error, only: %i[show update_status destroy]
+    before_action :set_error, only: %i[show update_status destroy create_github_issue]
 
     rescue_from ActiveRecord::RecordNotFound do
       redirect_to errors_path, alert: 'Error not found.'
@@ -44,6 +44,35 @@ module ErrorRadar
       render json: { ok: true }
     end
 
+    def create_github_issue
+      unless github_configured?
+        return render json: { ok: false, error: 'GitHub not configured (set config.github_token and config.github_repo)' },
+                      status: :unprocessable_entity
+      end
+
+      if ErrorLog.column_names.include?('github_issue_url') && @error.github_issue_url.present?
+        return render json: { ok: false, error: 'Issue already created', url: @error.github_issue_url },
+                      status: :unprocessable_entity
+      end
+
+      require 'error_radar/integrations/github'
+      result = ErrorRadar::Integrations::Github.create_issue(
+        @error,
+        token: ErrorRadar.config.github_token,
+        repo:  ErrorRadar.config.github_repo
+      )
+
+      if result['html_url']
+        @error.update!(github_issue_url: result['html_url']) if ErrorLog.column_names.include?('github_issue_url')
+        render json: { ok: true, url: result['html_url'], number: result['number'] }
+      else
+        render json: { ok: false, error: result['message'] || 'GitHub API error' },
+               status: :unprocessable_entity
+      end
+    rescue StandardError => e
+      render json: { ok: false, error: e.message }, status: :internal_server_error
+    end
+
     def bulk
       ids = Array(params[:ids]).map(&:to_i).select(&:positive?)
       action = params[:bulk_action].to_s
@@ -115,6 +144,10 @@ module ErrorRadar
       ids.size
     end
 
+    def github_configured?
+      ErrorRadar.config.github_token.present? && ErrorRadar.config.github_repo.present?
+    end
+
     def active_filter_params
       params.permit(:q, :status, :severity, :category, :from, :to, :sort, :order).to_h
     end

data/app/mailers/error_radar/error_mailer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  class ErrorMailer < ActionMailer::Base
+    layout false
+
+    def new_error(error_log)
+      @error    = error_log
+      @is_new   = error_log.new_fingerprint?
+      @url      = build_url
+      @app_name = ErrorRadar::Notifier.app_name
+
+      prefix  = @is_new ? 'New' : 'Critical'
+      subject = "[#{@app_name}] #{prefix} #{@error.severity}: #{@error.error_class}"
+
+      mail(
+        to:      ErrorRadar.config.email_recipients,
+        from:    ErrorRadar.config.email_from || 'noreply@localhost',
+        subject: subject
+      )
+    end
+
+    private
+
+    def build_url
+      host = ErrorRadar.config.app_host.to_s.chomp('/')
+      return nil if host.empty?
+
+      "#{host}/error_radar/errors/#{@error.id}"
+    end
+  end
+end

data/app/models/error_radar/error_log.rb

@@ -29,13 +29,18 @@ module ErrorRadar
     # Record (or roll-up) an error. Idempotent per fingerprint: identical errors
     # increment `occurrences` and bump `last_seen_at` instead of creating a new
     # row. NEVER raises — logging must not break the calling code path.
+    def new_fingerprint?
+      @new_fingerprint || false
+    end
+
     def self.record(category:, message:, severity: :error, error_class: nil, source: nil,
                     backtrace: nil, context: {}, http_status: nil, request_url: nil,
                     api_code: nil, api_subcode: nil, fingerprint: nil)
       now = Time.current
       fp  = presence(fingerprint) || build_fingerprint(category: category, error_class: error_class, source: source, message: message)
 
-      log = find_or_initialize_by(fingerprint: fp)
+      log             = find_or_initialize_by(fingerprint: fp)
+      new_fingerprint = !log.persisted?
 
       if log.persisted?
         log.occurrences += 1
@@ -54,6 +59,7 @@ module ErrorRadar
       log.severity     = severity if log.new_record? || severity_rank(severity) > severity_rank(log.severity)
       log.last_seen_at = now
       log.save!
+      log.instance_variable_set(:@new_fingerprint, new_fingerprint)
       log
     rescue StandardError => e
       ErrorRadar::Tracking.warn_internal("ErrorLog.record failed: #{e.class}: #{e.message}")

data/app/views/error_radar/error_mailer/new_error.html.erb

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <style>
+    body{margin:0;padding:20px;background:#f4f6f8;font-family:-apple-system,"Segoe UI",Roboto,Arial,sans-serif;color:#1f2933}
+    .container{max-width:600px;margin:0 auto}
+    .header{background:#1f2933;color:#fff;padding:24px;border-radius:10px 10px 0 0}
+    .header h1{margin:0 0 6px;font-size:18px}
+    .header .meta{color:#9ca3af;font-size:12px}
+    .body{background:#fff;padding:24px;border-radius:0 0 10px 10px}
+    .grid{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin-bottom:20px}
+    .field .label{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:#9ca3af;margin-bottom:3px}
+    .field .value{font-size:14px;color:#1f2933}
+    .badge{display:inline-block;padding:3px 10px;border-radius:10px;color:#fff;font-size:12px;font-weight:600}
+    .msg-box{background:#f8fafc;border-left:4px solid #dc3545;padding:12px 14px;border-radius:0 8px 8px 0;font-family:ui-monospace,monospace;font-size:12px;white-space:pre-wrap;word-break:break-word;color:#374151;margin:16px 0}
+    .btn{display:inline-block;background:#2563eb;color:#fff!important;padding:11px 22px;border-radius:8px;text-decoration:none;font-size:14px;font-weight:600;margin-top:8px}
+    .footer{margin-top:20px;font-size:11px;color:#9ca3af;text-align:center}
+    <%
+      sev_colors = { 'critical' => '#7b001c', 'error' => '#dc3545', 'warning' => '#fd7e14', 'info' => '#17a2b8' }
+    %>
+  </style>
+</head>
+<body>
+<div class="container">
+  <div class="header">
+    <h1><%= @is_new ? '🆕 New error detected' : '🔁 Critical error recurring' %></h1>
+    <div class="meta"><%= @app_name %> · <%= @error.last_seen_at&.strftime('%Y-%m-%d %H:%M UTC') %></div>
+  </div>
+
+  <div class="body">
+    <div class="field" style="margin-bottom:20px">
+      <div class="label">Error class</div>
+      <div class="value" style="font-family:ui-monospace,monospace;font-size:17px;font-weight:700"><%= @error.error_class %></div>
+    </div>
+
+    <div class="grid">
+      <div class="field">
+        <div class="label">Source</div>
+        <div class="value"><%= @error.source || 'unknown' %></div>
+      </div>
+      <div class="field">
+        <div class="label">Category</div>
+        <div class="value"><%= @error.category.to_s.humanize %></div>
+      </div>
+      <div class="field">
+        <div class="label">Severity</div>
+        <div class="value">
+          <span class="badge" style="background:<%= sev_colors[@error.severity] || '#6c757d' %>"><%= @error.severity %></span>
+        </div>
+      </div>
+      <div class="field">
+        <div class="label">Occurrences</div>
+        <div class="value" style="font-weight:700;font-size:16px"><%= @error.occurrences %></div>
+      </div>
+      <div class="field">
+        <div class="label">First seen</div>
+        <div class="value"><%= @error.first_seen_at&.strftime('%Y-%m-%d %H:%M') %></div>
+      </div>
+      <div class="field">
+        <div class="label">Last seen</div>
+        <div class="value"><%= @error.last_seen_at&.strftime('%Y-%m-%d %H:%M') %></div>
+      </div>
+    </div>
+
+    <div class="field">
+      <div class="label">Message</div>
+      <div class="msg-box"><%= @error.message.to_s.truncate(600) %></div>
+    </div>
+
+    <% if @url %>
+      <a href="<%= @url %>" class="btn">View in Error Radar →</a>
+    <% end %>
+  </div>
+
+  <div class="footer">
+    Sent by <strong>Error Radar</strong> · <%= @app_name %>
+  </div>
+</div>
+</body>
+</html>

data/app/views/error_radar/error_mailer/new_error.text.erb

@@ -0,0 +1,21 @@
+[<%= @app_name %>] <%= @is_new ? 'New error' : 'Critical error recurring' %>: <%= @error.error_class %>
+<%= '=' * 60 %>
+
+Error class:  <%= @error.error_class %>
+Source:       <%= @error.source || 'unknown' %>
+Category:     <%= @error.category %>
+Severity:     <%= @error.severity %>
+Occurrences:  <%= @error.occurrences %>
+First seen:   <%= @error.first_seen_at&.strftime('%Y-%m-%d %H:%M UTC') %>
+Last seen:    <%= @error.last_seen_at&.strftime('%Y-%m-%d %H:%M UTC') %>
+
+Message:
+<%= @error.message.to_s.truncate(1000) %>
+<% if @url %>
+
+View in Error Radar:
+<%= @url %>
+<% end %>
+
+--
+Sent by Error Radar · <%= @app_name %>

data/app/views/error_radar/errors/show.html.erb

@@ -104,11 +104,37 @@
   </div>
 </div>
 
+<%# ── GitHub Issue ── %>
+<% if ErrorRadar.config.github_token.present? && ErrorRadar.config.github_repo.present? %>
+  <div class="panel" style="margin-top:16px">
+    <h2>GitHub</h2>
+    <% has_col = @error.class.column_names.include?('github_issue_url') %>
+    <% if has_col && @error.github_issue_url.present? %>
+      <a href="<%= @error.github_issue_url %>" target="_blank" rel="noopener"
+         class="er-btn" style="background:#24292e;display:inline-block;text-decoration:none">
+        &#9651; View GitHub Issue
+      </a>
+    <% else %>
+      <button id="github-btn" class="er-btn" style="background:#24292e" onclick="createGithubIssue()">
+        &#9651; Create GitHub Issue
+      </button>
+      <span id="github-status" style="font-size:13px;color:#6b7280;margin-left:10px"></span>
+      <% unless has_col %>
+        <p style="font-size:12px;color:#9ca3af;margin:10px 0 0">
+          Run <code style="background:#f3f4f6;padding:2px 6px;border-radius:4px">bin/rails generate error_radar:upgrade_v050 &amp;&amp; bin/rails db:migrate</code>
+          to enable issue tracking.
+        </p>
+      <% end %>
+    <% end %>
+  </div>
+<% end %>
+
 <script>
 (function () {
   var CSRF       = document.querySelector('meta[name="csrf-token"]').content;
   var STATUS_URL = '<%= error_status_path(@error) %>';
   var DELETE_URL = '<%= error_path(@error) %>';
+  var GITHUB_URL = '<%= error_github_issue_path(@error) %>';
 
   document.querySelectorAll('.status-btn').forEach(function (btn) {
     btn.addEventListener('click', function () { changeStatus(btn.dataset.status, null); });
@@ -154,6 +180,35 @@
     });
   };
 
+  window.createGithubIssue = function () {
+    var btn    = document.getElementById('github-btn');
+    var status = document.getElementById('github-status');
+    if (!btn) return;
+    btn.disabled    = true;
+    status.textContent = 'Creating issue…';
+
+    fetch(GITHUB_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': CSRF }
+    })
+    .then(function (r) { return r.json(); })
+    .then(function (d) {
+      if (d.ok) {
+        status.innerHTML = '✓ Created: <a href="' + d.url + '" target="_blank">#' + d.number + '</a>';
+        btn.style.display = 'none';
+        showToast('GitHub issue #' + d.number + ' created', true);
+      } else {
+        status.textContent = 'Error: ' + (d.error || 'failed');
+        btn.disabled = false;
+        showToast(d.error || 'GitHub error', false);
+      }
+    })
+    .catch(function () {
+      status.textContent = 'Network error';
+      btn.disabled = false;
+    });
+  };
+
   function showToast(msg, ok) {
     var t = document.getElementById('toast');
     t.textContent = msg;

data/config/routes.rb

@@ -3,9 +3,17 @@
 ErrorRadar::Engine.routes.draw do
   root to: 'dashboard#index'
 
-  get    'errors',            to: 'errors#index',         as: :errors
-  post   'errors/bulk',       to: 'errors#bulk',          as: :errors_bulk
-  get    'errors/:id',        to: 'errors#show',          as: :error
-  patch  'errors/:id/status', to: 'errors#update_status', as: :error_status
-  delete 'errors/:id',        to: 'errors#destroy'
+  # REST API — JSON endpoints for CI/CD, external dashboards, scripts
+  namespace :api, defaults: { format: :json } do
+    resources :errors, only: %i[index show update]
+    resource  :stats,  only: [:show]
+  end
+
+  # Web UI
+  get    'errors',                  to: 'errors#index',               as: :errors
+  post   'errors/bulk',             to: 'errors#bulk',                as: :errors_bulk
+  post   'errors/:id/github_issue', to: 'errors#create_github_issue', as: :error_github_issue
+  get    'errors/:id',              to: 'errors#show',                as: :error
+  patch  'errors/:id/status',       to: 'errors#update_status',       as: :error_status
+  delete 'errors/:id',              to: 'errors#destroy'
 end

data/lib/error_radar/configuration.rb

@@ -35,6 +35,50 @@ module ErrorRadar
     attr_accessor :install_middleware, :install_sidekiq, :install_rails_admin,
                   :install_active_job, :install_rake
 
+    # Notifications ─────────────────────────────────────────────────────────
+    # When to fire: :new_error (first time a fingerprint is seen),
+    #               :critical  (any critical-severity occurrence, throttled),
+    #               :all       (every occurrence, throttled to 1/hour/fingerprint)
+    attr_accessor :notify_on
+
+    # Slack incoming-webhook URL (https://hooks.slack.com/services/...)
+    attr_accessor :slack_webhook_url
+    # Override target channel. Leave nil to use webhook's default channel.
+    attr_accessor :slack_channel
+
+    # Discord incoming-webhook URL
+    attr_accessor :discord_webhook_url
+
+    # ActionMailer recipients. Requires ActionMailer to be configured in host app.
+    attr_accessor :email_recipients
+    # From address for notification emails.
+    attr_accessor :email_from
+
+    # One or more plain HTTPS URLs that receive a POST with JSON body on each alert.
+    attr_accessor :webhook_urls
+
+    # App name shown in notification subject/title. Defaults to Rails app name.
+    attr_accessor :app_name
+    # Base URL used to build deep-links (e.g. "https://myapp.com").
+    attr_accessor :app_host
+
+    # Custom callbacks: ->(error_log) { ... }. Called after built-in channels.
+    attr_reader :error_callbacks
+
+    def on_error(&block)
+      @error_callbacks << block
+    end
+
+    # REST API ────────────────────────────────────────────────────────────────
+    # Bearer token for /api/* endpoints. nil = unauthenticated (not for prod).
+    attr_accessor :api_token
+
+    # GitHub integration ──────────────────────────────────────────────────────
+    # Personal access token with repo scope.
+    attr_accessor :github_token
+    # "owner/repo" string, e.g. "myorg/myapp".
+    attr_accessor :github_repo
+
     # Custom classification rules. Each is a callable `->(exception) { :category | nil }`.
     # The first rule that returns a non-nil category wins; built-in rules run after.
     attr_accessor :categorizers
@@ -79,6 +123,21 @@ module ErrorRadar
       @install_rails_admin = true
       @install_active_job  = true
       @install_rake        = true
+
+      @notify_on            = [:new_error]
+      @slack_webhook_url    = nil
+      @slack_channel        = nil
+      @discord_webhook_url  = nil
+      @email_recipients     = []
+      @email_from           = nil
+      @webhook_urls         = []
+      @app_name             = nil
+      @app_host             = nil
+      @error_callbacks      = []
+
+      @api_token    = nil
+      @github_token = nil
+      @github_repo  = nil
       @categorizers       = []
       @detail_extractors  = []
       @expected_servers   = []

data/lib/error_radar/integrations/github.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module ErrorRadar
+  module Integrations
+    # Creates GitHub issues from ErrorLog records via the GitHub REST API.
+    # Requires a personal access token with the `repo` scope and a repo in
+    # "owner/repo" format.
+    module Github
+      API_BASE = 'https://api.github.com'
+
+      # Returns the parsed JSON response from GitHub.
+      # Raises StandardError on network/API failure.
+      def self.create_issue(error_log, token:, repo:)
+        owner, repo_name = repo.split('/', 2)
+        uri  = URI("#{API_BASE}/repos/#{owner}/#{repo_name}/issues")
+
+        http              = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        req = Net::HTTP::Post.new(uri)
+        req['Authorization']        = "Bearer #{token}"
+        req['Content-Type']         = 'application/json'
+        req['Accept']               = 'application/vnd.github+json'
+        req['X-GitHub-Api-Version'] = '2022-11-28'
+        req.body = {
+          title:  issue_title(error_log),
+          body:   issue_body(error_log),
+          labels: ['bug', 'error-radar']
+        }.to_json
+
+        response = http.request(req)
+        JSON.parse(response.body)
+      end
+
+      def self.issue_title(log)
+        short_msg = log.message.to_s.truncate(80).gsub(/\n/, ' ')
+        "[Error Radar] #{log.error_class}: #{short_msg}"
+      end
+
+      def self.issue_body(log)
+        url       = ErrorRadar::Notifier.error_url(log)
+        backtrace = log.backtrace.to_s.split("\n").first(20).join("\n")
+
+        parts = []
+        parts << "## Error Details\n"
+        parts << "| Field | Value |"
+        parts << "|-------|-------|"
+        parts << "| **Error Class** | `#{log.error_class}` |"
+        parts << "| **Source** | #{log.source || 'unknown'} |"
+        parts << "| **Category** | #{log.category} |"
+        parts << "| **Severity** | #{log.severity} |"
+        parts << "| **Occurrences** | #{log.occurrences} |"
+        parts << "| **First seen** | #{log.first_seen_at&.strftime('%Y-%m-%d %H:%M UTC')} |"
+        parts << "| **Last seen** | #{log.last_seen_at&.strftime('%Y-%m-%d %H:%M UTC')} |"
+        parts << "\n## Message\n\n```\n#{log.message.to_s.truncate(1000)}\n```"
+
+        unless backtrace.empty?
+          parts << "\n## Backtrace\n\n```\n#{backtrace}\n```"
+        end
+
+        parts << "\n## Link\n\n[View in Error Radar](#{url})" if url
+
+        parts << "\n---\n*Created automatically by [Error Radar](https://github.com/chienbn9x/error_radar)*"
+        parts.join("\n")
+      end
+    end
+  end
+end

data/lib/error_radar/notifications/discord.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module ErrorRadar
+  module Notifications
+    module Discord
+      SEV_COLORS = {
+        'critical' => 0x7b001c,
+        'error'    => 0xdc3545,
+        'warning'  => 0xfd7e14,
+        'info'     => 0x17a2b8
+      }.freeze
+
+      def self.deliver(log)
+        url     = URI(ErrorRadar.config.discord_webhook_url)
+        payload = build_payload(log)
+
+        http              = Net::HTTP.new(url.host, url.port)
+        http.use_ssl      = url.scheme == 'https'
+        http.open_timeout = 5
+        http.read_timeout = 5
+
+        req                 = Net::HTTP::Post.new(url)
+        req['Content-Type'] = 'application/json'
+        req.body            = payload.to_json
+
+        http.request(req)
+      rescue StandardError => e
+        ErrorRadar::Tracking.warn_internal("Discord notification failed: #{e.message}")
+      end
+
+      def self.build_payload(log)
+        app    = ErrorRadar::Notifier.app_name
+        url    = ErrorRadar::Notifier.error_url(log)
+        prefix = log.new_fingerprint? ? '🆕 New error' : '🔁 Critical error'
+
+        fields = [
+          { name: 'Source',      value: (log.source || 'unknown').truncate(100), inline: true },
+          { name: 'Category',    value: log.category.to_s,                       inline: true },
+          { name: 'Severity',    value: log.severity.to_s,                       inline: true },
+          { name: 'Occurrences', value: log.occurrences.to_s,                    inline: true }
+        ]
+        fields << { name: 'View', value: "[Error Radar](#{url})", inline: false } if url
+
+        embed = {
+          title:       "#{prefix}: #{log.error_class}",
+          description: "```#{log.message.to_s.truncate(300)}```",
+          color:       SEV_COLORS[log.severity] || 0x6c757d,
+          fields:      fields,
+          footer:      { text: "[#{app}] Error Radar" },
+          timestamp:   log.last_seen_at&.iso8601
+        }.compact
+
+        { embeds: [embed] }
+      end
+    end
+  end
+end

data/lib/error_radar/notifications/email.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  module Notifications
+    # Delivers notification emails via ActionMailer (must be configured in
+    # the host app). Uses deliver_later so it doesn't block the request cycle.
+    module Email
+      def self.deliver(log)
+        return unless defined?(::ActionMailer::Base)
+
+        require 'error_radar/mailers/error_mailer'
+        ErrorRadar::ErrorMailer.new_error(log).deliver_later
+      rescue StandardError => e
+        ErrorRadar::Tracking.warn_internal("Email notification failed: #{e.message}")
+      end
+    end
+  end
+end

data/lib/error_radar/notifications/slack.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module ErrorRadar
+  module Notifications
+    module Slack
+      SEV_EMOJI = {
+        'critical' => ':red_circle:',
+        'error'    => ':large_orange_circle:',
+        'warning'  => ':large_yellow_circle:',
+        'info'     => ':large_blue_circle:'
+      }.freeze
+
+      def self.deliver(log)
+        url     = URI(ErrorRadar.config.slack_webhook_url)
+        payload = build_payload(log)
+
+        http              = Net::HTTP.new(url.host, url.port)
+        http.use_ssl      = url.scheme == 'https'
+        http.open_timeout = 5
+        http.read_timeout = 5
+
+        req                  = Net::HTTP::Post.new(url)
+        req['Content-Type']  = 'application/json'
+        req.body             = payload.to_json
+
+        http.request(req)
+      rescue StandardError => e
+        ErrorRadar::Tracking.warn_internal("Slack notification failed: #{e.message}")
+      end
+
+      def self.build_payload(log)
+        emoji   = SEV_EMOJI[log.severity] || ':white_circle:'
+        title   = "#{emoji} #{log.new_fingerprint? ? 'New error' : 'Critical error'}: *#{log.error_class}*"
+        url     = ErrorRadar::Notifier.error_url(log)
+        app     = ErrorRadar::Notifier.app_name
+        channel = ErrorRadar.config.slack_channel
+
+        blocks = [
+          { type: 'section', text: { type: 'mrkdwn', text: "*[#{app}]* #{title}" } },
+          {
+            type: 'section',
+            fields: [
+              { type: 'mrkdwn', text: "*Source*\n#{(log.source || 'unknown').truncate(80)}" },
+              { type: 'mrkdwn', text: "*Category*\n#{log.category}" },
+              { type: 'mrkdwn', text: "*Severity*\n#{log.severity}" },
+              { type: 'mrkdwn', text: "*Occurrences*\n#{log.occurrences}" }
+            ]
+          },
+          {
+            type: 'section',
+            text: { type: 'mrkdwn', text: "*Message*\n```#{log.message.to_s.truncate(400)}```" }
+          }
+        ]
+
+        if url
+          blocks << {
+            type: 'actions',
+            elements: [{
+              type: 'button',
+              text: { type: 'plain_text', text: 'View in Error Radar', emoji: true },
+              url: url
+            }]
+          }
+        end
+
+        payload = { blocks: blocks, text: "[#{app}] #{log.error_class}: #{log.message.to_s.truncate(200)}" }
+        payload[:channel] = channel if channel.to_s != ''
+        payload
+      end
+    end
+  end
+end

data/lib/error_radar/notifications/webhook.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module ErrorRadar
+  module Notifications
+    # Generic outbound webhook. POSTs a JSON payload to any URL.
+    # Useful for PagerDuty, OpsGenie, custom scripts, etc.
+    module Webhook
+      def self.deliver(log, url:)
+        uri = URI(url)
+
+        http              = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = uri.scheme == 'https'
+        http.open_timeout = 5
+        http.read_timeout = 5
+
+        req                 = Net::HTTP::Post.new(uri)
+        req['Content-Type'] = 'application/json'
+        req['User-Agent']   = "ErrorRadar/#{ErrorRadar::VERSION}"
+        req.body            = build_payload(log).to_json
+
+        http.request(req)
+      rescue StandardError => e
+        ErrorRadar::Tracking.warn_internal("Webhook (#{url}) notification failed: #{e.message}")
+      end
+
+      def self.build_payload(log)
+        {
+          event:         log.new_fingerprint? ? 'new_error' : 'recurring_error',
+          app:           ErrorRadar::Notifier.app_name,
+          error_class:   log.error_class,
+          source:        log.source,
+          category:      log.category,
+          severity:      log.severity,
+          message:       log.message.to_s.truncate(500),
+          occurrences:   log.occurrences,
+          fingerprint:   log.fingerprint,
+          first_seen_at: log.first_seen_at&.iso8601,
+          last_seen_at:  log.last_seen_at&.iso8601,
+          url:           ErrorRadar::Notifier.error_url(log)
+        }
+      end
+    end
+  end
+end

data/lib/error_radar/notifier.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ErrorRadar
+  # Dispatches alert notifications (Slack, Discord, email, webhooks, custom
+  # callbacks) after an ErrorLog is persisted. Called from Tracking.capture and
+  # Tracking.notify. Never raises — a broken notification must not affect the
+  # host application.
+  module Notifier
+    THROTTLE_MUTEX = Mutex.new
+    # fingerprint => Time of last notification (in-memory, resets on restart)
+    THROTTLE = {}
+    THROTTLE_INTERVAL = 3600 # seconds between repeat alerts per fingerprint
+
+    def self.dispatch(log)
+      return unless ErrorRadar.config.enabled
+      return unless should_fire?(log)
+
+      cfg = ErrorRadar.config
+      send_slack(log)                           if cfg.slack_webhook_url.to_s.start_with?('http')
+      send_discord(log)                         if cfg.discord_webhook_url.to_s.start_with?('http')
+      send_email(log)                           if cfg.email_recipients.any?
+      cfg.webhook_urls.each { |url| send_webhook(log, url) }
+      cfg.error_callbacks.each { |cb| safe_call(cb, log) }
+    rescue StandardError => e
+      ErrorRadar::Tracking.warn_internal("Notifier.dispatch failed: #{e.message}")
+    end
+
+    # ── Fire decision ──────────────────────────────────────────────────────
+    def self.should_fire?(log)
+      rules = Array(ErrorRadar.config.notify_on).map(&:to_sym)
+      return false if rules.empty?
+
+      # :new_error — fire exactly once per fingerprint (no throttle needed)
+      return true if rules.include?(:new_error) && log.new_fingerprint?
+
+      # :critical / :all — fire for recurring events, subject to throttle
+      matches_severity = rules.include?(:all) ||
+                         (rules.include?(:critical) && log.severity_critical?)
+      matches_severity && throttle_ok?(log.fingerprint)
+    end
+
+    def self.throttle_ok?(fingerprint)
+      THROTTLE_MUTEX.synchronize do
+        last = THROTTLE[fingerprint]
+        ok   = last.nil? || (Time.current - last) >= THROTTLE_INTERVAL
+        THROTTLE[fingerprint] = Time.current if ok
+        ok
+      end
+    end
+
+    # ── Channel dispatchers ────────────────────────────────────────────────
+    def self.send_slack(log)
+      require 'error_radar/notifications/slack'
+      Notifications::Slack.deliver(log)
+    end
+
+    def self.send_discord(log)
+      require 'error_radar/notifications/discord'
+      Notifications::Discord.deliver(log)
+    end
+
+    def self.send_email(log)
+      require 'error_radar/notifications/email'
+      Notifications::Email.deliver(log)
+    end
+
+    def self.send_webhook(log, url)
+      require 'error_radar/notifications/webhook'
+      Notifications::Webhook.deliver(log, url: url)
+    end
+
+    def self.safe_call(cb, log)
+      cb.call(log)
+    rescue StandardError => e
+      ErrorRadar::Tracking.warn_internal("on_error callback failed: #{e.message}")
+    end
+
+    # Build a deep-link URL to the error detail page.
+    def self.error_url(log)
+      host = ErrorRadar.config.app_host.to_s.chomp('/')
+      return nil if host.empty?
+
+      "#{host}/error_radar/errors/#{log.id}"
+    end
+
+    def self.app_name
+      ErrorRadar.config.app_name ||
+        (defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : 'App')
+    end
+  end
+end

data/lib/error_radar/tracking.rb

@@ -27,7 +27,9 @@ module ErrorRadar
         attrs.merge!(extra.compact) if extra.is_a?(Hash)
       end
 
-      ErrorRadar::ErrorLog.record(**attrs)
+      log = ErrorRadar::ErrorLog.record(**attrs)
+      ErrorRadar::Notifier.dispatch(log) if log
+      log
     rescue StandardError => e
       warn_internal("capture failed: #{e.class}: #{e.message}")
       nil
@@ -47,7 +49,9 @@ module ErrorRadar
     def notify(message, category: :application, severity: :error, source: nil, context: {})
       return nil unless ErrorRadar.config.enabled
 
-      ErrorRadar::ErrorLog.record(category: category, severity: severity, message: message, source: source, context: context)
+      log = ErrorRadar::ErrorLog.record(category: category, severity: severity, message: message, source: source, context: context)
+      ErrorRadar::Notifier.dispatch(log) if log
+      log
     rescue StandardError => e
       warn_internal("notify failed: #{e.class}: #{e.message}")
       nil

data/lib/error_radar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ErrorRadar
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

data/lib/error_radar.rb

@@ -3,6 +3,7 @@
 require 'error_radar/version'
 require 'error_radar/configuration'
 require 'error_radar/tracking'
+require 'error_radar/notifier'
 require 'error_radar/middleware'
 require 'error_radar/server_monitor'
 require 'error_radar/engine'

data/lib/generators/error_radar/install/templates/initializer.rb

@@ -14,6 +14,33 @@ ErrorRadar.configure do |config|
   config.install_rake        = true   # capture Rake task failures (auto)
   config.install_rails_admin = true   # register the ErrorLog board (auto, if RailsAdmin present)
 
+  # --- Notifications ---
+  # When to fire: :new_error (first occurrence of a fingerprint, default),
+  #               :critical  (any critical severity, throttled to 1/hour),
+  #               :all       (every occurrence, throttled to 1/hour per fingerprint)
+  config.notify_on = [:new_error]
+
+  # Slack incoming webhook (https://api.slack.com/messaging/webhooks)
+  # config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
+  # config.slack_channel     = '#errors'   # optional override
+
+  # Discord incoming webhook
+  # config.discord_webhook_url = ENV['DISCORD_WEBHOOK_URL']
+
+  # Email (requires ActionMailer to be configured in the host app)
+  # config.email_recipients = ['dev@myapp.com', 'oncall@myapp.com']
+  # config.email_from       = 'errors@myapp.com'
+
+  # Generic webhook — POST JSON to any URL (PagerDuty, OpsGenie, custom scripts)
+  # config.webhook_urls = [ENV['PAGERDUTY_WEBHOOK_URL']]
+
+  # Base URL used to generate deep-links in notifications
+  # config.app_host = 'https://myapp.com'
+  # config.app_name = 'MyApp'              # shown in notification title/subject
+
+  # Custom callback — runs after all built-in channels
+  # config.on_error { |error_log| MyPager.create_incident(error_log) }
+
   # --- Dashboard access control ---
   # Run as a before_action; raise/redirect inside to deny. Example with Devise:
   # config.authenticate = ->(controller) { controller.send(:authenticate_admin!) }
@@ -45,6 +72,17 @@ ErrorRadar.configure do |config|
   # config.expected_servers = [
   #   { key: 'web', name: 'Web', tag: 'sidekiq_web', host: 'web', queue_hint: 'low' }
   # ]
+
+  # --- REST API ---
+  # Protect /api/* endpoints with a Bearer token.
+  # config.api_token = ENV['ERROR_RADAR_API_TOKEN']
+  # curl -H "Authorization: Bearer $TOKEN" https://myapp.com/error_radar/api/stats
+
+  # --- GitHub Integration ---
+  # Creates GitHub issues directly from the error detail page.
+  # Requires running: bin/rails generate error_radar:upgrade_v050 && bin/rails db:migrate
+  # config.github_token = ENV['GITHUB_TOKEN']   # PAT with repo scope
+  # config.github_repo  = 'myorg/myapp'         # "owner/repo" format
 end
 
 # ActiveJob is now captured automatically via install_active_job = true above.

data/lib/generators/error_radar/upgrade_v050/templates/add_github_issue_to_error_radar_error_logs.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddGithubIssueToErrorRadarErrorLogs < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :error_radar_error_logs, :github_issue_url, :string, limit: 500
+  end
+end

data/lib/generators/error_radar/upgrade_v050/upgrade_v050_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module ErrorRadar
+  module Generators
+    class UpgradeV050Generator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generates the migration for Error Radar v0.5.0 (adds github_issue_url column).'
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template(
+          'add_github_issue_to_error_radar_error_logs.rb.tt',
+          'db/migrate/add_github_issue_to_error_radar_error_logs.rb'
+        )
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: error_radar
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - chienbn9x
@@ -57,13 +57,19 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/controllers/error_radar/api/base_controller.rb
+- app/controllers/error_radar/api/errors_controller.rb
+- app/controllers/error_radar/api/stats_controller.rb
 - app/controllers/error_radar/application_controller.rb
 - app/controllers/error_radar/dashboard_controller.rb
 - app/controllers/error_radar/errors_controller.rb
+- app/mailers/error_radar/error_mailer.rb
 - app/models/error_radar/application_record.rb
 - app/models/error_radar/error_log.rb
 - app/views/error_radar/dashboard/index.html.erb
 - app/views/error_radar/dashboard/show.html.erb
+- app/views/error_radar/error_mailer/new_error.html.erb
+- app/views/error_radar/error_mailer/new_error.text.erb
 - app/views/error_radar/errors/index.html.erb
 - app/views/error_radar/errors/show.html.erb
 - app/views/layouts/error_radar/application.html.erb
@@ -72,16 +78,24 @@ files:
 - lib/error_radar/configuration.rb
 - lib/error_radar/engine.rb
 - lib/error_radar/integrations/active_job.rb
+- lib/error_radar/integrations/github.rb
 - lib/error_radar/integrations/rails_admin.rb
 - lib/error_radar/integrations/rake.rb
 - lib/error_radar/integrations/sidekiq.rb
 - lib/error_radar/middleware.rb
+- lib/error_radar/notifications/discord.rb
+- lib/error_radar/notifications/email.rb
+- lib/error_radar/notifications/slack.rb
+- lib/error_radar/notifications/webhook.rb
+- lib/error_radar/notifier.rb
 - lib/error_radar/server_monitor.rb
 - lib/error_radar/tracking.rb
 - lib/error_radar/version.rb
 - lib/generators/error_radar/install/install_generator.rb
 - lib/generators/error_radar/install/templates/create_error_radar_error_logs.rb.tt
 - lib/generators/error_radar/install/templates/initializer.rb
+- lib/generators/error_radar/upgrade_v050/templates/add_github_issue_to_error_radar_error_logs.rb.tt
+- lib/generators/error_radar/upgrade_v050/upgrade_v050_generator.rb
 homepage: https://github.com/chienbn9x/error_radar
 licenses:
 - MIT