solid_errors 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11cd9651413ea528780669e5c01abec456118a34a70c93042a85a471c0d1fd07
-  data.tar.gz: 39f16c51d5bb62144c8b1b138c18fc6fa4dff4e601c635ed3046f9d37f1d960a
+  metadata.gz: 389a4c6c9c7910c471dfc93caf7003790e1afa6c0a6781f010d6453b99731ec2
+  data.tar.gz: 0ad0508538e6ff2f523a865e4230ff371400a56b8e897b6078c47570dd71eccc
 SHA512:
-  metadata.gz: 39341060f4ee0e9bfdc009fedd2176fb9bb7ae6c60aaddc175f8e4449d2274f7014f6df71b683865a94eb6c779700c4b0356a0addf2c435a40162027a45b5bec
-  data.tar.gz: 87f876f3bdcdf11dcdeac4ded4c6ae873c3f5a53c87aebe454ce925416a66ad19dc37d4984b9a6c326fe79e2c1bab16f6c20f6feb9f79381a70965e35d058030
+  metadata.gz: c91d2c051098cd1f3530592f76f85b9dffe8aa264f693950673f1ac8110a09f1c0b6afa86ec7eb3b071d52825899cf71cf17e75ad01f394639446df4fbf21fbd
+  data.tar.gz: 7947a0212c04437d205c822da7a0a96fccba64907d5ad3a062afe6919934767d4d533da0f977e6d48218b7c7f6bd9d992a10cf5d157c2a661154edb0921488bc

data/README.md

@@ -79,6 +79,9 @@ production:
 
 Then run `db:prepare` in production to ensure the database is created and the schema is loaded.
 
+> [!WARNING]
+> Use `db:prepare`, not `db:create` followed by `db:migrate`. Solid Errors ships a schema rather than migrations, so `db:migrate` leaves the errors database empty and then dumps that empty schema over `db/errors_schema.rb`. If that has happened, copy the schema back from [the install template](lib/generators/solid_errors/install/templates/db/errors_schema.rb) and run `db:prepare` again.
+
 Then mount the engine in your `config/routes.rb` file:
 ```ruby
 authenticate :user, -> (user) { user.admin? } do
@@ -151,6 +154,17 @@ Rails.error.handle(context: { user_id: user.id }, severity: :info) do
 end
 ```
 
