chronicle-rails 0.1.0

data/app/models/chronicle/error_log.rb

@@ -0,0 +1,69 @@
+module Chronicle
+  class ErrorLog < ApplicationRecord
+    belongs_to :error_group
+
+    # Constants are re-exported so callers can reference ErrorLog::OPEN etc.
+    # without knowing about the group model.
+    OPEN          = ErrorGroup::OPEN
+    RESOLVED      = ErrorGroup::RESOLVED
+    IGNORED       = ErrorGroup::IGNORED
+    VALID_STATUSES = ErrorGroup::VALID_STATUSES
+
+    # These fields do not live in error_logs; they are provided at creation time
+    # and forwarded to the ErrorGroup by GroupResolver.  After the group is
+    # resolved the reader methods below return the persisted group values.
+    attr_writer :project, :source_type, :source_name, :error_message,
+                :error_fingerprint, :original_backtrace, :cleaned_backtrace
+
+    validates :error_group, presence: true
+    validates :source_type,
+              :source_name,
+              :error_message, presence: true, on: :create
+
+    before_validation :resolve_error_group, on: :create
+
+    delegate :status, :jira_link, to: :error_group, allow_nil: true
+
+    # Reader methods: prefer the persisted group value once the log is saved;
+    # fall back to the in-memory virtual attribute during the create flow.
+    def project           = error_group&.project           || @project
+    def source_type       = error_group&.source_type       || @source_type
+    def source_name       = error_group&.source_name       || @source_name
+    def error_message     = error_group&.error_message     || @error_message
+    def error_fingerprint = error_group&.fingerprint       || @error_fingerprint
+    def original_backtrace = error_group&.original_backtrace || @original_backtrace
+    def cleaned_backtrace  = error_group&.cleaned_backtrace  || @cleaned_backtrace
+
+    # Returns a flat hash that combines the log's own columns with the key
+    # group-level fields inlined for API convenience, plus the full nested
+    # group for clients that need it.
+    def get_hash
+      group = error_group
+      attributes.symbolize_keys.merge(
+        error_fingerprint: group&.fingerprint,
+        project: group&.project,
+        source_type: group&.source_type,
+        source_name: group&.source_name,
+        error_message: group&.error_message,
+        original_backtrace: group&.original_backtrace,
+        cleaned_backtrace: group&.cleaned_backtrace,
+        status: group&.status,
+        jira_link: group&.jira_link,
+        error_group: group&.get_hash,
+        user: (Chronicle.config.user_model&.find_by(id: user_id)&.try(:basic_info) if user_id.present?)
+      )
+    end
+
+    def as_json(_options = {})
+      get_hash
+    end
+
+    private
+
+    def resolve_error_group
+      return if error_group_id.present? || error_group&.persisted?
+
+      self.error_group = ErrorLogs::GroupResolver.new(self).call
+    end
+  end
+end

data/app/services/chronicle/api_logs/buffer.rb

@@ -0,0 +1,62 @@
+require 'fileutils'
+require 'json'
+
+module Chronicle
+  module ApiLogs
+    # Append-only, per-process file buffer for API log payloads.
+    #
+    # Each Puma/SolidQueue worker writes to its own `api_logs.{pid}.jsonl`
+    # file, so no cross-process locking is needed. The Flusher reads all
+    # PID files when it runs.
+    class Buffer
+      FILE_PREFIX = 'api_logs'.freeze
+      FILE_EXT    = 'jsonl'.freeze
+
+      class << self
+        def append(payload)
+          dir = buffer_dir
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          path = current_file_path
+          File.open(path, 'a') { |f| f.puts(payload.to_json) }
+
+          maybe_flush(path)
+        end
+
+        def buffer_dir
+          configured = Chronicle.config.api_log_buffer_dir
+          return configured if configured.present?
+
+          if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+            Rails.root.join('tmp/chronicle').to_s
+          else
+            File.join(Dir.tmpdir, 'chronicle')
+          end
+        end
+
+        def current_file_path
+          File.join(buffer_dir, "#{FILE_PREFIX}.#{Process.pid}.#{FILE_EXT}")
+        end
+
+        def line_count(path)
+          return 0 unless File.exist?(path)
+          count = 0
+          File.foreach(path) { count += 1 }
+          count
+        end
+
+        private
+
+        def maybe_flush(path)
+          threshold = Chronicle.config.api_log_flush_size
+          return if threshold.nil? || threshold <= 0
+          return if line_count(path) < threshold
+
+          Chronicle::FlushApiLogsJob.perform_later
+        rescue StandardError
+          # Never let a flush enqueue failure break the request path.
+        end
+      end
+    end
+  end
+end

