rails_event_viewer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 323623721d960260a7ea2077cf30edc17c4708b7c8d96ab5d9fc7320b45f8113
+  data.tar.gz: 7afbd0a2835c53520bbbb8d1f323b1643297bc8e641948c614ddc407d6791edd
+SHA512:
+  metadata.gz: f28f9dff6c4085b5c319744f19c71ae1f373dede9add4a8f5a0bda335bb088ec283e353c151cd28eb5ae71ba2d9b4a6f8c13f45bb7a03d62b687ba706b405ff9
+  data.tar.gz: 544807b6dbee7af798bce690b6b51e0ada6f168b7681d867d2b57ce634aa3995b1878ba3f3e3dbe3976d6ce55edf9bb6f069f1b4b2722988154b97b86164103c

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-09-29)
+
+Initial release.
+
+- Web dashboard for browsing, searching, and analyzing events emitted via `Rails.event` (Rails 8.1+).
+- Storage adapters: ActiveRecord (default), Redis, Memory, Null, or a custom class.
+- Buffered async ingestion with configurable buffer size, flush interval, and sampling.
+- Event filtering with `captured_events` and `ignored_events`.
+- Event groups by context or tag keys, such as `request_id`.
+- Analytics: events over time and counts by event name.
+- HTTP Basic Auth or custom authentication. The dashboard returns 403 outside development and test when neither is configured, and when Basic Auth is enabled with a blank user or password.
+- Rake tasks: `stats`, `cleanup`, `flush`, `clear`, `install:migrations`.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Keshav Biswa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,451 @@
+# RailsEventViewer
+
+A Rails engine for viewing and analyzing events emitted via `Rails.event`.
+Provides a web UI dashboard for browsing, filtering, and visualizing domain events in your Rails application.
+
+## Features
+
+- Web-based dashboard for viewing events
+- Flexible storage adapters (ActiveRecord, Redis, Memory, or custom)
+- High-performance buffered ingestion with configurable batch writes
+- Fluent query interface for programmatic access
+- Event filtering by name, tags, and time range
+- Full-text search across event names and payloads
+- Analytics with event counts over time
+- Configurable retention and automatic cleanup
+- HTTP Basic Auth or custom authentication
+
+## Requirements
+
+- Rails 8.1+
+- Ruby 3.2+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_event_viewer"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Run the install generator:
+
+```bash
+rails generate rails_event_viewer:install
+```
+
+This will:
+- Create a migration for the events table (if using ActiveRecord adapter)
+- Create an initializer with configuration options
+- Mount the engine at `/events`
+
+Run the migration:
+
+```bash
+rails db:migrate
+```
+
+## Configuration
+
+Configure RailsEventViewer in `config/initializers/rails_event_viewer.rb`:
+
+```ruby
+RailsEventViewer.configure do |config|
+  # Storage adapter: :active_record, :redis, :memory, :null, or a custom class
+  config.storage_adapter = :active_record
+
+  # Adapter-specific options
+  config.adapter_options = {}
+
+  # Performance settings
+  config.async = true              # Enable buffered writes
+  config.buffer_size = 100         # Flush after N events
+  config.flush_interval = 2        # Flush every N seconds
+  config.sample_rate = 1.0         # 1.0 = capture all, 0.1 = capture 10%
+
+  # Retention
+  config.retention_period = 7.days
+
+  # Filtering
+  config.captured_events = []      # Empty = capture all
+  config.ignored_events = []       # Events to never capture
+
+  # UI settings
+  config.per_page = 25
+
+  # Authentication (choose one)
+  config.http_basic_auth_enabled = true
+  config.http_basic_auth_user = ENV["RAILS_EVENT_VIEWER_USER"]
+  config.http_basic_auth_password = ENV["RAILS_EVENT_VIEWER_PASSWORD"]
+
+  # Or use custom authentication
+  config.authentication = ->(controller) {
+    controller.authenticate_user!
+    controller.current_user.admin?
+  }
+end
+```
+
+## Storage Adapters
+
+### ActiveRecord (default)
+
+Stores events in your database. Best for most applications with full analytics support.
+
+```ruby
+config.storage_adapter = :active_record
+```
+
+The install generator creates the migration for you. If you skipped the generator, copy the migration from the engine instead. Do not do both, or you will get two migrations for the same table.
+
+```bash
+rails rails_event_viewer:install:migrations
+rails db:migrate
+```
+
+### Redis
+
+Stores events in Redis sorted sets. Good for high-volume, ephemeral storage where you don't need long-term persistence.
+
+First, add the redis gem to your Gemfile:
+
+```ruby
+gem "redis"
+```
+
+Then configure the adapter:
+
+```ruby
+config.storage_adapter = :redis
+config.adapter_options = {
+  redis_options: { url: ENV.fetch("REDIS_URL", "redis://localhost:6379") },
+  pool_size: 5,
+  key_prefix: "rails_event_viewer",
+  max_events: 10_000
+}
+```
+
+Options:
+- `redis_options` - Hash passed to `Redis.new` whenever the pool opens a new connection (default: `{}`)
+- `pool_size` - Number of pooled Redis connections, should match your app's thread count (default: `5`)
+- `pool_timeout` - Seconds to wait for a free connection before raising (default: `5`)
+- `key_prefix` - Prefix for Redis keys (default: `"rails_event_viewer"`). The adapter wraps it in braces, so keys look like `{rails_event_viewer}:events`. The braces are a Redis Cluster hash tag that keeps every key on one node, which the adapter's multi-key commands require. Do not add braces yourself.
+- `max_events` - Maximum events to retain, older events are automatically trimmed (default: `10_000`)
+
+The adapter uses a connection pool rather than a single shared connection, since one Redis connection is not safe to use concurrently across multiple threads. Each pooled connection is built independently from `redis_options`. Pass `pool:` with your own `ConnectionPool` for full control.
+
+Note: Redis adapter performs analytics by fetching events into memory, which may be slower than ActiveRecord for large datasets.
+
+Filtered queries and analytics scan every stored event. Keep `max_events` modest, around 10,000, if you filter often.
+
+### Memory
+
+In-memory storage for development and testing.
+
+```ruby
+config.storage_adapter = :memory
+config.adapter_options = { max_events: 1000 }
+```
+
+Options:
+- `max_events` - Maximum events to retain (default: `1000`)
+
+Note: Events are lost when the server process restarts. Not recommended for production use.
+
+### Null
+
+Discards all events. Useful for disabling event capture in specific environments.
+
+```ruby
+config.storage_adapter = :null
+```
+
+### Switching Adapters via Environment Variable
+
+A common pattern is to use different adapters per environment:
+
+```ruby
+RailsEventViewer.configure do |config|
+  adapter = ENV.fetch("EVENT_STORAGE", "active_record").to_sym
+  config.storage_adapter = adapter
+
+  case adapter
+  when :redis
+    config.adapter_options = {
+      redis_options: { url: ENV.fetch("REDIS_URL", "redis://localhost:6379") },
+      max_events: 10_000
+    }
+  when :memory
+    config.adapter_options = { max_events: 1000 }
+  end
+end
+```
+
+Then switch adapters when starting your server:
+
+```bash
+# Use ActiveRecord (default)
+bin/rails server
+
+# Use Redis
+EVENT_STORAGE=redis bin/rails server
+
+# Use Memory
+EVENT_STORAGE=memory bin/rails server
+```
+
+### Custom Adapter
+
+Create your own adapter by including the `RailsEventViewer::Adapter` module:
+
+```ruby
+class MyCustomAdapter
+  include RailsEventViewer::Adapter
+
+  def write_events(events)
+  end
+
+  def fetch_events(relation)
+  end
+
+  def count_events(relation)
+  end
+
+  def distinct_event_names
+  end
+
+  def find_event(id)
+  end
+
+  def delete_before(timestamp)
+  end
+
+  def distinct_group_values(key, source: :context)
+  end
+
+  def group_instances(key, source: :context, limit: 100)
+  end
+
+  def events_over_time(since:, interval:)
+    # Return { time => count }
+  end
+
+  def counts_by_name(limit:)
+    # Return { name => count }, highest first
+  end
+
+  def count_since(since)
+    # Return count of events since a time
+  end
+end
+
+config.storage_adapter = MyCustomAdapter
+```
+
+## Emitting Events
+
+RailsEventViewer automatically subscribes to `Rails.event`. Emit events using the standard Rails API:
+
+```ruby
+Rails.event.notify("user.created", user_id: user.id, email: user.email)
+
+Rails.event.notify(
+  "order.placed",
+  order_id: order.id,
+  total: order.total,
+  tags: { environment: Rails.env, priority: "high" }
+)
+```
+
+## Programmatic Access
+
+Use the fluent query interface to access events:
+
+```ruby
+# Get all events
+RailsEventViewer.events.each { |e| puts e[:name] }
+
+# Filter by name
+RailsEventViewer.events.with_name("user.created").to_a
+
+# Filter by tag
+RailsEventViewer.events.with_tag(:environment, "production").to_a
+
+# Time range
+RailsEventViewer.events.since(1.hour.ago).until(30.minutes.ago).to_a
+
+# Search
+RailsEventViewer.events.search("user@example.com").to_a
+
+# Combine filters
+RailsEventViewer.events
+  .with_name("order.placed")
+  .with_tag(:priority, "high")
+  .since(1.day.ago)
+  .limit(50)
+  .each { |e| process(e) }
+
+# Count
+RailsEventViewer.events.with_name("user.created").count
+
+# Pagination
+RailsEventViewer.events.offset(25).limit(25).to_a
+```
+
+## Rake Tasks
+
+```bash
+# Show statistics
+bin/rails rails_event_viewer:stats
+
+# Clean up old events (based on retention_period)
+bin/rails rails_event_viewer:cleanup
+
+# Flush buffered events
+bin/rails rails_event_viewer:flush
+
+# Clear all events (interactive confirmation required)
+bin/rails rails_event_viewer:clear
+```
+
+For automatic cleanup, add to your scheduler:
+
+```yaml
+# config/recurring.yml (Solid Queue)
+production:
+  rails_event_viewer_cleanup:
+    command: "RailsEventViewer.adapter.delete_before(RailsEventViewer.retention_period.ago)"
+    schedule: every day at 3am
+```
+
+Or using the whenever gem:
+
+```ruby
+# config/schedule.rb (whenever gem)
+every 1.day, at: "3:00 am" do
+  rake "rails_event_viewer:cleanup"
+end
+```
+
+## Event Filtering
+
+Control which events are captured:
+
+```ruby
+# Only capture specific events
+config.captured_events = ["user.created", "order.placed"]
+
+# Or use regex patterns
+config.captured_events = [/^user\./, /^order\./]
+
+# Ignore specific events
+config.ignored_events = ["internal.heartbeat", /^debug\./]
+```
+
+## Sampling
+
+For high-volume applications, reduce storage by sampling if needed:
+
+```ruby
+# Capture only 10% of events
+config.sample_rate = 0.1
+```
+
+## Authentication
+
+If neither option below is configured, the dashboard is open in development and test, and returns `403 Forbidden` in every other environment, including staging. Enabling HTTP Basic Auth with a blank user or password also returns `403 Forbidden`.
+
+Set `RAILS_ENV` on every deployed server. If it is missing, Rails falls back to development and the dashboard is open.
+
+### HTTP Basic Auth
+
+```ruby
+config.http_basic_auth_enabled = true
+config.http_basic_auth_user = ENV["RAILS_EVENT_VIEWER_USER"]
+config.http_basic_auth_password = ENV["RAILS_EVENT_VIEWER_PASSWORD"]
+```
+
+### Custom Authentication
+
+```ruby
+# Devise example
+config.authentication = ->(controller) {
+  controller.authenticate_user!
+  controller.current_user.admin?
+}
+```
+
+## Routes
+
+The engine is mounted at the path specified in your routes (default `/events`):
+
+```ruby
+# config/routes.rb
+mount RailsEventViewer::Engine, at: "/events"
+```
+
+Available routes:
+- `/events` - Dashboard
+- `/events/events` - Event list with filtering
+- `/events/events/:id` - Single event detail
+- `/events/analytics/overview` - Analytics dashboard
+- `/events/groups` - Event groups
+
+## How Event Capture Works
+
+RailsEventViewer subscribes to `Rails.event` (the Structured Event Reporter introduced in Rails 8.1),
+which is built on top of `ActiveSupport::Notifications`. This means internal Rails instrumentation
+events (`sql.active_record`, `process_action.action_controller`, etc.) are received by the subscriber.
+
+By default, all internal Rails framework events are excluded via the built-in `ignored_events` patterns.
+This prevents noise from flooding your storage.
+
+**Captured by default:**
+- Application events emitted via `Rails.event.notify("my.event", ...)`
+
+**Ignored by default** (via `ignored_events`):
+- `active_record.*`, `action_controller.*`, `action_view.*`, `active_job.*`
+- `action_mailer.*`, `active_storage.*`, `action_cable.*`, `rails.*`
+- `turbo.*`, `cache_*`, `*.sql`, `solid_*`
+
+To capture internal Rails events, remove the relevant pattern from `ignored_events`:
+
+```ruby
+RailsEventViewer.configure do |config|
+  config.ignored_events = RailsEventViewer.ignored_events.reject { |p| p == /^active_record\./ }
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+cd test/dummy
+bin/rails db:migrate
+bin/rails server
+```
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/stylesheets/rails_event_viewer/application.css

