chronicle-rails 0.1.0

data/app/services/chronicle/error_logs/group_resolver.rb

@@ -0,0 +1,66 @@
+module Chronicle
+  module ErrorLogs
+    # Resolves the ErrorGroup for a new ErrorLog.
+    #
+    # Responsibilities:
+    #   - Derive the fingerprint (use the caller-supplied one, or compute from
+    #     the log's structural identity if none was given).
+    #   - Find an existing group for that fingerprint and increment its
+    #     occurrence tracking.
+    #   - Create a brand-new group when none exists yet.
+    #   - Handle the concurrent-insert race condition transparently.
+    class GroupResolver
+      def initialize(error_log)
+        @error_log = error_log
+      end
+
+      def call
+        existing = ErrorGroup.find_by(project: error_log.project, fingerprint: fingerprint)
+        return bump_occurrence(existing) if existing
+
+        create_group
+      rescue ActiveRecord::RecordNotUnique
+        # A concurrent request won the INSERT race. Find the winner and record
+        # this occurrence against it so the count stays accurate.
+        bump_occurrence(ErrorGroup.find_by!(project: error_log.project, fingerprint: fingerprint))
+      end
+
+      private
+
+      attr_reader :error_log
+
+      def fingerprint
+        @fingerprint ||= error_log.error_fingerprint.presence ||
+                         ErrorGroup.compute_fingerprint(error_log)
+      end
+
+      def versions
+        { backend_version: error_log.backend_version, client_version: error_log.client_version }
+      end
+
+      def bump_occurrence(group)
+        group.record_occurrence!(**versions)
+        group
+      end
+
+      def create_group
+        now = Time.current
+        ErrorGroup.create!(
+          project: error_log.project,
+          fingerprint: fingerprint,
+          source_type: error_log.source_type,
+          source_name: error_log.source_name,
+          error_message: error_log.error_message,
+          original_backtrace: error_log.original_backtrace,
+          cleaned_backtrace: error_log.cleaned_backtrace,
+          backend_version: error_log.backend_version,
+          client_version: error_log.client_version,
+          status: ErrorGroup::OPEN,
+          first_seen_at: now,
+          last_seen_at: now,
+          occurrence_count: 1
+        )
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,28 @@
+Chronicle::Engine.routes.draw do
+  # Auth (admin login only — sync endpoints removed, no longer needed as a separate service)
+  get 'auth/login', to: 'auth#login'
+
+  # API log updates + metrics (create is handled internally via service/buffer, not HTTP)
+  resources :api_logs, only: [] do
+    collection do
+      put  ':request_id', to: 'api_logs#update', as: :update
+      get  :kpi_cards
+      get  :distribution_metrics
+    end
+  end
+
+  # Error log deletion (create is handled internally via Chronicle.log_error)
+  resources :error_logs, only: [:destroy]
+
+  # Admin-only reads and management
+  scope :admin, as: :admin do
+    resources :api_logs,    only: [:index, :show]
+    resources :error_logs,  only: [:index, :show]
+    resources :error_groups, only: [:index, :show, :update]
+    resources :api_routes, only: [:index] do
+      collection do
+        get :stats
+      end
+    end
+  end
+end

data/db/migrate/20260101000001_create_chronicle_admin_users.rb

@@ -0,0 +1,16 @@
+class CreateChronicleAdminUsers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :chronicle_admin_users do |t|
+      t.string :email,           null: false
+      t.string :name,            null: false
+      t.string :password_digest, null: false
+      t.string :auth_token,      null: false
+      t.integer :role,           default: 0, null: false
+
+      t.timestamps
+    end
+
+    add_index :chronicle_admin_users, :email,      unique: true
+    add_index :chronicle_admin_users, :auth_token, unique: true
+  end
+end

data/db/migrate/20260101000002_create_chronicle_api_logs.rb

@@ -0,0 +1,32 @@
+class CreateChronicleApiLogs < ActiveRecord::Migration[7.1]
+  def change
+    create_table :chronicle_api_logs do |t|
+      t.bigint  :user_id
+      t.string  :request_id
+      t.string  :device_os
+      t.string  :device_id
+      t.string  :device_type
+      t.string  :device_model_name
+      t.string  :brand
+      t.string  :os_version
+      t.string  :time_zone
+      t.string  :client_version
+      t.string  :backend_version
+      t.string  :ip_address
+      t.string  :http_method
+      t.string  :api_endpoint
+      t.integer :http_status_code
+      t.integer :response_time_ms
+      t.integer :frontend_response_time_ms
+      t.datetime :timestamp
+      t.json    :path_params
+      t.json    :meta
+
+      t.timestamps
+    end
+
+    add_index :chronicle_api_logs, :user_id
+    add_index :chronicle_api_logs, :request_id
+    add_index :chronicle_api_logs, :timestamp
+  end
+end

data/db/migrate/20260101000003_create_chronicle_api_routes.rb