+
+### What each occurrence records
+
+Every occurrence stores the backtrace and the error's context. Rails adds the current request or job to that context, and Solid Errors records it as:
+
+* **Requests:** the controller action (`UsersController#show`) and its params, with your `config.filter_parameters` applied.
+* **Background jobs:** the job class, its id and queue, and its arguments, also filtered.
+
+Any Active Record object in the context is stored as its [GlobalID](https://github.com/rails/globalid) (`gid://my-app/User/1`), so you can tell which record was involved. Add your own context with `Rails.error.set_context(...)` or the `context:` option shown above.
+
+Errors raised in background jobs reach Solid Errors when your job backend runs jobs inside the Rails executor, as Solid Queue, Sidekiq and GoodJob do. You don't need any extra setup for this.
 ### Configuration
 
 You can configure Solid Errors via the Rails configuration object, under the `solid_errors` key. Currently, the following configuration options are available:
@@ -164,6 +178,7 @@ You can configure Solid Errors via the Rails configuration object, under the `so
 * `email_to` - The email address(es) to send a notification to. See [Email notifications](#email-notifications) for more information.
 * `email_every_occurrence` - Whether to email every occurrence (the default), or only new errors and resolved errors that occur again. See [Email notifications](#email-notifications) for more information.
 * `email_subject_prefix` - Prefix added to the subject line for email notifications. See [Email notifications](#email-notifications) for more information.
+* `email_subject` - A proc that builds the subject line for email notifications. See [Email notifications](#email-notifications) for more information.
 * `base_controller_class` - Specify a different controller as the base class for the Solid Errors controller. See [Authentication](#authentication) for more information.
 * `destroy_after` - If set, Solid Errors will periodically destroy resolved records that are older than the value specified. See [Automatically destroying old records](#automatically-destroying-old-records) for more information.
 * `ignored_errors` - Error classes, or their names, to never record, in addition to the built-in list in `SolidErrors::Subscriber::IGNORED_ERRORS`. For example, `config.solid_errors.ignored_errors = ["ActiveStorage::FileNotFoundError"]`.
@@ -230,6 +245,10 @@ config.solid_errors.enabled = false
 
 When disabled, Solid Errors will not subscribe to the Rails error reporter and no errors will be recorded.
 
+Disable it in every environment that loads the gem but has no errors database, such as development or test. Otherwise Solid Errors records errors to the primary database, fails with `Could not find table 'solid_errors'`, and in development and test that failure can hide the error you were looking for.
+
+Configuration belongs in `config/environments/<environment>.rb`, not in `config/<environment>.rb`, which Rails does not load.
+
 #### Authentication
 
 Solid Errors does not restrict access out of the box. You must secure the dashboard yourself. However, it does provide basic HTTP authentication that can be used with basic authentication or Devise. All you need to do is setup a username and password.
@@ -272,14 +291,14 @@ Solid Errors _can_ send email notifications whenever an error occurs, if your ap
 
 There are two ways to configure email notifications. First, you can use environment variables:
 
-```ruby
-ENV["SOLIDERRORS_SEND_EMAILS"] = true # defaults to false
-ENV["SOLIDERRORS_EMAIL_FROM"] = "errors@myapp.com" # defaults to "solid_errors@noreply.com"
-ENV["SOLIDERRORS_EMAIL_TO"] = "devs@myapp.com" # no default, must be set
-ENV["SOLIDERRORS_EMAIL_SUBJECT_PREFIX"] = "[Application name][Environment]" # no default, optional
+```sh
+SOLIDERRORS_SEND_EMAILS=true # defaults to false
+SOLIDERRORS_EMAIL_FROM=errors@myapp.com # defaults to solid_errors@noreply.com
+SOLIDERRORS_EMAIL_TO=devs@myapp.com # no default, must be set
+SOLIDERRORS_EMAIL_SUBJECT_PREFIX="[Application name][Environment]" # no default, optional
 ```
 
-Second, you can set the values via the configuration object:
+Second, you can set the values via the configuration object, which takes precedence over the environment variables:
 
 ```ruby
 # Set authentication credentials and optional subject prefix for Solid Errors
@@ -297,6 +316,32 @@ To be emailed only when an error is new, or when a resolved error occurs again,
 config.solid_errors.email_every_occurrence = false # defaults to true
 ```
 
+The subject names the error, and says when a resolved error has occurred again (`🔥 TimeoutError (reopened)`). To build it yourself, set `email_subject` to a proc. It is called with the error, the occurrence, and `reason`: `:created` or `:reopened` when the occurrence opened its error, `nil` for any other. `email_subject_prefix` is still added in front of what it returns.
+
+```ruby
+config.solid_errors.email_subject = ->(error:, occurrence:, reason:) {
+  # Counting up to this occurrence, rather than all of them, gives the same answer however late the email is sent
+  count = error.occurrences.where(id: ..occurrence.id).count
+  subject = "#{error.severity_emoji} #{error.exception_class}"
+
+  case reason
+  when :reopened then "🔄 REOPENED: #{subject}"
+  when :resolved then "✅ RESOLVED: #{error.exception_class}"
+  else count.in?([10, 100, 1_000]) ? "#{subject} (#{count.ordinalize} occurrence)" : subject
+  end
+}
+```
+
+The error email can also be sent for events of your own, such as an error being resolved or occurring unusually often. Whatever reason you pass reaches `email_subject`, as `:resolved` does in the example above:
+
+```ruby
+# config/initializers/solid_errors.rb
+ActiveSupport::Notifications.subscribe("error_resolved.solid_errors") do |event|
+  occurrence = event.payload[:error].occurrences.last
+  SolidErrors::ErrorMailer.error_occurred(occurrence, :resolved).deliver_later if occurrence && SolidErrors.send_emails?
+end
+```
+
 #### Lifecycle events
 
 Solid Errors publishes [Active Support notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) once each change is committed, so you can send errors to Slack, a webhook or anywhere else:
@@ -330,6 +375,21 @@ config.solid_errors.destroy_after = 30.days
 config.solid_errors.destroy_after = 6.months
 ```
 
+#### Checking the schema after an upgrade
+
+When a release changes the schema, [UPGRADE.md](UPGRADE.md) describes the migration. To have your test suite fail until you've applied it, assert that the errors database has everything the installed version uses:
+
+```ruby
+# test/solid_errors_test.rb
+require "test_helper"
+
+class SolidErrorsTest < ActiveSupport::TestCase
+  test "the errors database is up to date" do
+    assert SolidErrors.migrated?
+  end
+end
+```
+
 ### Examples
 
 There are only two screens in the dashboard.
@@ -412,6 +472,11 @@ You can always take control of the views by creating your own views and/or parti
 </html>
 ```
 
+
+### Locales
+
+The dashboard is written in English and renders in English whenever your app allows the `:en` locale. If `config.i18n.available_locales` leaves out `:en`, the dashboard renders in your app's locale instead, and you will need to provide the `datetime.distance_in_words.short` translations from [`config/locales/en.yml`](config/locales/en.yml) in that locale.
+
 ## Sponsors
 
 <p align="center">

data/app/controllers/solid_errors/errors_controller.rb

@@ -1,6 +1,6 @@
 module SolidErrors
   class ErrorsController < ApplicationController
-    around_action :force_english_locale!
+    around_action :use_english_when_available
 
     before_action :set_error, only: %i[show update destroy]
 
@@ -53,7 +53,10 @@ module SolidErrors
       @error = Error.find(params[:id])
     end
 
-    def force_english_locale!(&action)
+    # The dashboard's strings ship in English only; apps that don't allow :en keep their own locale
+    def use_english_when_available(&action)
+      return action.call unless I18n.locale_available?(:en)
+
       I18n.with_locale(:en, &action)
     end
 

data/app/mailers/solid_errors/error_mailer.rb

@@ -12,13 +12,15 @@ module SolidErrors
       helper_method :occurrence_url
     end
 
-    def error_occurred(occurrence)
+    # reason is passed on to SolidErrors.email_subject: :created or :reopened when the occurrence
+    # opened its error, or whatever an app sending this email for its own events passes
+    def error_occurred(occurrence, reason = nil)
       unless defined?(ActionMailer::Base)
         raise "ActionMailer is not available. Make sure that you require \"action_mailer/railtie\" in application.rb"
       end
       @occurrence = occurrence
       @error = occurrence.error
-      subject = "#{@error.severity_emoji} #{@error.exception_class}"
+      subject = SolidErrors.email_subject.call(error: @error, occurrence: @occurrence, reason: reason&.to_sym)
       if SolidErrors.email_subject_prefix.present?
         subject = [SolidErrors.email_subject_prefix, subject].join(" ").squish!
       end

data/app/models/solid_errors/occurrence.rb

@@ -35,7 +35,8 @@ module SolidErrors
     end
 
     def send_email
-      ErrorMailer.error_occurred(self).deliver_later
+      # Passed along rather than read off the occurrence, which the mailer job loads afresh without it
+      ErrorMailer.error_occurred(self, opens_error).deliver_later
     end
 
     def clear_resolved_errors

data/app/views/solid_errors/error_mailer/error_occurred.html.erb

@@ -1,7 +1,6 @@
 <html>
 <head>
   <title>Solid Errors | <%= @error.severity_emoji %> <%= @error.exception_class %></title>
-  <%= render "layouts/solid_errors/style" %>
   <style>
     body {
       padding: 20px;

data/lib/solid_errors/sanitizer.rb

@@ -49,6 +49,10 @@ module SolidErrors
       when String
         sanitize_string(data)
       else # all other objects
+        if (global_id = global_id(data))
+          return global_id
+        end
+
         klass = data.class
 
         begin
@@ -67,6 +71,15 @@ module SolidErrors
 
     attr_reader :max_depth
 
+    # A saved record is identified by its GlobalID (gid://app/User/1) instead of just its class
+    def global_id(object)
+      return unless object.respond_to?(:to_global_id)
+
+      object.to_global_id.to_s
+    rescue
+      nil
+    end
+
     def basic_object?(object)
       object.respond_to?(:to_s)
       false

data/lib/solid_errors/subscriber.rb

@@ -42,11 +42,31 @@ module SolidErrors
       SolidErrors::Occurrence.create(
         error_id: record.id,
         backtrace: error.backtrace&.join("\n"),
-        context: s(context),
+        context: s(readable_context(context)),
         opens_error: opens_error
       )
     end
 
+    # Rails puts the current controller or job in the context; keep what identifies the work, not the object
+    def readable_context(context)
+      context = context.dup
+      if defined?(ActionController::Metal) && (controller = context[:controller]).is_a?(ActionController::Metal)
+        context[:controller] = "#{controller.class.name}##{controller.action_name}"
+        context[:params] ||= controller.request.filtered_parameters.except("controller", "action")
+      end
+      if defined?(ActiveJob::Base) && (job = context[:job]).is_a?(ActiveJob::Base)
+        context[:job] = job.class.name
+        context[:job_id] ||= job.job_id
+        context[:queue] ||= job.queue_name
+        context[:arguments] ||= parameter_filter.filter(arguments: s(job.arguments))[:arguments]
+      end
+      context
+    end
+
+    def parameter_filter
+      ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+    end
+
     def s(data)
       Sanitizer.sanitize(data)
     end

data/lib/solid_errors/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidErrors
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/solid_errors.rb

@@ -11,11 +11,14 @@ module SolidErrors
   mattr_accessor :base_controller_class, default: "::ActionController::Base"
   mattr_writer :username
   mattr_writer :password
-  mattr_accessor :send_emails, default: false
-  mattr_accessor :email_from, default: "solid_errors@noreply.com"
-  mattr_accessor :email_to
-  mattr_accessor :email_subject_prefix
+  mattr_writer :send_emails, :email_from, :email_to, :email_subject_prefix, default: nil
   mattr_accessor :email_every_occurrence, default: true
+  # Builds the error email's subject, before email_subject_prefix. reason is :created or :reopened when
+  # the occurrence opened its error, nil for any other occurrence, or the app's own reason when it sends the email itself
+  mattr_accessor :email_subject, default: ->(error:, occurrence:, reason:) {
+    subject = "#{error.severity_emoji} #{error.exception_class}"
+    (reason == :reopened) ? "#{subject} (reopened)" : subject
+  }
   mattr_accessor :destroy_after
   mattr_accessor :ignored_errors, default: []
   mattr_writer :url_helper_name, :url_options
@@ -33,6 +36,34 @@ module SolidErrors
       @password ||= ENV["SOLIDERRORS_PASSWORD"] || @@password
     end
 
+    # Each email setting falls back to its SOLIDERRORS_* environment variable when not configured
+    def send_emails
+      @@send_emails.nil? ? ActiveModel::Type::Boolean.new.cast(ENV["SOLIDERRORS_SEND_EMAILS"]) || false : @@send_emails
+    end
+
+    def email_from
+      @@email_from || ENV["SOLIDERRORS_EMAIL_FROM"] || "solid_errors@noreply.com"
+    end
+
+    def email_to
+      @@email_to || ENV["SOLIDERRORS_EMAIL_TO"]
+    end
+
+    def email_subject_prefix
+      @@email_subject_prefix || ENV["SOLIDERRORS_EMAIL_SUBJECT_PREFIX"]
+    end
+
+    # Whether the errors database has every table and column this version reads and writes.
+    # Assert it in your test suite to catch a schema change you haven't applied yet.
+    def migrated?
+      {
+        SolidErrors::Error => %w[exception_class message severity source resolved_at fingerprint created_at updated_at],
+        SolidErrors::Occurrence => %w[error_id backtrace context created_at updated_at]
+      }.all? do |model, columns|
+        model.table_exists? && (columns - model.column_names).empty?
+      end
+    end
+
     def send_emails?
       send_emails && email_to.present? && !ActiveSupport::IsolatedExecutionState[:solid_errors_without_emails]
     end
@@ -47,11 +78,11 @@ module SolidErrors
     end
 
     def url_helper_name
-      @url_helper_name ||= detect_url_helper_name
+      @@url_helper_name ||= detect_url_helper_name
     end
 
     def url_options
-      @url_options ||= detect_url_options
+      @@url_options ||= detect_url_options
     end
 
     private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_errors
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Stephen Margheim