rails_pulse 0.4.2 → 0.5.0.pre.2

data/app/models/rails_pulse/time_range.rb

@@ -0,0 +1,309 @@
+module RailsPulse
+  # Resolves the dashboard's time range, chart-zoom/table window, and
+  # duration-threshold filter from request params and session state, in one
+  # pass. Returns a single frozen Result so every caller — controllers,
+  # views, cards, charts — reads the same object instead of each re-deriving
+  # its own answer.
+  #
+  # Priority order for the chart/page window (highest first):
+  #   1. Page-specific preset from the dropdown (params[:q][:period_start_range])
+  #   2. Page-specific custom range from the picker (params[:q][:custom_date_range])
+  #   3. Chart zoom / drill-down params (params[:q][:occurred_at_gteq/_lt])
+  #   4. Time range selector preference (session[:time_range_preference])
+  #   5. Global filters (session[:global_filters]["start_time"/"end_time"])
+  #   6. Default (default_key)
+  #
+  # Every input is parsed in Time.zone, matching how Summary rows are
+  # bucketed — parsing a custom-range string in any other zone would
+  # misinterpret the intended instant whenever that zone differs from
+  # Time.zone, silently resolving to the wrong window.
+  class TimeRange
+    Result = Struct.new(
+      :window, :table_window, :period_type, :selected_time_range,
+      :zoom_start, :zoom_end, :start_duration, :selected_response_range,
+      keyword_init: true
+    )
+
+    PRESET_START = {
+      "last_24_hours" => -> { 1.day.ago },
+      "last_7_days"   => -> { 1.week.ago },
+      "last_14_days"  => -> { 2.weeks.ago },
+      "last_30_days"  => -> { 1.month.ago }
+    }.freeze
+
+    # Human-readable label for the zone daily/weekly/monthly summaries are
+    # bucketed in and custom ranges are rounded in (see class comment above)
+    # — the host app's config.time_zone, not the browser's zone. "UTC" or,
+    # e.g., "Eastern Time (US & Canada) (UTC-04:00)".
+    #
+    # This reads the Time.zone of the current dashboard request and assumes
+    # it is the zone SummaryJob ran under. That holds when both use
+    # config.time_zone (decision 0020). A host that overrides Time.zone per
+    # request for the dashboard as well would see a label that names the
+    # display zone while the daily buckets were still cut in the job's zone.
+    def self.aggregation_zone_label
+      return "UTC" if utc_zone?
+      "#{Time.zone.name} (UTC#{Time.zone.now.formatted_offset})"
+    end
+
+    # Compact form of aggregation_zone_label for chart headings and tooltip
+    # suffixes, where the full name would crowd out the data: "UTC", the
+    # zone's abbreviation when it has an alphabetic one ("EDT"), otherwise
+    # the offset ("UTC+05:45").
+    def self.aggregation_zone_short_label
+      return "UTC" if utc_zone?
+      abbreviation = Time.zone.now.zone
+      abbreviation.match?(/\A[A-Z]{2,5}\z/) ? abbreviation : "UTC#{Time.zone.now.formatted_offset}"
+    end
+
+    # IANA identifier for the same zone, for the chart JS (Intl.DateTimeFormat)
+    # to render daily labels in the zone summaries were actually bucketed in
+    # instead of the browser's zone.
+    def self.aggregation_zone_iana
+      Time.zone.tzinfo.name
+    end
+
+    def self.utc_zone?
+      Time.zone.utc_offset.zero? && Time.zone.now.zone == "UTC"
+    end
+    private_class_method :utc_zone?
+
+    def self.resolve(params:, session:, default_key: :last_24_hours, duration_range_type: :route)
+      new(params: params, session: session, default_key: default_key, duration_range_type: duration_range_type).resolve
+    end
+
+    def initialize(params:, session:, default_key:, duration_range_type:)
+      @params = params
+      @session = session
+      @default_key = default_key
+      @duration_range_type = duration_range_type
+    end
+
+    def resolve
+      start_time, end_time, selected_time_range = resolve_window
+      start_time, end_time, time_diff_hours = normalize(start_time, end_time)
+      period_type = time_diff_hours <= 25 ? "hour" : "day"
+
+      zoom_start, zoom_end, table_start, table_end = resolve_zoom(start_time.to_i, end_time.to_i)
+      start_duration, selected_response_range = resolve_duration
+
+      Result.new(
+        window: RailsPulse::TimeWindow.new(start_time, end_time),
+        table_window: RailsPulse::TimeWindow.new(table_start, table_end),
+        period_type: period_type,
+        selected_time_range: selected_time_range.to_s,
+        zoom_start: zoom_start,
+        zoom_end: zoom_end,
+        start_duration: start_duration,
+        selected_response_range: selected_response_range
+      ).freeze
+    end
+
+    private
+
+    attr_reader :params, :session, :default_key, :duration_range_type
+
+    # -- Window resolution (priorities 1-6) ----------------------------------
+
+    def resolve_window
+      from_page_preset || from_page_custom_range || from_chart_zoom ||
+        from_session_custom || from_session_preset || from_global_filters ||
+        default_window
+    end
+
+    def default_window
+      [ preset_start(default_key), Time.zone.now, default_key ]
+    end
+
+    def preset_start(key)
+      (PRESET_START[key.to_s] || PRESET_START["last_24_hours"]).call
+    end
+
+    # Priority 1: page-specific preset from the dropdown.
+    def from_page_preset
+      range = ransack_params[:period_start_range]
+      return nil unless range.present? && range.to_sym != :custom
+
+      [ preset_start(range), Time.zone.now, range ]
+    end
+
+    # Priority 2: page-specific custom datetime range from the picker (only
+    # when period_start_range is explicitly "custom").
+    def from_page_custom_range
+      return nil unless ransack_params[:period_start_range].present? &&
+        ransack_params[:period_start_range].to_sym == :custom &&
+        ransack_params[:custom_date_range].present? &&
+        ransack_params[:custom_date_range].include?(" to ")
+
+      dates = ransack_params[:custom_date_range].split(" to ")
+      custom_start = parse_time_param(dates[0].strip)
+      custom_end = parse_time_param(dates[1].strip)
+      return nil unless custom_start && custom_end
+
+      [ custom_start, custom_end, :custom ]
+    end
+
+    # Priority 3: custom time range from chart zoom.
+    def from_chart_zoom
+      return nil unless ransack_params[:occurred_at_gteq].present? && ransack_params[:occurred_at_lt].present?
+
+      zoom_start = parse_time_param(ransack_params[:occurred_at_gteq])
+      zoom_end = parse_time_param(ransack_params[:occurred_at_lt])
+      return nil unless zoom_start && zoom_end
+
+      [ zoom_start, zoom_end, :custom ]
+    end
+
+    # Priority 4a: custom range from the time range selector (session).
+    def from_session_custom
+      preference = session_time_range_preference
+      return nil unless RailsPulse::TimeRangePreference.custom?(preference)
+
+      start_time = parse_time_param(preference["start_time"]) || preset_start(default_key)
+      end_time = parse_time_param(preference["end_time"]) || Time.zone.now
+      [ start_time, end_time, :custom ]
+    end
+
+    # Priority 4b: preset from the time range selector (session).
+    def from_session_preset
+      preference = session_time_range_preference
+      return nil unless preference.is_a?(String) && preference.present?
+
+      [ preset_start(preference), Time.zone.now, preference.to_sym ]
+    end
+
+    # Priority 5: global filters (session).
+    def from_global_filters
+      filters = session_global_filters
+      return nil unless filters["start_time"].present? || filters["end_time"].present?
+
+      start_time = parse_time_param(filters["start_time"]) || preset_start(default_key)
+      end_time = parse_time_param(filters["end_time"]) || Time.zone.now
+      [ start_time, end_time, :custom ]
+    end
+
+    def ransack_params
+      q = params[:q]
+      q.respond_to?(:permit) ? q : ActionController::Parameters.new({})
+    end
+
+    def session_time_range_preference
+      RailsPulse::TimeRangePreference.normalize(session[:time_range_preference])
+    end
+
+    def session_global_filters
+      filters = session[:global_filters]
+      filters.is_a?(Hash) ? filters : {}
+    end
+
+    # Returns nil for anything that does not parse, so a hand-edited or stale
+    # value falls back to the default range instead of raising.
+    def parse_time_param(param)
+      case param
+      when Time, DateTime
+        param.in_time_zone
+      when String
+        return nil if param.blank?
+
+        Time.zone.parse(param)
+      when Numeric
+        Time.zone.at(param)
+      else
+        nil
+      end
+    rescue ArgumentError, TypeError, RangeError
+      nil
+    end
+
+    # Rounds to hour or day boundaries in Time.zone (summaries are always
+    # bucketed there) and returns the span in hours (float) alongside.
+    def normalize(start_time, end_time)
+      start_time = start_time.in_time_zone
+      end_time = end_time.in_time_zone
+      time_diff_hours = (end_time.to_i - start_time.to_i) / 3600.0
+
+      if time_diff_hours <= 25
+        [ start_time.beginning_of_hour, end_time.end_of_hour, time_diff_hours ]
+      else
+        [ start_time.beginning_of_day, end_time.end_of_day, time_diff_hours ]
+      end
+    end
+
+    # -- Zoom / table window --------------------------------------------------
+
+    def resolve_zoom(main_start, main_end)
+      selected_column_time = params[:selected_column_time]
+      zoom_start = params.delete(:zoom_start_time)
+      zoom_end = params.delete(:zoom_end_time)
+
+      if selected_column_time
+        table_start, table_end = normalize_column_time(selected_column_time.to_i, main_start, main_end)
+        # Column selection has highest precedence for the table only; the
+        # chart keeps showing the full range, so zoom_start/zoom_end are
+        # returned as extracted (not normalized) rather than derived here.
+        return [ zoom_start, zoom_end, table_start, table_end ]
+      end
+
+      zoom_start, zoom_end = normalize_zoom_times(zoom_start.to_i, zoom_end.to_i) if zoom_start && zoom_end
+
+      table_start = zoom_start || main_start
+      table_end = zoom_end || main_end
+
+      [ zoom_start, zoom_end, table_start, table_end ]
+    end
+
+    # column_time_ms is JS milliseconds; period boundary is based on the
+    # overall page range (main_start/main_end), same as the chart.
+    def normalize_column_time(column_time_ms, main_start, main_end)
+      column_time_seconds = column_time_ms / 1000
+      time_diff_hours = (main_end - main_start) / 3600.0
+      column_time_obj = Time.zone&.at(column_time_seconds) || Time.at(column_time_seconds)
+
+      if time_diff_hours <= 25
+        [ column_time_obj.beginning_of_hour.to_i, column_time_obj.end_of_hour.to_i ]
+      else
+        [ column_time_obj.beginning_of_day.to_i, column_time_obj.end_of_day.to_i ]
+      end
+    end
+
+    # start_ms/end_ms are JS milliseconds; period boundary is based on the
+    # zoomed span itself.
+    def normalize_zoom_times(start_ms, end_ms)
+      start_seconds = start_ms / 1000
+      end_seconds = end_ms / 1000
+      time_diff_hours = (end_seconds - start_seconds) / 3600.0
+      start_obj = Time.zone&.at(start_seconds) || Time.at(start_seconds)
+      end_obj = Time.zone&.at(end_seconds) || Time.at(end_seconds)
+
+      if time_diff_hours <= 25
+        [ start_obj.beginning_of_hour.to_i, end_obj.end_of_hour.to_i ]
+      else
+        [ start_obj.beginning_of_day.to_i, end_obj.end_of_day.to_i ]
+      end
+    end
+
+    # -- Duration threshold -----------------------------------------------------
+
+    def resolve_duration
+      thresholds = RailsPulse.configuration.public_send("#{duration_range_type}_thresholds")
+      duration_param = ransack_params[:avg_duration] || ransack_params[:duration] || ransack_params[:duration_gteq]
+
+      if duration_param.present?
+        [ threshold_for(thresholds, duration_param), duration_param ]
+      elsif (global_threshold = session_global_filters["performance_threshold"]).present?
+        [ threshold_for(thresholds, global_threshold), global_threshold.to_sym ]
+      else
+        [ 0, :all ]
+      end
+    end
+
+    def threshold_for(thresholds, key)
+      case key.to_sym
+      when :slow then thresholds[:slow]
+      when :very_slow then thresholds[:very_slow]
+      when :critical then thresholds[:critical]
+      else 0
+      end
+    end
+  end
+end