@@ -0,0 +1,32 @@
+/* RailsEventViewer Application Styles */
+/* Note: Tailwind CSS is loaded via CDN in development. For production, compile using:
+   npx tailwindcss -i ./app/assets/stylesheets/rails_event_viewer/tailwind.css \
+                   -o ./app/assets/stylesheets/rails_event_viewer/application.css --minify
+*/
+
+/* Custom styles that don't require Tailwind compilation */
+.json-tree {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.875rem;
+}
+
+.json-tree-key {
+  color: #4b5563;
+  font-weight: 500;
+}
+
+.json-tree-string {
+  color: #059669;
+}
+
+.json-tree-number {
+  color: #2563eb;
+}
+
+.json-tree-boolean {
+  color: #7c3aed;
+}
+
+.json-tree-null {
+  color: #9ca3af;
+}

data/app/assets/stylesheets/rails_event_viewer/tailwind.css

@@ -0,0 +1,54 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Custom component styles */
+@layer components {
+  .btn {
+    @apply px-4 py-2 rounded-md text-sm font-medium transition-colors;
+  }
+
+  .btn-primary {
+    @apply bg-indigo-600 text-white hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2;
+  }
+
+  .btn-secondary {
+    @apply bg-white text-gray-700 border border-gray-300 hover:bg-gray-50;
+  }
+
+  .card {
+    @apply bg-white rounded-lg shadow;
+  }
+
+  .input {
+    @apply block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 sm:text-sm;
+  }
+
+  .label {
+    @apply block text-sm font-medium text-gray-700;
+  }
+
+  .badge {
+    @apply inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium;
+  }
+
+  .badge-primary {
+    @apply bg-indigo-100 text-indigo-800;
+  }
+
+  .badge-gray {
+    @apply bg-gray-100 text-gray-800;
+  }
+
+  .badge-green {
+    @apply bg-green-100 text-green-800;
+  }
+
+  .table-header {
+    @apply px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider;
+  }
+
+  .table-cell {
+    @apply px-6 py-4 whitespace-nowrap text-sm;
+  }
+}

