good_job 4.19.2 → 4.21.1

data/app/charts/good_job/performance_range.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+module GoodJob
+  class PerformanceRange
+    PARAMETER_KEYS = %w[chart_range chart_start chart_end].freeze
+    TIME_ZONE_PARAMETER_KEY = "chart_time_zone"
+    INPUT_PARAMETER_KEYS = [*PARAMETER_KEYS, TIME_ZONE_PARAMETER_KEY].freeze
+    DEFAULT_KEY = "24h"
+    MAXIMUM_TIME_SERIES_COORDINATES = 30
+    MAXIMUM_TIME_ZONE_LENGTH = 255
+    # Restrict custom bounds to portable four-digit years in the timezone used by the page.
+    MINIMUM_YEAR = 1000
+    MAXIMUM_YEAR = 9999
+    MINIMUM_LOCAL_VALUE = "1000-01-01T00:00:00"
+    MAXIMUM_LOCAL_VALUE = "9999-12-31T23:59:59"
+    TIMESTAMP_PATTERN = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+    LOCAL_TIMESTAMP_PATTERN = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?\z/
+
+    OPTIONS = {
+      "1h" => {
+        label: "1h",
+        duration: 1.hour,
+        interval_seconds: 5.minutes.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "6h" => {
+        label: "6h",
+        duration: 6.hours,
+        interval_seconds: 15.minutes.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "24h" => {
+        label: "24h",
+        duration: 24.hours,
+        interval_seconds: 1.hour.to_i,
+        label_format: "%H:%M",
+        label_style: "time",
+      },
+      "7d" => {
+        label: "7d",
+        duration: 24.hours * 7,
+        interval_seconds: 6.hours.to_i,
+        label_format: "%b %-d %H:%M",
+        label_style: "date_time",
+      },
+    }.freeze
+
+    # All candidates become integer seconds. The 30-day and 365-day scales are fixed elapsed
+    # durations for readable long-range charts, not calendar month or year aggregation.
+    SEMANTIC_INTERVALS = [
+      *[1, 2, 5, 10, 15, 30].map(&:seconds),
+      *[1, 2, 5, 10, 15, 30].map(&:minutes),
+      *[1, 2, 3, 6, 12].map(&:hours),
+      *[1, 2, 3, 5, 7, 14].map(&:days),
+      *[1, 2, 3, 6].map { |multiple| multiple * 30.days },
+      *[1, 2, 5, 10, 20, 50, 100, 200, 500].map { |multiple| multiple * 365.days },
+    ].map(&:to_i).uniq.sort.freeze
+
+    attr_reader :end_time, :interval_seconds, :key, :label_format, :label_style, :start_time
+
+    def initialize(params = nil, query_string: nil, **parameter_keywords)
+      @params = params || parameter_keywords
+      @repeated_parameter_keys = repeated_parameter_keys(query_string)
+      @local_time_zone = local_time_zone
+      resolve
+    end
+
+    def apply(relation)
+      relation.where(scheduled_at: start_time...end_time)
+    end
+
+    def canonical_parameters?(query_parameters)
+      query_parameters.slice(*INPUT_PARAMETER_KEYS) == to_params
+    end
+
+    def chart_timestamp_label(timestamp)
+      timestamp.in_time_zone.strftime(label_format)
+    end
+
+    def chart_timestamp_labels(timestamps)
+      labels = timestamps.map { |timestamp| chart_timestamp_label(timestamp) }
+
+      labels.each_index.group_by { |index| labels[index] }.each_value do |indices|
+        next unless indices.many?
+
+        offsets = indices.map { |index| timestamps[index].in_time_zone.formatted_offset }
+        next unless offsets.uniq.many?
+
+        indices.zip(offsets).each do |index, offset|
+          labels[index] = "#{labels[index]} #{offset}"
+        end
+      end
+
+      labels
+    end
+
+    def canonical_timestamp(timestamp)
+      timestamp = timestamp.in_time_zone
+      # ISO 8601 cannot preserve the sub-minute historical offsets present in some IANA zones.
+      timestamp.utc_offset.remainder(60).zero? ? timestamp.iso8601 : timestamp.utc.iso8601
+    end
+
+    def custom?
+      key.nil?
+    end
+
+    def custom_params
+      {
+        "chart_start" => canonical_timestamp(start_time),
+        "chart_end" => canonical_timestamp(end_time),
+      }
+    end
+
+    def default?
+      to_params.empty?
+    end
+
+    def end_label
+      range_label(end_time)
+    end
+
+    def end_local_value
+      local_value(end_time)
+    end
+
+    def navigation_params
+      return to_params unless key
+
+      # A preset is a relative definition; navigation also carries this evaluated instance.
+      {
+        "chart_range" => key,
+        "chart_start" => canonical_timestamp(start_time),
+        "chart_end" => canonical_timestamp(end_time),
+      }
+    end
+
+    def options
+      OPTIONS.map { |option_key, option| { key: option_key, label: option.fetch(:label) } }
+    end
+
+    def reload_params
+      return to_params if custom? || default?
+
+      { "chart_range" => key }
+    end
+
+    def start_end_binds
+      [
+        query_attribute("start_time", start_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("end_time", end_time, ActiveRecord::Type::DateTime.new),
+      ]
+    end
+
+    def start_label
+      range_label(start_time)
+    end
+
+    def start_local_value
+      local_value(start_time)
+    end
+
+    # Keep this order in sync with the $1/$2/$3 placeholders in PerformanceIndexChart.
+    def time_series_binds
+      [
+        query_attribute("series_start_time", series_start_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("series_end_time", series_end_time, ActiveRecord::Type::DateTime.new),
+        query_attribute("interval_seconds", interval_seconds, ActiveRecord::Type::Integer.new(limit: 8)),
+      ]
+    end
+
+    def time_series_bucket_sql(column_name, start_expression:, interval_expression:)
+      column_sql = GoodJob::Job.adapter_class.quote_column_name(column_name)
+
+      <<~SQL.squish
+        #{start_expression} +
+        FLOOR(EXTRACT(EPOCH FROM (#{column_sql} - #{start_expression})) / #{interval_expression}) *
+        #{interval_expression} * INTERVAL '1 second'
+      SQL
+    end
+
+    def time_series_coordinate_count
+      coordinate_count(interval_seconds)
+    end
+
+    def to_params
+      @canonical_params.dup
+    end
+
+    private
+
+    def align_time(time, interval = interval_seconds)
+      # JRuby can misreport rational epochs for extreme years even when integer seconds are correct.
+      (time - (time.to_i % interval) - time.subsec).utc
+    end
+
+    def aligned_epoch_seconds(time, interval)
+      time.to_i.div(interval) * interval
+    end
+
+    def coordinate_count(interval)
+      first_coordinate = aligned_epoch_seconds(start_time, interval)
+      last_coordinate = aligned_epoch_seconds(end_time - Rational(1, 1_000_000), interval)
+
+      ((last_coordinate - first_coordinate) / interval) + 1
+    end
+
+    def custom_times
+      parsed_start = parse_time("chart_start", @params[:chart_start])
+      parsed_end = parse_time("chart_end", @params[:chart_end])
+      return unless parsed_start && parsed_end && parsed_start < parsed_end
+
+      [parsed_start, parsed_end]
+    end
+
+    def custom_interval_seconds
+      # Fall back to the coarsest interval rather than raising: MINIMUM_YEAR/MAXIMUM_YEAR bound the
+      # widest possible range today, but nothing enforces that bound against SEMANTIC_INTERVALS.last.
+      SEMANTIC_INTERVALS.find do |interval|
+        coordinate_count(interval) <= MAXIMUM_TIME_SERIES_COORDINATES
+      end || SEMANTIC_INTERVALS.last
+    end
+
+    def custom_label_options
+      elapsed_seconds = end_time - start_time
+
+      if elapsed_seconds >= 365.days
+        { label_format: "%b %-d, %Y %H:%M", label_style: "date_time_year" }
+      elsif elapsed_seconds >= 24.hours
+        { label_format: "%b %-d %H:%M", label_style: "date_time" }
+      elsif interval_seconds < 1.minute
+        { label_format: "%H:%M:%S", label_style: "time_seconds" }
+      else
+        { label_format: "%H:%M", label_style: "time" }
+      end
+    end
+
+    def parse_time(parameter_key, value)
+      return if @repeated_parameter_keys.include?(parameter_key)
+      return unless value.is_a?(String)
+
+      timestamp = if TIMESTAMP_PATTERN.match?(value)
+                    Time.iso8601(value)
+                  elsif (local_match = LOCAL_TIMESTAMP_PATTERN.match(value))
+                    parse_local_time(parameter_key, local_match)
+                  end
+      return unless timestamp
+      return unless timestamp.to_f.finite?
+
+      timestamp = timestamp.in_time_zone.change(usec: 0)
+      return unless timestamp.year.between?(MINIMUM_YEAR, MAXIMUM_YEAR)
+
+      timestamp
+    rescue ArgumentError, RangeError
+      nil
+    end
+
+    def repeated_parameter_keys(query_string)
+      return [] if query_string.blank?
+
+      keys = URI.decode_www_form(query_string).filter_map do |key, _value|
+        key if INPUT_PARAMETER_KEYS.include?(key)
+      end
+      keys.tally.select { |_key, count| count > 1 }.keys
+    rescue ArgumentError
+      INPUT_PARAMETER_KEYS
+    end
+
+    def query_attribute(name, value, type)
+      ActiveRecord::Relation::QueryAttribute.new(name, value, type)
+    end
+
+    def local_value(time)
+      time.in_time_zone.strftime("%Y-%m-%dT%H:%M:%S")
+    end
+
+    def parse_local_time(parameter_key, match)
+      return unless @local_time_zone
+
+      components = match.captures
+      components[-1] ||= "0"
+      numeric_components = components.map { |component| Integer(component, 10) }
+      local_time = Time.utc(*numeric_components)
+      normalized_value = format("%04d-%02d-%02dT%02d:%02d:%02d", *numeric_components)
+      return unless local_time.strftime("%Y-%m-%dT%H:%M:%S") == normalized_value
+
+      periods = @local_time_zone.tzinfo.periods_for_local(local_time)
+      return if periods.empty?
+
+      # A local input cannot carry an offset. Include both repeated fall-back occurrences
+      # by resolving starts to the earlier instant and ends to the later instant.
+      instants = periods.map do |period|
+        (local_time - period.utc_total_offset).in_time_zone
+      end
+      parameter_key == "chart_end" ? instants.max : instants.min
+    end
+
+    def local_time_zone
+      return if @repeated_parameter_keys.include?(TIME_ZONE_PARAMETER_KEY)
+
+      value = @params[TIME_ZONE_PARAMETER_KEY] || @params[TIME_ZONE_PARAMETER_KEY.to_sym]
+      return Time.zone if value.nil?
+      return unless value.is_a?(String) && value.bytesize <= MAXIMUM_TIME_ZONE_LENGTH
+      return unless /\A[A-Za-z0-9._+-]+(?:\/[A-Za-z0-9._+-]+)*\z/.match?(value)
+
+      tzinfo = TZInfo::Timezone.get(value)
+      ActiveSupport::TimeZone.create(value, nil, tzinfo)
+    rescue TZInfo::InvalidTimezoneIdentifier
+      nil
+    end
+
+    def range_label(time)
+      local_time = time.in_time_zone
+      format = label_style == "date_time_year" ? "%b %-d, %Y %H:%M:%S" : "%b %-d, %H:%M:%S"
+      label = local_time.strftime(format)
+
+      backward_clock_transition? ? "#{label} #{local_time.formatted_offset}" : label
+    end
+
+    # Intentionally checks Time.zone (the server-rendered zone), not @local_time_zone: this backs
+    # the initial server-rendered label, before any browser-zone enhancement. The client mirrors
+    # this same concept for its own currently-displayed zone in
+    # performance_range_controller.js#crossesBackwardClockTransition — keep both in sync in spirit
+    # (elapsed exact time vs. elapsed civil time) but each must use its own zone, not the other's.
+    def backward_clock_transition?
+      @_backward_clock_transition ||= end_time.in_time_zone.utc_offset < start_time.in_time_zone.utc_offset
+    end
+
+    def resolve
+      range_key = preset_key
+
+      if (times = custom_times)
+        @start_time, @end_time = times
+
+        # Do not attach a preset identity to tampered bounds with a different elapsed duration.
+        if range_key && end_time - start_time == OPTIONS.fetch(range_key).fetch(:duration)
+          @key = range_key
+          @canonical_params = navigation_params
+          options = OPTIONS.fetch(key)
+        else
+          @key = nil
+          @canonical_params = custom_params
+          @interval_seconds = custom_interval_seconds
+          options = custom_label_options
+        end
+      else
+        @key = range_key || DEFAULT_KEY
+        options = OPTIONS.fetch(key)
+        @end_time = current_end_time
+        @start_time = end_time - options.fetch(:duration)
+        @canonical_params = range_key ? { "chart_range" => key } : {}
+      end
+
+      @interval_seconds ||= options.fetch(:interval_seconds)
+      @label_format = options.fetch(:label_format)
+      @label_style = options.fetch(:label_style)
+    end
+
+    def preset_key
+      return if @repeated_parameter_keys.include?("chart_range")
+
+      value = @params[:chart_range]
+      value if value.is_a?(String) && OPTIONS.key?(value)
+    end
+
+    def series_end_time
+      align_time(end_time - Rational(1, 1_000_000))
+    end
+
+    def series_start_time
+      align_time(start_time)
+    end
+
+    def current_end_time
+      current_time = Time.current
+      current_time.usec.zero? ? current_time : current_time.ceil
+    end
+  end
+end

data/app/charts/good_job/performance_show_chart.rb

@@ -12,30 +12,33 @@ module GoodJob
       10**8 # About 3 years
     ].freeze
 
-    def initialize(job_class)
+    def initialize(job_class, range = GoodJob::PerformanceRange.new, metric = GoodJob::LatencyMetric.default)
       super()
       @job_class = job_class
+      @range = range
+      @metric = metric
     end
 
     def data
       table_name = GoodJob::Execution.table_name
 
       interval_entries = BUCKET_INTERVALS.map { "interval '#{_1}'" }.join(",")
+      bucket_expression = "WIDTH_BUCKET(#{@metric.expression}, ARRAY[#{interval_entries}])"
       sum_query = <<~SQL.squish
         SELECT
-          WIDTH_BUCKET(duration, ARRAY[#{interval_entries}]) as bucket_index,
-          COUNT(WIDTH_BUCKET(duration, ARRAY[#{interval_entries}])) AS count
+          #{bucket_expression} as bucket_index,
+          COUNT(#{bucket_expression}) AS count
         FROM #{table_name} sources
         WHERE
-          scheduled_at > $1::timestamp
+          scheduled_at >= $1::timestamp
           AND scheduled_at < $2::timestamp
           AND job_class = $3
-          AND duration IS NOT NULL
+          AND #{@metric.presence_sql}
         GROUP BY bucket_index
       SQL
 
       binds = [
-        *start_end_binds,
+        *@range.start_end_binds,
         @job_class,
       ]
       labels = BUCKET_INTERVALS.map { |interval| GoodJob::ApplicationController.helpers.format_duration(interval) }
@@ -59,6 +62,12 @@ module GoodJob
           }],
         },
         options: {
+          plugins: {
+            title: {
+              display: true,
+              text: @metric.histogram_title,
+            },
+          },
           scales: {
             y: {
               beginAtZero: true,

data/app/charts/good_job/scheduled_by_queue_chart.rb

@@ -17,8 +17,8 @@ module GoodJob
       # offset from UTC (e.g. IST +05:30). AR serializes Time binds as UTC, so the outer
       # date_trunc operates in UTC, and this predicate must match that.
       pushdown = <<~SQL.squish
-        "good_jobs"."scheduled_at" >= date_trunc('hour', ?::timestamp)
-        AND "good_jobs"."scheduled_at" < date_trunc('hour', ?::timestamp) + interval '1 hour'
+        #{GoodJob::Job.quoted_table_name}."scheduled_at" >= date_trunc('hour', ?::timestamp)
+        AND #{GoodJob::Job.quoted_table_name}."scheduled_at" < date_trunc('hour', ?::timestamp) + interval '1 hour'
       SQL
 
       inner_sql = @filter.filtered_query

data/app/controllers/good_job/cleaner_controller.rb

@@ -23,7 +23,7 @@ module GoodJob
         GoodJob::Job.discarded
                     .select(<<~SQL.squish)
                       job_class,
-                      count(id) AS failed,
+                      COUNT(*) AS failed,
                       COUNT(*) FILTER (WHERE "finished_at" > NOW() - INTERVAL '1 HOUR') AS last_1_hour,
                       COUNT(*) FILTER (WHERE "finished_at" > NOW() - INTERVAL '3 HOURS') AS last_3_hours,
                       COUNT(*) FILTER (WHERE "finished_at" > NOW() - INTERVAL '24 HOURS') AS last_24_hours,

data/app/controllers/good_job/performance_controller.rb

@@ -2,27 +2,46 @@
 
 module GoodJob
   class PerformanceController < ApplicationController
+    before_action :set_performance_range
+
     def index
-      @performances = GoodJob::Execution.group(:job_class).select("
-        job_class,
-        COUNT(*) AS executions_count,
-        AVG(duration) AS avg_duration,
-        MIN(duration) AS min_duration,
-        MAX(duration) AS max_duration
-      ").order(:job_class)
-
-      @queue_performances = GoodJob::Execution.group(:queue_name).select("
-        queue_name,
-        COUNT(*) AS executions_count,
-        AVG(duration) AS avg_duration,
-        MIN(duration) AS min_duration,
-        MAX(duration) AS max_duration
-      ").order(:queue_name)
+      executions = @performance_range.apply(GoodJob::Execution)
+      aggregates = GoodJob::LatencyMetric.table_aggregates_sql
+
+      @performances = executions.group(:job_class).select("job_class, #{aggregates}").order(:job_class)
+      @queue_performances = executions.group(:queue_name).select("queue_name, #{aggregates}").order(:queue_name)
+
+      @chart_data = GoodJob::PerformanceIndexChart.new(@performance_range, @chart_metric).data
     end
 
     def show
-      representative_job = GoodJob::Job.find_by!(job_class: params[:id])
+      representative_job = GoodJob::Job.find_by!(job_class: request.path_parameters.fetch(:id))
       @job_class = representative_job.job_class
+      @charts = GoodJob::LatencyMetric.options.to_h do |metric|
+        [metric.key, GoodJob::PerformanceShowChart.new(@job_class, @performance_range, metric).data]
+      end
+    end
+
+    private
+
+    def set_performance_range
+      locale = request.query_parameters["locale"]
+      @performance_range_context = locale.is_a?(String) ? { "locale" => locale } : {}
+      @performance_range = GoodJob::PerformanceRange.new(params, query_string: request.query_string)
+      # Only the index chart is metric-switchable; show renders every metric.
+      @chart_metric = GoodJob::LatencyMetric.from_params(params)
+      @chart_metric_params = action_name == "index" ? @chart_metric.to_params : {}
+      return if @performance_range.canonical_parameters?(request.query_parameters)
+
+      canonical_query = @performance_range.to_params.symbolize_keys
+      canonical_query[:locale] = @performance_range_context["locale"]
+      canonical_query.merge!(@chart_metric_params.symbolize_keys)
+      canonical_path = if action_name == "show"
+                         performance_path(request.path_parameters.fetch(:id), canonical_query)
+                       else
+                         performance_index_path(canonical_query)
+                       end
+      redirect_to canonical_path
     end
   end
 end

data/app/filters/good_job/base_filter.rb

@@ -13,15 +13,17 @@ module GoodJob
     end
 
     def records
-      after_id = params[:after_id]
-      after_at = params[:after_at].present? ? Time.zone.parse(params[:after_at]) : nil
-      limit = params.fetch(:limit, DEFAULT_LIMIT)
-
-      query_for_records.display_all(
-        ordered_by: ordered_by,
-        after_at: after_at,
-        after_id: after_id
-      ).limit(limit)
+      @_records ||= begin
+        after_id = params[:after_id]
+        after_at = params[:after_at].present? ? Time.zone.parse(params[:after_at]) : nil
+        limit = params.fetch(:limit, DEFAULT_LIMIT)
+
+        query_for_records.display_all(
+          ordered_by: ordered_by,
+          after_at: after_at,
+          after_id: after_id
+        ).limit(limit)
+      end
     end
 
     def last
@@ -76,7 +78,7 @@ module GoodJob
 
     def next_page_params
       order_column = ordered_by.first
-      last_record = records.last
+      last_record = last
 
       {
         after_at: last_record&.send(order_column)&.iso8601(6),

data/app/filters/good_job/batches_filter.rb

@@ -2,16 +2,26 @@
 
 module GoodJob
   class BatchesFilter < BaseFilter
+    def job_count(batch)
+      job_counts.fetch(batch.id, 0)
+    end
+
     def filtered_query(_filtered_params = params)
       base_query
     end
 
     def query_for_records
-      default_base_query
+      base_query
     end
 
     def default_base_query
-      GoodJob::BatchRecord.includes(:jobs)
+      GoodJob::BatchRecord.all
+    end
+
+    private
+
+    def job_counts
+      @_job_counts ||= GoodJob::Job.where(batch_id: records.map(&:id)).group(:batch_id).count
     end
   end
 end

data/app/frontend/good_job/application.js

@@ -12,6 +12,8 @@ import AsyncValuesController from "async_values_controller";
 Stimulus.register("async-values", AsyncValuesController);
 import ChartController from "chart_controller";
 Stimulus.register("chart", ChartController);
+import PerformanceRangeController from "performance_range_controller";
+Stimulus.register("performance-range", PerformanceRangeController);
 import LivePollController from "live_poll_controller";
 Stimulus.register("live-poll", LivePollController);
 import CheckboxToggleController from "checkbox_toggle_controller";

data/app/frontend/good_job/modules/async_values_controller.js

@@ -7,8 +7,15 @@ export default class extends Controller {
   }
   static targets = ["value"]
 
+  #onLivePollRefresh = () => this.#fetch();
+
   connect() {
     this.#fetch();
+    document.addEventListener("good_job:live-poll-refreshed", this.#onLivePollRefresh);
+  }
+
+  disconnect() {
+    document.removeEventListener("good_job:live-poll-refreshed", this.#onLivePollRefresh);
   }
 
   async #fetch() {