data/app/models/rails_pulse/time_window.rb

@@ -45,6 +45,21 @@ module RailsPulse
       starts
     end
 
+    # The start of each chart bucket from the window's start, as epoch
+    # seconds: one calendar day or one hour apart in Time.zone. A day is 23
+    # or 25 hours across a daylight-saving change, so stepping a fixed 86,400
+    # seconds would drift off local midnight and miss every summary after it.
+    def bucket_timestamps(period_type)
+      step = period_type.to_s == "hour" ? 1.hour : 1.day
+      stamps = []
+      current = start_time
+      while current <= end_time
+        stamps << current.to_i
+        current += step
+      end
+      stamps
+    end
+
     # The window of the same length immediately preceding this one, for
     # period-over-period comparisons. `unit` is "day" or "hour".
     def previous(unit)

data/app/models/rails_pulse/writer_heartbeat.rb

@@ -0,0 +1,90 @@
+module RailsPulse
+  # The background writer's once-a-minute sample, stored as an Event of kind
+  # writer_heartbeat: `subject` is "host:pid", `value` the requests dropped
+  # since the previous sample, and `metadata` the queue depth, its configured
+  # capacity and the lifetime drop count. Stats are otherwise per process, so
+  # with eight Puma workers the dashboard could only ever see the one that
+  # happened to serve it; these rows let it, the Storage page and
+  # rails_pulse:status add every live writer up.
+  class WriterHeartbeat
+    KIND = "writer_heartbeat".freeze
+    # A writer that has not reported for this long is treated as gone.
+    LIVE_WINDOW = 3.minutes
+    RETENTION = 24.hours
+
+    Sample = Struct.new(:hostname, :pid, :queue_size, :queue_depth, :dropped_total, :sampled_at, keyword_init: true) do
+      def process_label
+        "#{hostname}:#{pid}"
+      end
+    end
+
+    class << self
+      def events
+        RailsPulse::Event.of_kind(KIND)
+      end
+
+      # `host_label` is config.cloud.host_label: Rails Pulse Cloud names the
+      # host by it instead of the hostname, which can show internal addresses
+      # and changes with every container.
+      def record!(hostname:, pid:, queue_size:, queue_depth:, dropped:, dropped_total:, host_label: nil, sampled_at: Time.current)
+        RailsPulse::Event.insert_all([ {
+          kind:        KIND,
+          subject:     "#{hostname}:#{pid}",
+          outcome:     "sampled",
+          value:       dropped,
+          occurred_at: sampled_at,
+          metadata:    { hostname: hostname, host_label: host_label, pid: pid, queue_size: queue_size, queue_depth: queue_depth,
+                         dropped_total: dropped_total }.compact.to_json,
+          created_at:  sampled_at,
+          updated_at:  sampled_at
+        } ])
+      end
+
+      def prune!
+        events.where(occurred_at: ...RETENTION.ago).delete_all
+      end
+
+      # The latest sample from each writer that reported inside LIVE_WINDOW,
+      # newest first. A handful of rows per process, reduced in Ruby.
+      def live_processes
+        events.since(LIVE_WINDOW.ago).recent.to_a.uniq(&:subject).map { |event| sample_from(event) }
+      end
+
+      # { "host:pid" => requests dropped inside `window` }
+      def dropped_by_process(window: 1.hour)
+        events.since(window.ago).group(:subject).sum(:value).transform_values(&:to_i)
+      end
+
+      # What the dashboard, Storage page and status task show:
+      #   processes        live writers
+      #   queue_depth      requests waiting across them, from each one's latest sample
+      #   queue_size       the largest configured capacity among them
+      #   dropped          requests dropped inside `window`, across every process
+      #   last_sampled_at  most recent heartbeat, nil when there is none
+      def summary(window: 1.hour)
+        processes = live_processes
+        {
+          processes:       processes.size,
+          queue_depth:     processes.sum(&:queue_depth),
+          queue_size:      processes.map(&:queue_size).max || 0,
+          dropped:         events.since(window.ago).sum(:value).to_i,
+          last_sampled_at: events.maximum(:occurred_at)
+        }
+      end
+
+      private
+
+      def sample_from(event)
+        meta = event.metadata_hash
+        Sample.new(
+          hostname:      meta["hostname"],
+          pid:           meta["pid"],
+          queue_size:    meta["queue_size"].to_i,
+          queue_depth:   meta["queue_depth"].to_i,
+          dropped_total: meta["dropped_total"].to_i,
+          sampled_at:    event.occurred_at
+        )
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/deployment_serializer.rb