@@ -0,0 +1,13 @@
+class CreateChronicleApiRoutes < ActiveRecord::Migration[7.1]
+  def change
+    create_table :chronicle_api_routes do |t|
+      t.string   :path,        null: false
+      t.string   :http_method, null: false
+      t.datetime :first_seen_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :chronicle_api_routes, [:path, :http_method], unique: true, name: 'index_chronicle_api_routes_on_path_and_method'
+  end
+end

data/db/migrate/20260101000004_create_chronicle_error_groups.rb

@@ -0,0 +1,26 @@
+class CreateChronicleErrorGroups < ActiveRecord::Migration[7.1]
+  def change
+    create_table :chronicle_error_groups do |t|
+      t.string  :project,            null: false
+      t.string  :fingerprint,        null: false
+      t.string  :source_type,        null: false
+      t.string  :source_name,        null: false
+      t.string  :error_message,      null: false
+      t.text    :original_backtrace
+      t.text    :cleaned_backtrace
+      t.string  :status,             null: false, default: 'open'
+      t.integer :occurrence_count,   null: false, default: 0
+      t.string  :jira_link
+      t.string  :backend_version
+      t.string  :client_version
+      t.datetime :first_seen_at,     null: false
+      t.datetime :last_seen_at,      null: false
+
+      t.timestamps
+    end
+
+    add_index :chronicle_error_groups, [:project, :fingerprint], unique: true, name: 'index_chronicle_error_groups_on_project_and_fingerprint'
+    add_index :chronicle_error_groups, :status
+    add_index :chronicle_error_groups, :last_seen_at
+  end
+end

data/db/migrate/20260101000005_create_chronicle_error_logs.rb

@@ -0,0 +1,19 @@
+class CreateChronicleErrorLogs < ActiveRecord::Migration[7.1]
+  def change
+    create_table :chronicle_error_logs do |t|
+      t.bigint :error_group_id, null: false
+      t.bigint :user_id
+      t.string :request_id
+      t.string :backend_version
+      t.string :client_version
+      t.json   :context
+
+      t.timestamps
+    end
+
+    add_index :chronicle_error_logs, :error_group_id
+    add_index :chronicle_error_logs, :user_id
+
+    add_foreign_key :chronicle_error_logs, :chronicle_error_groups, column: :error_group_id
+  end
+end

data/lib/chronicle/configuration.rb

@@ -0,0 +1,56 @@
+module Chronicle
+  class Configuration
+    attr_accessor :user_class,
+                  :admin_user_class,
+                  :api_token,
+                  :project_name,
+                  :backend_version,
+                  :api_log_buffer,
+                  :api_log_flush_interval,
+                  :api_log_flush_size,
+                  :api_log_buffer_dir,
+                  :skip_paths,
+                  :skip_api_log_proc,
+                  :disable_api_logging,
+                  :disable_error_logging
+
+    def initialize
+      @user_class             = nil
+      @admin_user_class       = 'Chronicle::AdminUser'
+      @api_token              = nil
+      @project_name           = nil
+      @backend_version        = -> {}
+      @api_log_buffer         = :file
+      @api_log_flush_interval = 30
+      @api_log_flush_size     = 500
+      @api_log_buffer_dir     = nil
+      @skip_paths             = []
+      @skip_api_log_proc      = nil
+      @disable_api_logging    = false
+      @disable_error_logging  = false
+    end
+
+    def user_model
+      return nil if user_class.nil?
+      user_class.is_a?(String) ? user_class.constantize : user_class
+    end
+
+    def admin_user_model
+      admin_user_class.is_a?(String) ? admin_user_class.constantize : admin_user_class
+    end
+
+    def resolved_backend_version
+      backend_version.respond_to?(:call) ? backend_version.call : backend_version
+    end
+
+    def api_logging_disabled?
+      val = disable_api_logging
+      val.respond_to?(:call) ? val.call : val
+    end
+
+    def error_logging_disabled?
+      val = disable_error_logging
+      val.respond_to?(:call) ? val.call : val
+    end
+  end
+end

data/lib/chronicle/engine.rb

@@ -0,0 +1,12 @@
+module Chronicle
+  class Engine < ::Rails::Engine
+    isolate_namespace Chronicle
+
+    config.generators.api_only = true
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.factory_bot dir: 'spec/factories'
+    end
+  end
+end

data/lib/chronicle/util.rb

@@ -0,0 +1,26 @@
+module Chronicle
+  module Util
+    class << self
+      def coerce_to_hash(input)
+        case input
+        when Hash
+          input
+        when ActionController::Parameters
+          input.to_unsafe_h
+        else
+          raise ArgumentError, 'Input expected to be a hash'
+        end
+      end
+
+      def parse_date(str)
+        return nil if str.blank?
+
+        begin
+          Date.parse(str)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/chronicle/version.rb

@@ -0,0 +1,3 @@
+module Chronicle
+  VERSION = '0.1.0'.freeze
+end

data/lib/chronicle-rails.rb

@@ -0,0 +1 @@
+require 'chronicle'

