Plugin System Guide

# config/initializers/error_dashboard_plugins.rb
class MyCustomPlugin < RailsErrorDashboard::Plugin
  def name
    "My Custom Plugin"
  end

  def description
    "Does something with errors"
  end

  def on_error_logged(error_log)
    Rails.logger.info("New error: #{error_log.error_type}")
  end
end

# config/initializers/error_dashboard_plugins.rb, after the class
RailsErrorDashboard.register_plugin(MyCustomPlugin.new)

def on_error_logged(error_log)
  SendErrorJob.perform_later(error_log.id)
end

class RailsErrorDashboard::Plugin
  def name                 # required, and unique among your plugins
    raise NotImplementedError, "Plugin must implement #name"
  end

  def description = "No description provided"
  def version = "1.0.0"
  def on_register; end    # called once, at registration
  def enabled? = true      # checked before every hook

  # Event hooks, all optional
  def on_error_logged(error_log); end
  def on_error_recurred(error_log); end
  def on_error_reopened(error_log); end
  def on_error_resolved(error_log); end
  def on_error_muted(error_log); end
  def on_error_unmuted(error_log); end
  def on_errors_batch_resolved(error_logs); end
  def on_errors_batch_muted(error_logs); end
  def on_errors_batch_unmuted(error_logs); end
  def on_errors_batch_deleted(error_ids); end
  def on_error_viewed(error_log); end

  # Calls a hook and rescues what it raises (see "When a plugin fails")
  def safe_execute(method_name, *args); end
end

RailsErrorDashboard.register_plugin(MyCustomPlugin.new)
# => true, or false when a plugin with the same name is already registered

RailsErrorDashboard.register_plugin(Object.new)
# => ArgumentError: Plugin must be an instance of RailsErrorDashboard::Plugin

RailsErrorDashboard.unregister_plugin("My Custom Plugin")
RailsErrorDashboard.plugins # => [#<MyCustomPlugin>, ...]

RailsErrorDashboard::PluginRegistry.names # => ["My Custom Plugin"]
RailsErrorDashboard::PluginRegistry.info
# => [{ name: "My Custom Plugin", version: "1.0.0", description: "...", enabled: true }]
RailsErrorDashboard::PluginRegistry.find("My Custom Plugin") # => #<MyCustomPlugin>

class ErrorMetricsPlugin < RailsErrorDashboard::Plugin
  def name
    "Error Metrics"
  end

  def on_error_logged(error_log)
    StatsD.increment("errors.new")
    StatsD.increment("errors.by_type.#{metric_name(error_log.error_type)}")
  end

  def on_error_resolved(error_log)
    StatsD.increment("errors.resolved")
    seconds = error_log.resolved_at - error_log.first_seen_at
    StatsD.timing("errors.time_to_resolve", (seconds * 1000).round) # timing takes milliseconds
  end

  private

  def metric_name(name)
    name.gsub("::", ".").downcase
  end
end

RailsErrorDashboard.register_plugin(ErrorMetricsPlugin.new)

class ErrorAuditPlugin < RailsErrorDashboard::Plugin
  def initialize(logger: Rails.logger)
    @logger = logger
  end

  def name
    "Error Audit"
  end

  def on_error_resolved(error_log)
    @logger.info("[Audit] resolved #{error_log.id} by #{error_log.resolved_by_name}")
  end

  def on_error_muted(error_log)
    @logger.info("[Audit] muted #{error_log.id} by #{error_log.muted_by}: #{error_log.muted_reason}")
  end

  def on_errors_batch_deleted(error_ids)
    @logger.info("[Audit] deleted #{error_ids.size} errors: #{error_ids.join(', ')}")
  end
end

RailsErrorDashboard.register_plugin(ErrorAuditPlugin.new)

class JiraTicketsPlugin < RailsErrorDashboard::Plugin
  def initialize(jira_client:, project_key:)
    @jira = jira_client
    @project_key = project_key
  end

  def name
    "Jira Tickets"
  end

  def on_error_logged(error_log)
    return unless error_log.critical?
    return if JiraTicketLink.exists?(error_hash: error_log.error_hash)

    CreateJiraTicketJob.perform_later(error_log.id) # the job calls create_ticket
  end

  def create_ticket(error_log)
    issue = @jira.Issue.build
    issue.save("fields" => {
      "project" => { "key" => @project_key },
      "summary" => "[#{error_log.environment}] #{error_log.error_type}",
      "description" => "#{error_log.message}\n\n" \
                       "#{RailsErrorDashboard::Services::NotificationHelpers.dashboard_url(error_log)}",
      "issuetype" => { "name" => "Bug" }
    })
    JiraTicketLink.create!(error_hash: error_log.error_hash, key: issue.key)
  end

  def on_error_resolved(error_log)
    link = JiraTicketLink.find_by(error_hash: error_log.error_hash)
    CloseJiraTicketJob.perform_later(link.key) if link # the job calls close_ticket
  end

  def close_ticket(key)
    issue = @jira.Issue.find(key)
    done = issue.transitions.all.find { |transition| transition.name == "Done" }
    issue.transitions.build.save!("transition" => { "id" => done.id }) if done
  end
end

class ProductionAlertPlugin < RailsErrorDashboard::Plugin
  def name
    "Production Alerts"
  end

  def enabled?
    Rails.env.production?
  end

  def on_error_logged(error_log)
    ProductionAlertService.send_alert(error_log)
  end
end

# config/initializers/error_dashboard_plugins.rb
require "rails_error_dashboard/plugins/metrics_plugin"
require "rails_error_dashboard/plugins/audit_log_plugin"
require "rails_error_dashboard/plugins/jira_integration_plugin"

RailsErrorDashboard.register_plugin(RailsErrorDashboard::Plugins::MetricsPlugin.new)

RailsErrorDashboard.register_plugin(
  RailsErrorDashboard::Plugins::AuditLogPlugin.new(
    logger: Logger.new(Rails.root.join("log", "error_audit.log"))
  )
)

if Rails.env.production?
  RailsErrorDashboard.register_plugin(
    RailsErrorDashboard::Plugins::JiraIntegrationPlugin.new(
      jira_url: ENV["JIRA_URL"],
      jira_username: ENV["JIRA_USERNAME"],
      jira_api_token: ENV["JIRA_API_TOKEN"],
      jira_project_key: ENV["JIRA_PROJECT_KEY"],
      only_critical: true
    )
  )
end

RailsErrorDashboard::PluginRegistry.names
RailsErrorDashboard::PluginRegistry.info
RailsErrorDashboard::PluginRegistry.find("My Custom Plugin").enabled?

RailsErrorDashboard.configuration.async_logging = false # this console only
RailsErrorDashboard::ManualErrorReporter.report(error_type: "PluginTestError", message: "plugin test")

plugin = RailsErrorDashboard::PluginRegistry.find("My Custom Plugin")
plugin.safe_execute(:on_error_logged, RailsErrorDashboard::ErrorLog.last)

# spec/plugins/my_custom_plugin_spec.rb
require "rails_helper"

RSpec.describe MyCustomPlugin do
  let(:plugin) { described_class.new }
  let(:error_log) { RailsErrorDashboard::ErrorLog.new(error_type: "NoMethodError", message: "test") }

  it "has a name" do
    expect(plugin.name).to eq("My Custom Plugin")
  end

  it "logs the error type" do
    allow(Rails.logger).to receive(:info)
    plugin.on_error_logged(error_log)
    expect(Rails.logger).to have_received(:info).with("New error: NoMethodError")
  end
end