@@ -0,0 +1,23 @@
+module RailsPulse
+  module Api
+    module V1
+      class DeploymentSerializer
+        # `comparison` is the deployment's DeploymentComparison, computed by
+        # the caller so a page of deployments is compared in one query.
+        def self.serialize(deployment, comparison: nil)
+          {
+            id:               deployment.id,
+            revision:         deployment.revision,
+            short_revision:   deployment.short_revision,
+            started_at:       deployment.started_at,
+            finished_at:      deployment.finished_at,
+            duration_seconds: deployment.duration&.round(1),
+            in_progress:      deployment.in_progress?,
+            metadata:         deployment.metadata_hash,
+            comparison:       comparison
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/exception_group_serializer.rb

@@ -0,0 +1,23 @@
+module RailsPulse
+  module Api
+    module V1
+      class ExceptionGroupSerializer
+        def self.serialize(group)
+          {
+            id:               group.id,
+            fingerprint:      group.fingerprint,
+            exception_class:  group.exception_class,
+            location:         group.location,
+            message:          group.message,
+            status:           group.status,
+            occurrence_count: group.occurrence_count,
+            first_seen_at:    group.first_seen_at,
+            last_seen_at:     group.last_seen_at,
+            resolved_at:      group.resolved_at,
+            preserve:         group.preserve
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/exception_occurrence_serializer.rb

@@ -0,0 +1,22 @@
+module RailsPulse
+  module Api
+    module V1
+      class ExceptionOccurrenceSerializer
+        def self.serialize(occurrence)
+          {
+            id:             occurrence.id,
+            exception_class: occurrence.exception_class,
+            message:        occurrence.message,
+            occurred_at:    occurrence.occurred_at,
+            request_method: occurrence.request_method,
+            request_url:    occurrence.request_url,
+            request_params: occurrence.request_params.presence,
+            environment:    occurrence.environment,
+            deploy_sha:     occurrence.deploy_sha,
+            backtrace:      Array(occurrence.backtrace)
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/job_run_serializer.rb

@@ -0,0 +1,28 @@
+module RailsPulse
+  module Api
+    module V1
+      class JobRunSerializer
+        ERROR_MESSAGE_LIMIT = 500
+
+        def self.serialize(run)
+          {
+            id:            run.id,
+            job_id:        run.job_id,
+            job_name:      run.job&.name,
+            queue_name:    run.job&.queue_name,
+            run_id:        run.run_id,
+            status:        run.status,
+            occurred_at:   run.occurred_at,
+            enqueued_at:   run.enqueued_at,
+            duration:      run.duration,
+            attempts:      run.attempts,
+            adapter:       run.adapter,
+            error_class:   run.error_class,
+            error_message: run.error_message&.truncate(ERROR_MESSAGE_LIMIT),
+            tags:          run.tags
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/job_serializer.rb

@@ -0,0 +1,26 @@
+module RailsPulse
+  module Api
+    module V1
+      class JobSerializer
+        # Without `stats` the counters are the job's lifetime totals, cached on
+        # the row. With it they cover one window and come from summaries, so
+        # the two are kept in separate keys rather than one set of names
+        # meaning different things depending on the request.
+        def self.serialize(job, stats: nil)
+          {
+            id:             job.id,
+            name:           job.name,
+            queue_name:     job.queue_name,
+            runs_count:     job.runs_count,
+            failures_count: job.failures_count,
+            avg_duration:   job.avg_duration,
+            p95_duration:   job.p95_duration,
+            p99_duration:   job.p99_duration,
+            failure_rate:   job.failure_rate,
+            stats:          stats
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/query_serializer.rb

@@ -0,0 +1,25 @@
+module RailsPulse
+  module Api
+    module V1
+      class QuerySerializer
+        def self.serialize(query, stats: nil)
+          analysis = (query.n_plus_one_analysis || {}).transform_keys(&:to_s)
+
+          {
+            id:             query.id,
+            normalized_sql: query.normalized_sql,
+            hashed_sql:     query.hashed_sql,
+            analyzed_at:    query.analyzed_at,
+            issues:         query.issues,
+            suggestions:    query.suggestions,
+            n_plus_one:     {
+              likely:     analysis["is_likely_n_plus_one"] == true,
+              confidence: analysis["confidence_score"]
+            },
+            stats:          stats
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/request_serializer.rb

@@ -0,0 +1,22 @@
+module RailsPulse
+  module Api
+    module V1
+      class RequestSerializer
+        def self.serialize(request)
+          {
+            id:                  request.id,
+            route_id:            request.route_id,
+            path:                request.route&.path,
+            occurred_at:         request.occurred_at,
+            duration:            request.duration,
+            status:              request.status,
+            is_error:            request.is_error,
+            request_uuid:        request.request_uuid,
+            controller_action:   request.controller_action,
+            response_size_bytes: request.response_size_bytes
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/rails_pulse/api/v1/route_serializer.rb

@@ -0,0 +1,19 @@
+module RailsPulse
+  module Api
+    module V1
+      class RouteSerializer
+        def self.serialize(route, stats: nil)
+          {
+            id:                route.id,
+            http_methods:      route.http_methods_list,
+            path:              route.path,
+            controller_action: route.controller_action,
+            tags:              route.tag_list,
+            created_at:        route.created_at,
+            stats:             stats
+          }
+        end
+      end
+    end
+  end
+end