data/app/controllers/rails_event_viewer/analytics_controller.rb

@@ -0,0 +1,78 @@
+module RailsEventViewer
+  class AnalyticsController < ApplicationController
+    before_action :check_analytics_support
+
+    def overview
+      @date_range = parse_date_range
+
+      relation = RailsEventViewer.events
+                   .since(@date_range.begin)
+                   .until(@date_range.end)
+
+      @total_events = relation.count
+      @unique_event_types = current_adapter.distinct_event_names.size
+      @events_by_type = current_adapter.counts_by_name(limit: 20)
+      @events_over_time = current_adapter.events_over_time(since: @date_range.begin, interval: period_for_range)
+
+      @avg_events_per_hour = calculate_avg_events_per_hour
+      @peak_period = find_peak_period
+    end
+
+    def events_over_time
+      since = params[:since]&.to_i&.seconds&.ago || 24.hours.ago
+      interval = params[:interval]&.to_sym || :hour
+
+      @events_data = current_adapter.events_over_time(since: since, interval: interval)
+
+      respond_to do |format|
+        format.json { render json: @events_data }
+        format.html { render partial: "events_over_time_chart" }
+      end
+    end
+
+    def events_by_type
+      limit = (params[:limit] || 20).to_i.clamp(1, 100)
+      @data = current_adapter.counts_by_name(limit: limit)
+
+      respond_to do |format|
+        format.json { render json: @data }
+        format.html { render partial: "events_by_type_chart" }
+      end
+    end
+
+    private
+
+    def check_analytics_support
+      unless analytics_supported?
+        redirect_to root_path, alert: "Analytics not supported by current storage adapter"
+      end
+    end
+
+    def parse_date_range
+      start_date = safe_parse_date(params[:start_date], default: 7.days.ago.to_date)
+      end_date = safe_parse_date(params[:end_date], default: Date.current)
+
+      start_date, end_date = end_date, start_date if start_date > end_date
+
+      start_date.beginning_of_day..end_date.end_of_day
+    end
+
+    def period_for_range
+      duration = (@date_range.end - @date_range.begin).to_i
+      duration <= 604800 ? :hour : :day
+    end
+
+    def calculate_avg_events_per_hour
+      hours = ((@date_range.end - @date_range.begin) / 3600.0).round(1)
+      return 0 if hours.zero?
+
+      (@total_events.to_f / hours).round(1)
+    end
+
+    def find_peak_period
+      return nil if @events_over_time.empty?
+
+      @events_over_time.max_by { |_, count| count }
+    end
+  end
+end