data/app/services/chronicle/api_logs/flusher.rb

@@ -0,0 +1,98 @@
+require 'json'
+
+module Chronicle
+  module ApiLogs
+    # Reads all per-PID buffer files, bulk-inserts their contents into
+    # chronicle_api_logs, upserts api_routes, and deletes the consumed files.
+    #
+    # Atomic-rename strategy: each buffer file is renamed to a `.flushing-*`
+    # name before reading, so concurrent writers (same PID) recreate the
+    # original file and never lose entries.
+    class Flusher
+      INSERT_BATCH_SIZE = 1000
+
+      class << self
+        def call
+          paths = claim_files
+          return { files: 0, records: 0 } if paths.empty?
+
+          records = paths.flat_map { |p| read_jsonl(p) }
+          return cleanup_and_return(paths, 0) if records.empty?
+
+          insert_logs(records)
+          sync_routes(records)
+
+          cleanup_and_return(paths, records.size)
+        end
+
+        def sync_routes(records)
+          now = Time.current
+          pairs = records.filter_map do |r|
+            path = r['api_endpoint']
+            method = r['http_method']
+            next if path.blank? || method.blank?
+            [path, method]
+          end.uniq
+
+          return if pairs.empty?
+
+          rows = pairs.map do |path, method|
+            { path: path, http_method: method, first_seen_at: now, created_at: now, updated_at: now }
+          end
+
+          ApiRoute.insert_all(rows, unique_by: 'index_chronicle_api_routes_on_path_and_method') # rubocop:disable Rails/SkipsModelValidations
+        end
+
+        private
+
+        def claim_files
+          dir = Buffer.buffer_dir
+          return [] unless File.directory?(dir)
+
+          glob = File.join(dir, "#{Buffer::FILE_PREFIX}.*.#{Buffer::FILE_EXT}")
+          stamp = Time.now.utc.strftime('%Y%m%d%H%M%S%N')
+
+          Dir.glob(glob).reject { |p| p.include?('.flushing-') }.filter_map do |path|
+            target = path.sub(/\.#{Buffer::FILE_EXT}\z/o, ".flushing-#{stamp}.#{Buffer::FILE_EXT}")
+            begin
+              File.rename(path, target)
+              target
+            rescue Errno::ENOENT
+              nil
+            end
+          end
+        end
+
+        def read_jsonl(path)
+          File.foreach(path).filter_map do |line|
+            line = line.strip
+            next if line.empty?
+            JSON.parse(line)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        def insert_logs(records)
+          now = Time.current
+          allowed = ApiLog.column_names - ['id']
+
+          records.each_slice(INSERT_BATCH_SIZE) do |batch|
+            rows = batch.map do |raw|
+              row = raw.slice(*allowed)
+              row['created_at'] ||= now
+              row['updated_at'] ||= now
+              row
+            end
+            ApiLog.insert_all(rows) # rubocop:disable Rails/SkipsModelValidations
+          end
+        end
+
+        def cleanup_and_return(paths, count)
+          paths.each { |p| FileUtils.rm_f(p) }
+          { files: paths.size, records: count }
+        end
+      end
+    end
+  end
+end

data/app/services/chronicle/api_logs/metrics.rb

@@ -0,0 +1,285 @@
+module Chronicle
+  module ApiLogs
+    class Metrics
+      include Filterable
+
+      FILTER_DEFINITION = {
+        client_version: :exact,
+        backend_version: :exact,
+        device_os: :exact,
+        time_zone: :exact,
+        start_date: :date_range,
+        end_date: :date_range,
+        http_method: :exact,
+        api_endpoint: :exact,
+      }.freeze
+
+      def initialize(filters: {})
+        @filters = filters
+        start_time, end_time = normalize_date_range
+        @filters[:start_date] = start_time.to_date.to_s
+        @filters[:end_date] = end_time.to_date.to_s
+      end
+
+      def kpi_cards
+        scope = build_query(ApiLog, filter_definition: FILTER_DEFINITION, filters: @filters, date_column: :timestamp)
+        aggregates = fetch_aggregates(scope)
+
+        {
+          total_api_calls: aggregates[:total_count],
+          unique_users: aggregates[:unique_users],
+          unique_devices: aggregates[:unique_devices],
+          average_response_time: aggregates[:avg_response_time],
+          p50_response_time: aggregates[:p50_response_time],
+          p95_response_time: aggregates[:p95_response_time],
+          p99_response_time: aggregates[:p99_response_time],
+          error_rate_percentage: calculate_error_rate(aggregates[:total_count], aggregates[:error_count]),
+          requests_per_hour: calculate_requests_per_hour(aggregates[:total_count]),
+        }
+      end
+
+      def distribution_metrics
+        start_time, end_time = normalize_date_range
+        scope = build_query(ApiLog, filter_definition: FILTER_DEFINITION, filters: @filters, date_column: :timestamp)
+
+        {
+          status_code_distribution: fetch_status_code_distribution(scope),
+          traffic_over_time: fetch_traffic_over_time(scope, start_time, end_time),
+          response_time_trend: fetch_response_time_trend(scope, start_time, end_time),
+        }
+      end
+
+      class << self
+        def kpi_cards(filters: {})
+          new(filters: filters).kpi_cards
+        end
+
+        def distribution_metrics(filters: {})
+          new(filters: filters).distribution_metrics
+        end
+      end
+
+      private
+
+      def fetch_aggregates(scope)
+        result = scope.pick(
+          Arel.sql('COUNT(*)'),
+          Arel.sql('COUNT(DISTINCT user_id)'),
+          Arel.sql('COUNT(DISTINCT device_id)'),
+          Arel.sql('AVG(response_time_ms)'),
+          Arel.sql('COUNT(CASE WHEN http_status_code BETWEEN 400 AND 599 THEN 1 END)'),
+          Arel.sql('PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY response_time_ms)'),
+          Arel.sql('PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY response_time_ms)'),
+          Arel.sql('PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY response_time_ms)')
+        )
+
+        return default_aggregates if result.nil?
+
+        {
+          total_count: result[0] || 0,
+          unique_users: result[1] || 0,
+          unique_devices: result[2] || 0,
+          avg_response_time: result[3]&.round(2) || 0.0,
+          error_count: result[4] || 0,
+          p50_response_time: result[5]&.round(2) || 0.0,
+          p95_response_time: result[6]&.round(2) || 0.0,
+          p99_response_time: result[7]&.round(2) || 0.0,
+        }
+      end
+
+      def default_aggregates
+        {
+          total_count: 0,
+          unique_users: 0,
+          unique_devices: 0,
+          avg_response_time: 0.0,
+          error_count: 0,
+          p50_response_time: 0.0,
+          p95_response_time: 0.0,
+          p99_response_time: 0.0,
+        }
+      end
+
+      def calculate_error_rate(total_count, error_count)
+        return 0.0 if total_count == 0
+
+        ((error_count.to_f / total_count) * 100).round(2)
+      end
+
+      def calculate_requests_per_hour(total_count)
+        return 0.0 if total_count == 0
+
+        # Use filter dates if provided
+        start_date = @filters[:start_date] || @filters['start_date']
+        end_date = @filters[:end_date] || @filters['end_date']
+
+        if start_date.present? && end_date.present?
+          start_time = Util.parse_date(start_date).beginning_of_day
+          end_time = Util.parse_date(end_date).end_of_day
+
+          duration_hours = ((end_time - start_time) / 3600.0)
+          return 0.0 if duration_hours == 0
+
+          (total_count / duration_hours).round(2)
+        else
+          # No date range provided, return 0.0
+          0.0
+        end
+      end
+
+      def normalize_date_range
+        @normalize_date_range ||= begin
+          start_date = @filters[:start_date] || @filters['start_date']
+          end_date = @filters[:end_date] || @filters['end_date']
+
+          if start_date.present? && end_date.present?
+            start_time = Util.parse_date(start_date).beginning_of_day
+            end_time = Util.parse_date(end_date).end_of_day
+          else
+            # Default to last 6 months
+            end_time = Time.current
+            start_time = 6.months.ago
+          end
+
+          # Ensure max range is 6 months
+          start_time = end_time - 6.months if (end_time - start_time) > 6.months
+
+          [start_time, end_time]
+        end
+      end
+
+      def calculate_time_interval(start_time, end_time)
+        duration_hours = ((end_time - start_time) / 3600.0)
+
+        if duration_hours <= 24
+          { interval: 1.hour, format: '%H:%M' }
+        elsif duration_hours <= 720 # 30 days
+          { interval: 1.day, format: '%b %d' }
+        else # More than 30 days
+          { interval: 1.month, format: '%b %Y' }
+        end
+      end
+
+      def fetch_status_code_distribution(scope)
+        results = scope
+                  .group(:http_status_code)
+                  .order(Arel.sql('COUNT(*) DESC'))
+                  .count
+
+        total = 0
+
+        status_code_frequency = results.map do |status_code, count|
+          total += count
+          {
+            status_code: status_code,
+            count: count,
+          }
+        end
+
+        {
+          total_count: total,
+          status_codes: status_code_frequency,
+        }
+      end
+
+      def fetch_traffic_over_time(scope, start_time, end_time)
+        interval_config = calculate_time_interval(start_time, end_time)
+        interval = interval_config[:interval]
+        format = interval_config[:format]
+
+        time_buckets = generate_time_buckets(start_time, end_time, interval)
+
+        # Fetch actual data grouped by interval
+        data = fetch_grouped_data(scope, interval_config, 'COUNT(*)')
+
+        # Fill in missing buckets with 0
+        time_buckets.map do |bucket_time|
+          {
+            label: bucket_time.strftime(format),
+            timestamp: bucket_time.to_i,
+            count: data[bucket_time] || 0,
+          }
+        end
+      end
+
+      def fetch_response_time_trend(scope, start_time, end_time)
+        interval_config = calculate_time_interval(start_time, end_time)
+        interval = interval_config[:interval]
+        format = interval_config[:format]
+
+        time_buckets = generate_time_buckets(start_time, end_time, interval)
+
+        # Fetch avg and p95 data
+        avg_data = fetch_grouped_data(scope, interval_config, 'AVG(response_time_ms)')
+        p95_data = fetch_grouped_data(scope, interval_config,
+                                      'PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY response_time_ms)')
+
+        time_buckets.map do |bucket_time|
+          {
+            label: bucket_time.strftime(format),
+            timestamp: bucket_time.to_i,
+            average_response_time: (avg_data[bucket_time] || 0).round(2),
+            p95_response_time: (p95_data[bucket_time] || 0).round(2),
+          }
+        end
+      end
+
+      def generate_time_buckets(start_time, end_time, interval)
+        buckets = []
+
+        if interval == 1.month
+          # For monthly intervals, start at beginning of month
+          current_time = start_time.beginning_of_month
+          while current_time <= end_time
+            buckets << current_time
+            current_time = (current_time + 1.month).beginning_of_month
+          end
+        else
+          # For hour/day intervals, use regular increments
+          current_time = start_time
+          while current_time <= end_time
+            buckets << current_time
+            current_time += interval
+          end
+        end
+
+        buckets
+      end
+
+      def fetch_grouped_data(scope, interval_config, aggregate_function)
+        interval = interval_config[:interval]
+
+        # Validate aggregate function to prevent SQL injection
+        validate_aggregate_function!(aggregate_function)
+
+        # Determine PostgreSQL date truncation function based on interval
+        trunc_func = if interval == 1.hour
+                       "date_trunc('hour', timestamp)"
+                     elsif interval == 1.month
+                       "date_trunc('month', timestamp)"
+                     else
+                       "date_trunc('day', timestamp)"
+                     end
+
+        results = scope
+                  .group(Arel.sql(trunc_func))
+                  .pluck(Arel.sql("#{trunc_func} as time_bucket, #{aggregate_function}"))
+
+        results.to_h { |time_str, value| [Time.zone.parse(time_str.to_s), value] }
+      end
+
+      def validate_aggregate_function!(function)
+        # Whitelist of allowed aggregate functions
+        allowed_functions = [
+          'COUNT(*)',
+          'AVG(response_time_ms)',
+          'PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY response_time_ms)',
+        ]
+
+        return if allowed_functions.include?(function)
+
+        raise ArgumentError, "Invalid aggregate function: #{function}"
+      end
+    end
+  end
+end

data/app/services/chronicle/api_logs/updater.rb

@@ -0,0 +1,19 @@
+module Chronicle
+  module ApiLogs
+    class Updater
+      def initialize(request_id, frontend_response_time_ms)
+        @request_id = request_id
+        @frontend_response_time_ms = frontend_response_time_ms
+      end
+
+      def call
+        api_log = ApiLog.find_by(request_id: @request_id)
+
+        raise NotFoundError, "API log not found with request_id: #{@request_id}" if api_log.nil?
+
+        api_log.update!(frontend_response_time_ms: @frontend_response_time_ms)
+        api_log
+      end
+    end
+  end
+end

data/app/services/chronicle/api_routes/stats.rb

@@ -0,0 +1,131 @@
+module Chronicle
+  module ApiRoutes
+    class Stats
+      SORTABLE_COLUMNS = %w[
+        avg_response_time_ms
+        p95_response_time_ms
+        p99_response_time_ms
+        error_rate_percentage
+        total_requests
+        unique_users
+        requests_per_hour
+      ].freeze
+
+      DEFAULT_SORT_BY        = 'avg_response_time_ms'.freeze
+      DEFAULT_SORT_DIRECTION = 'desc'.freeze
+      DEFAULT_PER_PAGE       = 25
+      MAX_PER_PAGE           = 100
+
+      # Aliases that PostgreSQL exposes after the GROUP BY+SELECT; safe to interpolate
+      # because they are taken from the SORTABLE_COLUMNS whitelist above.
+      SORT_COLUMN_ALIAS = {
+        'avg_response_time_ms' => 'avg_response_time_ms',
+        'p95_response_time_ms' => 'p95_response_time_ms',
+        'p99_response_time_ms' => 'p99_response_time_ms',
+        'error_rate_percentage' => 'error_rate_percentage',
+        'total_requests' => 'total_requests',
+        'unique_users' => 'unique_users',
+        # duration is constant per request so ordering by total_requests is equivalent
+        'requests_per_hour' => 'total_requests',
+      }.freeze
+
+      AGGREGATE_SELECT = [
+        'api_endpoint AS path',
+        'http_method',
+        'COUNT(*) AS total_requests',
+        'COUNT(DISTINCT user_id) AS unique_users',
+        'ROUND(AVG(response_time_ms)::numeric, 2) AS avg_response_time_ms',
+        'ROUND(PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY response_time_ms)::numeric, 2) AS p95_response_time_ms',
+        'ROUND(PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY response_time_ms)::numeric, 2) AS p99_response_time_ms',
+        'ROUND(100.0 * COUNT(CASE WHEN http_status_code BETWEEN 400 AND 599 THEN 1 END) / COUNT(*), 2)
+ AS error_rate_percentage',
+      ].freeze
+
+      def initialize(filters: {}, sort_by: nil, sort_direction: nil, page: 1, per_page: DEFAULT_PER_PAGE)
+        filters         = filters.to_unsafe_h.symbolize_keys if filters.respond_to?(:to_unsafe_h)
+        @filters        = filters.symbolize_keys
+        @sort_by        = SORTABLE_COLUMNS.include?(sort_by.to_s) ? sort_by.to_s : DEFAULT_SORT_BY
+        @sort_direction = if %w[asc
+                                desc].include?(sort_direction.to_s.downcase)
+                            sort_direction.to_s.downcase
+                          else
+                            DEFAULT_SORT_DIRECTION
+                          end
+        @page           = [page.to_i, 1].max
+        @per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+        @start_time, @end_time = normalize_date_range
+      end
+
+      def call
+        base    = filtered_scope
+        total   = base.group(:api_endpoint, :http_method).count.size
+        records = stats_scope(base)
+                  .order(Arel.sql("#{SORT_COLUMN_ALIAS[@sort_by]} #{@sort_direction.upcase} NULLS LAST"))
+                  .limit(@per_page)
+                  .offset((@page - 1) * @per_page)
+
+        duration_hours = [(@end_time - @start_time) / 3600.0, 1].max
+
+        {
+          data: records.map { |row| serialize(row, duration_hours) },
+          pagination: {
+            total_count: total,
+            page: @page,
+            per_page: @per_page,
+            total_pages: (total.to_f / @per_page).ceil,
+          },
+        }
+      end
+
+      private
+
+      def filtered_scope
+        scope = ApiLog.where(timestamp: @start_time..@end_time)
+
+        scope = scope.where(http_method: @filters[:http_method]) if @filters[:http_method].present?
+
+        if @filters[:api_endpoint].present?
+          pattern = "%#{ActiveRecord::Base.sanitize_sql_like(@filters[:api_endpoint])}%"
+          scope = scope.where(ApiLog.arel_table[:api_endpoint].matches(pattern))
+        end
+
+        scope
+      end
+
+      def stats_scope(base)
+        base.group(:api_endpoint, :http_method).select(*AGGREGATE_SELECT)
+      end
+
+      def serialize(row, duration_hours)
+        {
+          path: row.path,
+          http_method: row.http_method,
+          total_requests: row.total_requests.to_i,
+          unique_users: row.unique_users.to_i,
+          requests_per_hour: (row.total_requests.to_f / duration_hours).round(2),
+          avg_response_time_ms: row.avg_response_time_ms.to_f,
+          p95_response_time_ms: row.p95_response_time_ms.to_f,
+          p99_response_time_ms: row.p99_response_time_ms.to_f,
+          error_rate_percentage: row.error_rate_percentage.to_f,
+        }
+      end
+
+      def normalize_date_range
+        start_date = @filters[:start_date]
+        end_date   = @filters[:end_date]
+
+        if start_date.present? && end_date.present?
+          start_time = Util.parse_date(start_date).beginning_of_day
+          end_time   = Util.parse_date(end_date).end_of_day
+        else
+          end_time   = Time.current
+          start_time = 6.months.ago
+        end
+
+        start_time = end_time - 6.months if (end_time - start_time) > 6.months
+
+        [start_time, end_time]
+      end
+    end
+  end
+end