rails_pulse 0.4.2 → 0.5.0.pre.1

data/app/controllers/rails_pulse/api/v1/coverage_controller.rb

@@ -0,0 +1,158 @@
+module RailsPulse
+  module Api
+    module V1
+      # What Rails Pulse knows, and how recently, so a caller can tell "nothing
+      # went wrong" from "nothing was recorded". Every other endpoint answers a
+      # question about the data; this one answers whether the data is there.
+      class CoverageController < BaseController
+        # A writer silent for longer than this is treated as not collecting,
+        # matching the window the dashboard and status task use.
+        LIVE_WINDOW = RailsPulse::WriterHeartbeat::LIVE_WINDOW
+
+        # Hourly summaries fall behind by up to an hour in normal operation,
+        # so staleness is measured past that.
+        SUMMARY_GRACE = 2.hours
+
+        def show
+          render json: {
+            as_of: Time.current.utc.iso8601,
+            telemetry: telemetry,
+            summaries: summaries,
+            retention: retention,
+            collection: collection
+          }
+        end
+
+        private
+
+        # The newest and oldest record of each kind. An empty pair means
+        # nothing of that kind has been recorded — not that nothing happened.
+        def telemetry
+          config = RailsPulse.configuration
+          {
+            requests:   config.enabled ? span(RailsPulse::Request, :occurred_at) : untracked("config.enabled is false"),
+            job_runs:   config.track_jobs ? span(RailsPulse::JobRun, :occurred_at) : untracked("config.track_jobs is false"),
+            exceptions: exception_span
+          }
+        end
+
+        def untracked(reason)
+          { tracked: false, reason: reason }
+        end
+
+        def span(model, column)
+          oldest = model.minimum(column)
+          newest = model.maximum(column)
+          {
+            oldest: oldest&.utc&.iso8601,
+            newest: newest&.utc&.iso8601,
+            count: model.count,
+            tracked: true
+          }
+        end
+
+        def exception_span
+          return untracked("config.track_exceptions is false") unless RailsPulse.configuration.track_exceptions
+          return untracked("the exception tables are missing; run the upgrade generator") unless RailsPulse::ExceptionOccurrence.table_exists?
+
+          span(RailsPulse::ExceptionOccurrence, :occurred_at)
+        end
+
+        # Aggregated data outlives raw records, so a question about a window
+        # older than raw retention is answered from here or not at all.
+        def summaries
+          latest = RailsPulse::Summary.overall_requests.for_period_type("hour").maximum(:period_end)
+          earliest = RailsPulse::Summary.overall_requests.for_period_type("hour").minimum(:period_start)
+
+          {
+            hourly_from: earliest&.utc&.iso8601,
+            hourly_through: latest&.utc&.iso8601,
+            stale: latest.nil? || (Time.current - latest) > SUMMARY_GRACE,
+            note: summary_note(latest)
+          }
+        end
+
+        def summary_note(latest)
+          return "RailsPulse::SummaryJob has never run, so no window can be answered from summaries." if latest.nil?
+
+          age_hours = ((Time.current - latest) / 1.hour).round
+          return nil if age_hours <= (SUMMARY_GRACE / 1.hour)
+
+          "RailsPulse::SummaryJob is about #{age_hours}h behind, so recent windows are incomplete."
+        end
+
+        # What the configuration will keep, which bounds every question that
+        # can still be asked.
+        def retention
+          config = RailsPulse.configuration
+          {
+            raw_records: duration_label(config.full_retention_period),
+            hourly_summaries: duration_label(config.hourly_summary_retention),
+            events: duration_label(config.event_retention_period),
+            archiving_enabled: config.archiving_enabled
+          }
+        end
+
+        def duration_label(value)
+          return nil if value.nil?
+
+          seconds = value.respond_to?(:to_i) ? value.to_i : nil
+          seconds ? { seconds: seconds, days: (seconds / 86_400.0).round(2) } : nil
+        end
+
+        # Gaps: requests a writer dropped because its queue was full, which
+        # means the numbers understate what happened. A writer that has gone
+        # quiet is not one: it starts with a process's first tracked request
+        # and a new one starts on the next, so a missing heartbeat means
+        # nothing has been queued, not that something was lost.
+        def collection
+          unless RailsPulse.configuration.async
+            return {
+              known: false,
+              gap_suspected: false,
+              reason: "config.async is false, so requests are written inline: nothing is queued or dropped, " \
+                      "and no writer heartbeat is recorded"
+            }
+          end
+
+          unless RailsPulse::Event.table_available?
+            return { known: false, reason: "the events table is missing, so writer heartbeats are not recorded" }
+          end
+
+          stats = RailsPulse::WriterHeartbeat.summary(window: 1.hour)
+          last_seen = stats[:last_sampled_at]
+
+          {
+            known: true,
+            live_writers: stats[:processes],
+            queue_depth: stats[:queue_depth],
+            queue_size: stats[:queue_size],
+            dropped_last_hour: stats[:dropped],
+            last_heartbeat_at: last_seen&.utc&.iso8601,
+            gap_suspected: gap_suspected?(stats, last_seen),
+            note: collection_note(stats, last_seen)
+          }
+        end
+
+        def gap_suspected?(stats, _last_seen)
+          stats[:dropped].positive?
+        end
+
+        def collection_note(stats, last_seen)
+          notes = []
+          if last_seen.nil?
+            notes << "No writer heartbeat is on record. A writer starts with a process's first tracked request, " \
+                     "so the app has had no tracked web traffic, or its web processes are not running."
+          elsif (Time.current - last_seen) > LIVE_WINDOW
+            notes << "No writer has reported since #{last_seen.utc.iso8601}, so no request has been queued since " \
+                     "then: the app has had no tracked web traffic, or its web processes are not running."
+          end
+          if stats[:dropped].positive?
+            notes << "#{stats[:dropped]} request(s) were dropped in the last hour because the writer queue was full, so counts understate traffic."
+          end
+          notes.any? ? notes.join(" ") : nil
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/deployments_controller.rb