data/lib/chronicle.rb

@@ -0,0 +1,70 @@
+require 'chronicle/version'
+require 'chronicle/configuration'
+require 'chronicle/util'
+require 'chronicle/engine'
+
+module Chronicle
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def config
+      configuration
+    end
+
+    # Buffers an API log payload to a per-process file. The buffer is
+    # drained periodically by Chronicle::FlushApiLogsJob, and opportunistically
+    # when the configured flush size is exceeded.
+    def buffer_api_log(payload)
+      return if configuration.api_logging_disabled?
+      ApiLogs::Buffer.append(payload)
+    end
+
+    # Bulk-inserts API log payloads directly, bypassing the file buffer.
+    # Intended for tests, backfills, or hosts that implement their own buffering.
+    def bulk_log_api(payloads)
+      return if configuration.api_logging_disabled?
+      return if payloads.blank?
+
+      now = Time.current
+      allowed = ApiLog.column_names - ['id']
+      rows = payloads.map do |raw|
+        row = raw.respond_to?(:stringify_keys) ? raw.stringify_keys.slice(*allowed) : raw.slice(*allowed)
+        row['created_at'] ||= now
+        row['updated_at'] ||= now
+        row
+      end
+
+      rows.each_slice(ApiLogs::Flusher::INSERT_BATCH_SIZE) do |batch|
+        ApiLog.insert_all(batch) # rubocop:disable Rails/SkipsModelValidations
+      end
+
+      ApiLogs::Flusher.sync_routes(rows)
+    end
+
+    # Synchronously creates an ErrorLog. The model's before_validation hook
+    # routes it through ErrorLogs::GroupResolver for fingerprint dedup.
+    def log_error(payload)
+      return if configuration.error_logging_disabled?
+      ErrorLog.create!(payload)
+    end
+
+    # Drains all per-PID buffer files into the database. Safe to run
+    # concurrently — atomic file renames prevent double-processing.
+    def flush_api_logs!
+      ApiLogs::Flusher.call
+    end
+  end
+end

data/lib/tasks/chronicle_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :chronicle do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: chronicle-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sathwik Anil
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Chronicle is a mountable Rails engine that captures API request logs,
+  error logs, and exposesadmin endpoints for observability. Designed to be embedded
+  into any Rails application as adrop-in observability layer.
+email:
+- sathwik139@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/chronicle/api_logs_controller.rb
+- app/controllers/chronicle/api_routes_controller.rb
+- app/controllers/chronicle/application_controller.rb
+- app/controllers/chronicle/auth_controller.rb
+- app/controllers/chronicle/error_groups_controller.rb
+- app/controllers/chronicle/error_logs_controller.rb
+- app/controllers/chronicle/resource_controller.rb
+- app/controllers/concerns/chronicle/filterable.rb
+- app/controllers/concerns/chronicle/pagination.rb
+- app/errors/chronicle/authentication_error.rb
+- app/errors/chronicle/bad_request_error.rb
+- app/errors/chronicle/base_error.rb
+- app/errors/chronicle/forbidden_error.rb
+- app/errors/chronicle/not_acceptable_error.rb
+- app/errors/chronicle/not_found_error.rb
+- app/errors/chronicle/resource_busy_error.rb
+- app/errors/chronicle/validation_error.rb
+- app/jobs/chronicle/application_job.rb
+- app/jobs/chronicle/flush_api_logs_job.rb
+- app/mailers/chronicle/application_mailer.rb
+- app/models/chronicle/admin_user.rb
+- app/models/chronicle/api_log.rb
+- app/models/chronicle/api_route.rb
+- app/models/chronicle/application_record.rb
+- app/models/chronicle/error_group.rb
+- app/models/chronicle/error_log.rb
+- app/services/chronicle/api_logs/buffer.rb
+- app/services/chronicle/api_logs/flusher.rb
+- app/services/chronicle/api_logs/metrics.rb
+- app/services/chronicle/api_logs/updater.rb
+- app/services/chronicle/api_routes/stats.rb
+- app/services/chronicle/error_logs/group_resolver.rb
+- config/routes.rb
+- db/migrate/20260101000001_create_chronicle_admin_users.rb
+- db/migrate/20260101000002_create_chronicle_api_logs.rb
+- db/migrate/20260101000003_create_chronicle_api_routes.rb
+- db/migrate/20260101000004_create_chronicle_error_groups.rb
+- db/migrate/20260101000005_create_chronicle_error_logs.rb
+- lib/chronicle-rails.rb
+- lib/chronicle.rb
+- lib/chronicle/configuration.rb
+- lib/chronicle/engine.rb
+- lib/chronicle/util.rb
+- lib/chronicle/version.rb
+- lib/tasks/chronicle_tasks.rake
+homepage: https://github.com/Wildcats-Dev/chronicle-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Wildcats-Dev/chronicle-rails
+  source_code_uri: https://github.com/Wildcats-Dev/chronicle-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Pluggable Rails engine for API request and error logging.
+test_files: []