@@ -0,0 +1,24 @@
+module RailsPulse
+  module Api
+    module V1
+      class DeploymentsController < BaseController
+        def index
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          collection = RailsPulse::Deployment.recent.order(id: :desc)
+          collection = collection.where(started_at: since_start..) if since_start
+          collection = collection.where(started_at: ..until_end) if until_end
+
+          data, meta = paginated(collection)
+
+          render json: {
+            data: data.map { |deployment| DeploymentSerializer.serialize(deployment) },
+            meta: meta
+          }
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/exceptions_controller.rb

@@ -0,0 +1,76 @@
+module RailsPulse
+  module Api
+    module V1
+      # Exception groups: one row per distinct exception class and location,
+      # with its lifecycle status and how often and how recently it fired.
+      # This is what an agent or a desktop notifier reads to answer "what is
+      # broken right now?" — the raw 5xx request list under /requests cannot
+      # say which exception it was, only that the response failed.
+      class ExceptionsController < BaseController
+        STATUSES     = RailsPulse::ExceptionGroup::STATUSES
+        SORT_COLUMNS = %w[last_seen_at first_seen_at occurrence_count].freeze
+        DEFAULT_OCCURRENCES = 5
+        MAX_OCCURRENCES     = 20
+
+        rescue_from ActiveRecord::RecordNotFound do
+          render json: { error: "No exception group with id #{params[:id]}" }, status: :not_found
+        end
+
+        def index
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          status = params[:status].presence
+          if status && !STATUSES.include?(status)
+            return render json: { error: "Invalid status. Valid values: #{STATUSES.join(', ')}" }, status: :bad_request
+          end
+
+          sort = params[:sort].presence || "last_seen_at"
+          unless SORT_COLUMNS.include?(sort)
+            return render json: { error: "Invalid sort. Valid values: #{SORT_COLUMNS.join(', ')}" }, status: :bad_request
+          end
+
+          collection = RailsPulse::ExceptionGroup.order(sort => :desc, id: :desc)
+          collection = collection.where(status: status) if status
+          collection = collection.where(last_seen_at: since_start..) if since_start
+          collection = collection.where(last_seen_at: ..until_end) if until_end
+          collection = apply_search(collection)
+
+          data, meta = paginated(collection)
+          render json: { data: data.map { |group| ExceptionGroupSerializer.serialize(group) }, meta: meta }
+        end
+
+        # One group with its most recent occurrences: backtrace, request and
+        # params for each. This is what an agent reads to find the cause,
+        # so it carries everything the dashboard's exception page shows.
+        def show
+          group = RailsPulse::ExceptionGroup.find(params[:id])
+          count = integer_param(:occurrences, DEFAULT_OCCURRENCES, 1..MAX_OCCURRENCES)
+          occurrences = group.occurrences.order(occurred_at: :desc, id: :desc).limit(count)
+
+          render json: {
+            data: ExceptionGroupSerializer.serialize(group).merge(
+              occurrences: occurrences.map { |occurrence| ExceptionOccurrenceSerializer.serialize(occurrence) }
+            )
+          }
+        end
+
+        private
+
+        # Case-insensitive substring match on the exception class or the
+        # app-code location it was raised from.
+        def apply_search(scope)
+          return scope unless params[:search].present?
+
+          term = RailsPulse::LikePattern.containing(params[:search].to_s.downcase)
+          scope.where(
+            "LOWER(exception_class) LIKE :term #{RailsPulse::LikePattern::CLAUSE} " \
+            "OR LOWER(location) LIKE :term #{RailsPulse::LikePattern::CLAUSE}",
+            term: term
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/job_runs_controller.rb

@@ -0,0 +1,34 @@
+module RailsPulse
+  module Api
+    module V1
+      class JobRunsController < BaseController
+        def index
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          collection = RailsPulse::JobRun.includes(:job).order(occurred_at: :desc, id: :desc)
+          collection = collection.where(occurred_at: since_start..) if since_start
+          collection = collection.where(occurred_at: ..until_end) if until_end
+
+          status = params[:status].presence
+          if status == "failed"
+            collection = collection.failed
+          elsif status
+            unless RailsPulse::JobRun::STATUSES.include?(status)
+              return render json: { error: "Invalid status. Valid values: #{RailsPulse::JobRun::STATUSES.join(', ')}" }, status: :bad_request
+            end
+            collection = collection.where(status: status)
+          end
+
+          if params[:job].present?
+            collection = collection.joins(:job).where(rails_pulse_jobs: { name: params[:job] })
+          end
+
+          data, meta = paginated(collection)
+          render json: { data: data.map { |run| JobRunSerializer.serialize(run) }, meta: meta }
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/jobs_controller.rb

@@ -0,0 +1,172 @@
+module RailsPulse
+  module Api
+    module V1
+      class JobsController < BaseController
+        STATUSES = %w[failed].freeze
+
+        def index
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          collection = RailsPulse::Job.all.order(:name, :id)
+          collection = collection.where(name: params[:job]) if params[:job].present?
+
+          status = params[:status].presence
+          if status && !STATUSES.include?(status)
+            return render json: { error: "Invalid status. Valid values: #{STATUSES.join(', ')}" }, status: :bad_request
+          end
+
+          return render_windowed(collection, since_start, until_end, failed_only: status == "failed") if since_start || until_end
+
+          collection = collection.with_failures if status == "failed"
+          data, meta = paginated(collection)
+          render json: { data: data.map { |job| JobSerializer.serialize(job) }, meta: meta }
+        end
+
+        private
+
+        # Job rows carry lifetime counters, so a windowed question is answered
+        # from the per-job summaries the summary service writes each period,
+        # plus the raw runs recorded since the last period it summarized.
+        # Returning the lifetime numbers instead would answer a different
+        # question without saying so.
+        def render_windowed(collection, since_start, until_end, failed_only:)
+          until_end ||= Time.current
+          since_start ||= until_end - 24.hours
+
+          # Hourly rows are pruned at hourly_summary_retention, so a window
+          # reaching past that is read from daily rows for its whole length:
+          # reading the hourly rows that survive would count only part of it.
+          period_type = since_start >= RailsPulse.configuration.hourly_summary_retention.ago ? "hour" : "day"
+
+          # Periods are bucketed in the application's time zone, so the window
+          # is widened to that zone's period boundaries, not UTC ones.
+          from = RailsPulse::Summary.normalize_period_start(period_type, since_start.in_time_zone)
+          summarized_through = summarized_through(period_type)
+          summary_to = summarized_through ? [ summarized_through, period_ceiling(period_type, until_end) ].min : from
+          summary_to = from if summary_to < from
+
+          # The runs after the last summarized period are not in any summary
+          # yet, so they are counted from the raw rows. Cleanup never deletes a
+          # run that has not been summarized, so they are all still there.
+          live_from = [ from, summary_to ].max
+          live = live_from < until_end ? live_rows(collection, live_from, until_end) : {}
+          summarized = summary_to > from ? summary_rows(collection, period_type, from, summary_to) : {}
+
+          jobs = RailsPulse::Job.where(id: summarized.keys | live.keys).index_by(&:id)
+          rows = jobs.values.map { |job| [ job, stats_for(summarized[job.id], live[job.id]) ] }
+          rows.select! { |_, stats| stats[:failures_count].positive? } if failed_only
+          rows.sort_by! { |job, _| [ job.name.to_s, job.id ] }
+
+          page = rows.drop(offset).first(limit)
+
+          window = { since: from.utc.iso8601, until: [ summary_to, until_end ].max.utc.iso8601, period_type: period_type }
+          window[:summarized_through] = summarized_through&.utc&.iso8601
+          window[:live_from] = live_from.utc.iso8601 if live_from < until_end
+
+          render json: {
+            data: page.map { |job, stats| JobSerializer.serialize(job, stats: stats) },
+            meta: { total: rows.size, limit: limit, offset: offset, window: window }
+          }
+        end
+
+        # The end of the newest period SummaryJob has written. The overall
+        # request row is written every period even when nothing ran, so it
+        # advances on an app that records no requests between job runs.
+        def summarized_through(period_type)
+          latest = [
+            RailsPulse::Summary.overall_requests.for_period_type(period_type).maximum(:period_start),
+            RailsPulse::Summary.for_jobs.for_period_type(period_type).maximum(:period_start)
+          ].compact.max
+          latest && advance(period_type, latest.in_time_zone)
+        end
+
+        def summary_rows(collection, period_type, from, to)
+          RailsPulse::Summary
+            .for_jobs
+            .where(period_type: period_type, period_start: from...to)
+            .where(summarizable_id: collection.select(:id))
+            .group(:summarizable_id)
+            .select(
+              "summarizable_id, COUNT(*) AS periods, SUM(count) AS runs, SUM(error_count) AS failures, " \
+              "SUM(total_duration) AS total_duration, MIN(min_duration) AS min_duration, " \
+              "MAX(max_duration) AS max_duration, MAX(p95_duration) AS p95_duration, " \
+              "MAX(p99_duration) AS p99_duration"
+            )
+            .index_by(&:summarizable_id)
+        end
+
+        # Counted the way SummaryService counts a period: finished runs only,
+        # and anything other than success is a failure.
+        def live_rows(collection, from, to)
+          failure = "CASE WHEN status = #{RailsPulse::JobRun.connection.quote('success')} THEN 0 ELSE 1 END"
+
+          RailsPulse::JobRun
+            .where(occurred_at: from...to, status: RailsPulse::JobRun::FINAL_STATUSES)
+            .where(job_id: collection.select(:id))
+            .group(:job_id)
+            .select(
+              "job_id, COUNT(*) AS runs, SUM(#{failure}) AS failures, SUM(duration) AS total_duration, " \
+              "MIN(duration) AS min_duration, MAX(duration) AS max_duration"
+            )
+            .index_by(&:job_id)
+        end
+
+        def stats_for(summarized, live)
+          sources = [ summarized, live ].compact
+          runs = sources.sum { |row| row.runs.to_i }
+          failures = sources.sum { |row| row.failures.to_i }
+          total_duration = sources.sum { |row| row.total_duration.to_f }
+
+          stats = {
+            runs_count:     runs,
+            failures_count: failures,
+            failure_rate:   runs > 0 ? ((failures.to_f / runs) * 100).round(2) : 0.0,
+            avg_duration:   runs > 0 ? (total_duration / runs).round(2) : nil,
+            min_duration:   sources.filter_map { |row| row.min_duration&.to_f }.min&.round(2),
+            max_duration:   sources.filter_map { |row| row.max_duration&.to_f }.max&.round(2)
+          }
+
+          # A percentile is a property of a distribution, and the distribution
+          # behind each period is not kept, so percentiles from several periods
+          # cannot be combined. They are reported only when one summarized
+          # period holds every run in the window.
+          periods = summarized&.periods.to_i
+          if periods == 1 && live.nil?
+            stats[:p95_duration] = summarized.p95_duration&.to_f&.round(2)
+            stats[:p99_duration] = summarized.p99_duration&.to_f&.round(2)
+          else
+            stats[:percentiles_note] = percentiles_note(periods, live)
+          end
+
+          stats
+        end
+
+        def percentiles_note(periods, live)
+          if live && periods.zero?
+            "Omitted: these runs have not been summarized yet, and percentiles are read from summaries. " \
+              "Request a window ending at or before meta.window.summarized_through for p95 and p99."
+          else
+            spans = live ? "#{periods} summary period(s) and runs not yet summarized" : "#{periods} summary periods"
+            "Omitted: the window spans #{spans}, which cannot be combined into one percentile. " \
+              "Request a window covering a single summarized period for p95 and p99."
+          end
+        end
+
+        # The start of the period after the one `time` falls in, or `time`
+        # itself when it is already on a boundary.
+        def period_ceiling(period_type, time)
+          start = RailsPulse::Summary.normalize_period_start(period_type, time.in_time_zone)
+          start == time ? start : advance(period_type, start)
+        end
+
+        # Calendar arithmetic in the application's zone, so a day is a day
+        # across a DST change.
+        def advance(period_type, time)
+          period_type == "hour" ? time + 1.hour : time + 1.day
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/queries_controller.rb

@@ -0,0 +1,114 @@
+module RailsPulse
+  module Api
+    module V1
+      class QueriesController < BaseController
+        SORT_COLUMNS = %w[total_duration avg_duration executions max_duration].freeze
+
+        def index
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          sort = params[:sort].presence
+          if sort && !SORT_COLUMNS.include?(sort)
+            return render json: { error: "Invalid sort. Valid values: #{SORT_COLUMNS.join(', ')}" }, status: :bad_request
+          end
+
+          # A route filter is answered from operations, which only the stats
+          # path reads, so it implies a window the same way a sort does.
+          if since_start || until_end || sort || params[:route].present?
+            since_start ||= 24.hours.ago if until_end.nil?
+            render_with_stats(since_start..until_end, sort || "total_duration")
+          else
+            data, meta = paginated(RailsPulse::Query.all.order(:id))
+            render json: { data: data.map { |query| QuerySerializer.serialize(query) }, meta: meta }
+          end
+        end
+
+        private
+
+        def render_with_stats(range, sort)
+          base = RailsPulse::Operation.where.not(query_id: nil).where(occurred_at: range)
+          base = apply_route_filter(base)
+          total = base.distinct.count(:query_id)
+
+          rows = base
+            .group(:query_id)
+            # Qualified: the route filter joins requests, which has its own
+            # duration column.
+            .select(
+              "rails_pulse_operations.query_id, COUNT(*) AS executions, " \
+              "AVG(rails_pulse_operations.duration) AS avg_duration, " \
+              "MAX(rails_pulse_operations.duration) AS max_duration, " \
+              "SUM(rails_pulse_operations.duration) AS total_duration, " \
+              "MAX(rails_pulse_operations.repetition_count) AS max_repetition_count"
+            )
+            # query_id breaks ties so offset pages neither repeat nor skip rows.
+            .order(Arel.sql("#{sort} DESC, rails_pulse_operations.query_id ASC"))
+            .limit(limit)
+            .offset(offset)
+            .to_a
+
+          queries = RailsPulse::Query.where(id: rows.map(&:query_id)).index_by(&:id)
+          locations = source_locations(base, rows.map(&:query_id))
+          data = rows.filter_map do |row|
+            query = queries[row.query_id]
+            QuerySerializer.serialize(query, stats: stats_for(row, locations[row.query_id])) if query
+          end
+
+          render json: { data: data, meta: { total: total, limit: limit, offset: offset } }
+        end
+
+        # Restricts the operations to those issued while serving one route, so
+        # "what is slow inside this endpoint" is one call rather than a guess.
+        # A bare integer is a route id; anything else matches the controller
+        # action or path the way the routes endpoint's search does.
+        def apply_route_filter(scope)
+          route = params[:route].to_s
+          return scope if route.blank?
+
+          scope = scope.joins(request: :route)
+          return scope.where(rails_pulse_routes: { id: route.to_i }) if route.match?(/\A\d+\z/)
+
+          term = RailsPulse::LikePattern.containing(route.downcase)
+          scope.where(
+            "LOWER(rails_pulse_routes.controller_action) LIKE :term #{RailsPulse::LikePattern::CLAUSE} " \
+            "OR LOWER(rails_pulse_routes.path) LIKE :term #{RailsPulse::LikePattern::CLAUSE}",
+            term: term
+          )
+        end
+
+        # Where each query was issued from, most frequent first. Without this a
+        # caller knows a query is slow but not which line of code runs it.
+        # Counted over the same operations as the stats, so with a route filter
+        # a query shared across the app names the call sites in that endpoint.
+        def source_locations(operations, query_ids, per_query: 3)
+          return {} if query_ids.empty?
+
+          counts = operations
+            .where(query_id: query_ids)
+            .where.not(codebase_location: nil)
+            .group("rails_pulse_operations.query_id", "rails_pulse_operations.codebase_location")
+            .count
+
+          counts.group_by { |(query_id, _), _| query_id }.transform_values do |entries|
+            entries.sort_by { |(_, location), count| [ -count, location ] }
+              .first(per_query)
+              .map { |(_, location), count| { location: location, count: count } }
+          end
+        end
+
+        def stats_for(row, locations)
+          {
+            executions:           row.executions.to_i,
+            avg_duration_ms:      row.avg_duration.to_f.round(1),
+            max_duration_ms:      row.max_duration.to_f.round(1),
+            total_duration_ms:    row.total_duration.to_f.round(1),
+            max_repetition_count: row.max_repetition_count&.to_i,
+            source_locations:     locations || []
+          }
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_pulse/api/v1/requests_controller.rb

@@ -0,0 +1,58 @@
+module RailsPulse
+  module Api
+    module V1
+      class RequestsController < BaseController
+        STATUS_CLASS = /\A(\d)xx\z/
+        STATUS_CODE  = /\A\d{3}\z/
+
+        def index
+          collection = RailsPulse::Request.all.order(occurred_at: :desc, id: :desc)
+
+          parsed_range = time_range
+          return unless parsed_range
+          since_start, until_end = parsed_range
+
+          collection = collection.where(occurred_at: since_start..) if since_start
+          collection = collection.where(occurred_at: ..until_end) if until_end
+          collection = apply_route_filter(collection)
+          collection = apply_status_filter(collection)
+          return if performed?
+
+          data, meta = paginated(collection)
+          render json: { data: data.map { |request| RequestSerializer.serialize(request) }, meta: meta }
+        end
+
+        private
+
+        # Case-insensitive substring match on the request's controller action
+        # or its route's path, so an agent can profile one endpoint without
+        # paging through every request in the window.
+        def apply_route_filter(scope)
+          return scope unless params[:route].present?
+
+          term = RailsPulse::LikePattern.containing(params[:route].to_s.downcase)
+          scope.joins(:route).where(
+            "LOWER(rails_pulse_requests.controller_action) LIKE :term #{RailsPulse::LikePattern::CLAUSE} " \
+            "OR LOWER(rails_pulse_routes.path) LIKE :term #{RailsPulse::LikePattern::CLAUSE}",
+            term: term
+          )
+        end
+
+        def apply_status_filter(scope)
+          return scope unless params[:status].present?
+
+          status = params[:status].to_s.downcase
+          if (match = status.match(STATUS_CLASS))
+            digit = match[1].to_i
+            scope.where(status: (digit * 100)...((digit + 1) * 100))
+          elsif status.match?(STATUS_CODE)
+            scope.where(status: status.to_i)
+          else
+            render json: { error: "Invalid status. Use a three-digit code (500) or a class (5xx)" }, status: :bad_request
+            scope
+          end
+        end
+      end
+    end
+  end
+end