sinaliza 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9347558f2c9e741fe50da41cfd1f43835d03df264036a1d584f2f5e0806e598b
+  data.tar.gz: 86d025a67d8e219f120cb7f8e6b0631298a1b81ed20d4045096c4e3e9a7cb7a7
+SHA512:
+  metadata.gz: 9f557f39a26baab6127cbc66cdb24920186ce4e8d43845b93448445204e9b933be9025662da4a18597365a06e3d0ff7f67ce37ef4990f22a8fb731919da26f5a
+  data.tar.gz: df3fdc8f2cf43839a962a9e6e4529e0c8ba407f59fda8899e4bdb9fa787cc4644f0a84770346e1bcfd05ad700f53ab5ff5148743bfa2fa13434dbe4e075cbb67

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Marcelo Moraes
+
+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,186 @@
+# Sinaliza
+
+A Rails engine for recording and browsing application events. Track user actions, system events, and anything worth logging — from models, controllers, or anywhere in your code.
+
+Events are stored in the database and viewable through a mountable monitor dashboard.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "sinaliza", github: "marcelonmoraes/sinaliza"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails sinaliza:install:migrations
+bin/rails db:migrate
+```
+
+Mount the engine in your `config/routes.rb`:
+
+```ruby
+mount Sinaliza::Engine => "/sinaliza"
+```
+
+## Usage
+
+### Direct recording
+
+```ruby
+# Synchronous
+Sinaliza.record(name: "user.signed_up", actor: user, metadata: { plan: "pro" })
+
+# Asynchronous (via ActiveJob)
+Sinaliza.record_later(name: "report.generated", target: report)
+```
+
+Both methods accept:
+
+| Parameter    | Description                          | Default               |
+|-------------|--------------------------------------|-----------------------|
+| `name`      | Event name (required)                | —                     |
+| `actor`     | Who performed the action (any model) | `nil`                 |
+| `target`    | What was acted upon (any model)      | `nil`                 |
+| `metadata`  | Arbitrary hash of extra data         | `{}`                  |
+| `source`    | Origin label                         | `"manual"`            |
+| `ip_address`| IP address                           | `nil`                 |
+| `user_agent`| User agent string                    | `nil`                 |
+| `request_id`| Request ID                           | `nil`                 |
+
+### Model concern — `Sinaliza::Trackable`
+
+Include in any model to get event associations and helper methods:
+
+```ruby
+class User < ApplicationRecord
+  include Sinaliza::Trackable
+end
+```
+
+This gives you:
+
+```ruby
+user.events_as_actor   # events where user is the actor
+user.events_as_target  # events where user is the target
+
+user.track_event("profile.updated", metadata: { field: "email" })
+user.track_event("post.published", target: post)
+
+post.track_event_as_target("post.featured", actor: admin)
+```
+
+Events are recorded with `source: "model"`. When an actor or target is destroyed, associated events are preserved with nullified references (`dependent: :nullify`).
+
+### Controller concern — `Sinaliza::Traceable`
+
+Include in any controller to track actions declaratively or manually:
+
+```ruby
+class OrdersController < ApplicationController
+  include Sinaliza::Traceable
+
+  # Declarative — runs as an after_action callback
+  track_event "orders.listed", only: :index
+  track_event "order.viewed", only: :show, metadata: -> { { order_id: params[:id] } }
+
+  # Conditional tracking
+  track_event "order.created", only: :create, if: -> { response.successful? }
+
+  def refund
+    order = Order.find(params[:id])
+    order.refund!
+
+    # Manual — call anywhere in an action
+    record_event("order.refunded", target: order, metadata: { reason: params[:reason] })
+
+    redirect_to order
+  end
+end
+```
+
+Events are recorded with `source: "controller"`. Request context (IP address, user agent, request ID) is captured automatically based on configuration.
+
+The actor is resolved by calling the method defined in `Sinaliza.configuration.actor_method` (default: `current_user`).
+
+### Query scopes
+
+```ruby
+Sinaliza::Event.by_name("user.login")
+Sinaliza::Event.by_source("controller")
+Sinaliza::Event.by_actor_type("User")
+Sinaliza::Event.since(1.week.ago)
+Sinaliza::Event.before(Date.yesterday)
+Sinaliza::Event.between(1.week.ago, 1.day.ago)
+Sinaliza::Event.search("login")
+Sinaliza::Event.chronological          # oldest first
+Sinaliza::Event.reverse_chronological  # newest first
+```
+
+Scopes are chainable:
+
+```ruby
+Sinaliza::Event.by_name("order.created").by_actor_type("User").since(1.day.ago)
+```
+
+## Dashboard
+
+The engine mounts a monitor dashboard at your chosen path. It provides:
+
+- Paginated event list (cursor-based, 50 per page)
+- Filtering by name, source, actor type, date range, and free-text search
+- Detail view for each event with formatted JSON metadata
+
+### Protecting the dashboard
+
+The gem does not include authentication. Protect access via route constraints in your host app:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(u) { u.admin? } do
+  mount Sinaliza::Engine => "/sinaliza"
+end
+
+# or with a simple constraint
+mount Sinaliza::Engine => "/sinaliza", constraints: AdminConstraint.new
+```
+
+## Configuration
+
+```ruby
+# config/initializers/sinaliza.rb
+Sinaliza.configure do |config|
+  # Controller method used to resolve the actor (default: :current_user)
+  config.actor_method = :current_user
+
+  # Default source label for Sinaliza.record calls (default: "manual")
+  config.default_source = "manual"
+
+  # Capture IP, user agent, and request ID in controller events (default: true)
+  config.record_request_info = true
+
+  # Auto-purge events older than this duration (default: nil — no purging)
+  config.purge_after = 90.days
+end
+```
+
+## Purging old events
+
+If `purge_after` is configured, run the rake task to delete old events:
+
+```bash
+bin/rails sinaliza:purge
+```
+
+Schedule it with cron, Heroku Scheduler, or whatever you prefer.
+
+## Database schema
+
+Events are stored in a single `sinaliza_events` table with polymorphic `actor` and `target` columns. The `metadata` column uses `json` type for cross-database compatibility (SQLite, PostgreSQL, MySQL).
+
+## 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,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

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

@@ -0,0 +1,173 @@
+.sinaliza-dashboard {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 20px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  color: #1a1a1a;
+}
+
+.sinaliza-dashboard h1 {
+  font-size: 24px;
+  font-weight: 600;
+  margin-bottom: 20px;
+}
+
+/* Filters */
+.sinaliza-filters {
+  background: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 6px;
+  padding: 16px;
+  margin-bottom: 20px;
+}
+
+.sinaliza-filters__row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  align-items: flex-end;
+}
+
+.sinaliza-filters__field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.sinaliza-filters__field label {
+  font-size: 12px;
+  font-weight: 600;
+  color: #495057;
+}
+
+.sinaliza-filters__field input,
+.sinaliza-filters__field select {
+  padding: 6px 10px;
+  border: 1px solid #ced4da;
+  border-radius: 4px;
+  font-size: 13px;
+}
+
+.sinaliza-filters__actions {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.sinaliza-filters__actions button {
+  padding: 6px 16px;
+  background: #0d6efd;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  font-size: 13px;
+  cursor: pointer;
+}
+
+.sinaliza-filters__actions button:hover {
+  background: #0b5ed7;
+}
+
+/* Table */
+.sinaliza-table {
+  width: 100%;
+  border-collapse: collapse;
+  background: white;
+}
+
+.sinaliza-table th,
+.sinaliza-table td {
+  padding: 10px 12px;
+  text-align: left;
+  border-bottom: 1px solid #dee2e6;
+}
+
+.sinaliza-table th {
+  font-weight: 600;
+  font-size: 12px;
+  color: #495057;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  background: #f8f9fa;
+}
+
+.sinaliza-table tbody tr:hover {
+  background: #f8f9fa;
+}
+
+.sinaliza-time {
+  white-space: nowrap;
+  color: #6c757d;
+  font-size: 13px;
+}
+
+/* Detail table */
+.sinaliza-detail {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.sinaliza-detail th,
+.sinaliza-detail td {
+  padding: 10px 12px;
+  border-bottom: 1px solid #dee2e6;
+  vertical-align: top;
+}
+
+.sinaliza-detail th {
+  width: 140px;
+  font-weight: 600;
+  color: #495057;
+  text-align: right;
+  background: #f8f9fa;
+}
+
+/* Badges */
+.sinaliza-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  background: #e9ecef;
+  color: #495057;
+}
+
+.sinaliza-badge--source {
+  background: #d1ecf1;
+  color: #0c5460;
+}
+
+/* Links */
+.sinaliza-link {
+  color: #0d6efd;
+  text-decoration: none;
+}
+
+.sinaliza-link:hover {
+  text-decoration: underline;
+}
+
+/* JSON */
+.sinaliza-json {
+  background: #f8f9fa;
+  padding: 10px;
+  border-radius: 4px;
+  font-size: 13px;
+  overflow-x: auto;
+  margin: 0;
+}
+
+/* Empty state */
+.sinaliza-empty {
+  text-align: center;
+  color: #6c757d;
+  padding: 40px;
+}
+
+/* Pagination */
+.sinaliza-pagination {
+  padding: 16px 0;
+  text-align: center;
+}

data/app/controllers/concerns/sinaliza/traceable.rb

@@ -0,0 +1,47 @@
+module Sinaliza
+  module Traceable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def track_event(name, only: nil, except: nil, metadata: {}, if: nil)
+        callback_options = {}
+        callback_options[:only] = only if only
+        callback_options[:except] = except if except
+        callback_options[:if] = binding.local_variable_get(:if) if binding.local_variable_get(:if)
+
+        after_action(**callback_options) do
+          resolved_metadata = metadata.is_a?(Proc) ? instance_exec(&metadata) : metadata
+          record_event(name, metadata: resolved_metadata)
+        end
+      end
+    end
+
+    private
+
+    def record_event(name, target: nil, parent: nil, metadata: {})
+      actor = resolve_actor
+
+      attributes = {
+        name: name,
+        actor: actor,
+        target: target,
+        parent: parent,
+        metadata: metadata,
+        source: "controller"
+      }
+
+      if Sinaliza.configuration.record_request_info
+        attributes[:ip_address] = request.remote_ip
+        attributes[:user_agent] = request.user_agent
+        attributes[:request_id] = request.request_id
+      end
+
+      Sinaliza.record(**attributes)
+    end
+
+    def resolve_actor
+      method = Sinaliza.configuration.actor_method
+      send(method) if respond_to?(method, true)
+    end
+  end
+end

data/app/controllers/sinaliza/application_controller.rb

@@ -0,0 +1,4 @@
+module Sinaliza
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/sinaliza/events_controller.rb

@@ -0,0 +1,41 @@
+module Sinaliza
+  class EventsController < ApplicationController
+    PER_PAGE = 50
+
+    def index
+      @events = Event.roots.reverse_chronological
+
+      apply_filters
+      apply_cursor_pagination
+
+      @filter_names = Event.distinct.pluck(:name).sort
+      @filter_sources = Event.distinct.pluck(:source).sort
+      @filter_actor_types = Event.where.not(actor_type: nil).distinct.pluck(:actor_type).sort
+    end
+
+    def show
+      @event = Event.find(params[:id])
+      @children = @event.children.reverse_chronological
+    end
+
+    private
+
+    def apply_filters
+      @events = @events.by_name(params[:name]) if params[:name].present?
+      @events = @events.by_source(params[:source]) if params[:source].present?
+      @events = @events.by_actor_type(params[:actor_type]) if params[:actor_type].present?
+      @events = @events.search(params[:q]) if params[:q].present?
+      @events = @events.since(Date.parse(params[:since])) if params[:since].present?
+      @events = @events.before(Date.parse(params[:before]).end_of_day) if params[:before].present?
+    end
+
+    def apply_cursor_pagination
+      @events = @events.where("sinaliza_events.id < ?", params[:before_id].to_i) if params[:before_id].present?
+      @events = @events.limit(PER_PAGE + 1).to_a
+
+      @has_next_page = @events.size > PER_PAGE
+      @events = @events.first(PER_PAGE)
+      @next_cursor = @events.last&.id if @has_next_page
+    end
+  end
+end

data/app/helpers/sinaliza/application_helper.rb

@@ -0,0 +1,4 @@
+module Sinaliza
+  module ApplicationHelper
+  end
+end

data/app/jobs/sinaliza/application_job.rb

@@ -0,0 +1,4 @@
+module Sinaliza
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/sinaliza/record_event_job.rb

@@ -0,0 +1,19 @@
+module Sinaliza
+  class RecordEventJob < ApplicationJob
+    queue_as :default
+
+    def perform(attributes)
+      attributes = attributes.symbolize_keys
+
+      if attributes[:actor].is_a?(String)
+        attributes[:actor] = GlobalID::Locator.locate(attributes[:actor])
+      end
+
+      if attributes[:target].is_a?(String)
+        attributes[:target] = GlobalID::Locator.locate(attributes[:target])
+      end
+
+      Sinaliza::Event.create!(attributes)
+    end
+  end
+end

data/app/mailers/sinaliza/application_mailer.rb

@@ -0,0 +1,6 @@
+module Sinaliza
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/concerns/sinaliza/trackable.rb

@@ -0,0 +1,39 @@
+module Sinaliza
+  module Trackable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :events_as_actor,
+               class_name: "Sinaliza::Event",
+               as: :actor,
+               dependent: :nullify
+
+      has_many :events_as_target,
+               class_name: "Sinaliza::Event",
+               as: :target,
+               dependent: :nullify
+    end
+
+    def track_event(name, target: nil, parent: nil, metadata: {})
+      Sinaliza.record(
+        name: name,
+        actor: self,
+        target: target,
+        parent: parent,
+        metadata: metadata,
+        source: "model"
+      )
+    end
+
+    def track_event_as_target(name, actor: nil, parent: nil, metadata: {})
+      Sinaliza.record(
+        name: name,
+        actor: actor,
+        target: self,
+        parent: parent,
+        metadata: metadata,
+        source: "model"
+      )
+    end
+  end
+end

data/app/models/sinaliza/application_record.rb

@@ -0,0 +1,5 @@
+module Sinaliza
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/sinaliza/event.rb

@@ -0,0 +1,32 @@
+module Sinaliza
+  class Event < ApplicationRecord
+    belongs_to :actor, polymorphic: true, optional: true
+    belongs_to :target, polymorphic: true, optional: true
+    belongs_to :parent, class_name: "Sinaliza::Event", optional: true
+
+    has_many :children, class_name: "Sinaliza::Event", foreign_key: :parent_id, dependent: :destroy
+
+    validates :name, presence: true
+
+    scope :by_name, ->(name) { where(name: name) }
+    scope :by_source, ->(source) { where(source: source) }
+    scope :by_actor_type, ->(type) { where(actor_type: type) }
+    scope :since, ->(time) { where(created_at: time..) }
+    scope :before, ->(time) { where(created_at: ..time) }
+    scope :between, ->(from, to) { where(created_at: from..to) }
+    scope :chronological, -> { order(created_at: :asc) }
+    scope :reverse_chronological, -> { order(created_at: :desc) }
+    scope :roots, -> { where(parent_id: nil) }
+    scope :search, ->(query) {
+      where("name LIKE :q OR source LIKE :q OR actor_type LIKE :q OR target_type LIKE :q", q: "%#{query}%")
+    }
+
+    def root?
+      parent_id.nil?
+    end
+
+    def child?
+      parent_id.present?
+    end
+  end
+end

data/app/views/layouts/sinaliza/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Sinaliza</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "sinaliza/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/sinaliza/events/_filters.html.erb

@@ -0,0 +1,53 @@
+<form method="get" action="<%= events_path %>" class="sinaliza-filters">
+  <div class="sinaliza-filters__row">
+    <div class="sinaliza-filters__field">
+      <label for="q">Search</label>
+      <input type="text" name="q" id="q" value="<%= params[:q] %>" placeholder="Search events...">
+    </div>
+
+    <div class="sinaliza-filters__field">
+      <label for="name">Name</label>
+      <select name="name" id="name">
+        <option value="">All</option>
+        <% @filter_names.each do |name| %>
+          <option value="<%= name %>" <%= "selected" if params[:name] == name %>><%= name %></option>
+        <% end %>
+      </select>
+    </div>
+
+    <div class="sinaliza-filters__field">
+      <label for="source">Source</label>
+      <select name="source" id="source">
+        <option value="">All</option>
+        <% @filter_sources.each do |source| %>
+          <option value="<%= source %>" <%= "selected" if params[:source] == source %>><%= source %></option>
+        <% end %>
+      </select>
+    </div>
+
+    <div class="sinaliza-filters__field">
+      <label for="actor_type">Actor type</label>
+      <select name="actor_type" id="actor_type">
+        <option value="">All</option>
+        <% @filter_actor_types.each do |type| %>
+          <option value="<%= type %>" <%= "selected" if params[:actor_type] == type %>><%= type %></option>
+        <% end %>
+      </select>
+    </div>
+
+    <div class="sinaliza-filters__field">
+      <label for="since">Since</label>
+      <input type="date" name="since" id="since" value="<%= params[:since] %>">
+    </div>
+
+    <div class="sinaliza-filters__field">
+      <label for="before">Before</label>
+      <input type="date" name="before" id="before" value="<%= params[:before] %>">
+    </div>
+
+    <div class="sinaliza-filters__actions">
+      <button type="submit">Filter</button>
+      <a href="<%= events_path %>" class="sinaliza-link">Clear</a>
+    </div>
+  </div>
+</form>

data/app/views/sinaliza/events/index.html.erb

@@ -0,0 +1,45 @@
+<div class="sinaliza-dashboard">
+  <h1>Events Monitor</h1>
+
+  <%= render "filters" %>
+
+  <table class="sinaliza-table">
+    <thead>
+      <tr>
+        <th>Time</th>
+        <th>Name</th>
+        <th>Source</th>
+        <th>Actor</th>
+        <th>Target</th>
+        <th>Children</th>
+        <th></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @events.each do |event| %>
+        <tr>
+          <td class="sinaliza-time"><%= event.created_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+          <td><span class="sinaliza-badge"><%= event.name %></span></td>
+          <td><span class="sinaliza-badge sinaliza-badge--source"><%= event.source %></span></td>
+          <td><%= event.actor ? "#{event.actor_type}##{event.actor_id}" : "-" %></td>
+          <td><%= event.target ? "#{event.target_type}##{event.target_id}" : "-" %></td>
+          <td><%= event.children.size %></td>
+          <td><%= link_to "Detail", event_path(event), class: "sinaliza-link" %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <% if @events.empty? %>
+    <p class="sinaliza-empty">No events found.</p>
+  <% end %>
+
+  <% if @has_next_page %>
+    <div class="sinaliza-pagination">
+      <%
+        pagination_params = request.query_parameters.merge(before_id: @next_cursor)
+      %>
+      <%= link_to "Older events", events_path(pagination_params), class: "sinaliza-link" %>
+    </div>
+  <% end %>
+</div>

data/app/views/sinaliza/events/show.html.erb

@@ -0,0 +1,79 @@
+<div class="sinaliza-dashboard">
+  <p><%= link_to "Back to events", events_path, class: "sinaliza-link" %></p>
+
+  <h1>Event #<%= @event.id %></h1>
+
+  <table class="sinaliza-detail">
+    <tr>
+      <th>Name</th>
+      <td><span class="sinaliza-badge"><%= @event.name %></span></td>
+    </tr>
+    <% if @event.parent %>
+    <tr>
+      <th>Parent</th>
+      <td><%= link_to "Event ##{@event.parent_id}", event_path(@event.parent), class: "sinaliza-link" %></td>
+    </tr>
+    <% end %>
+    <tr>
+      <th>Source</th>
+      <td><span class="sinaliza-badge sinaliza-badge--source"><%= @event.source %></span></td>
+    </tr>
+    <tr>
+      <th>Actor</th>
+      <td><%= @event.actor ? "#{@event.actor_type}##{@event.actor_id}" : "-" %></td>
+    </tr>
+    <tr>
+      <th>Target</th>
+      <td><%= @event.target ? "#{@event.target_type}##{@event.target_id}" : "-" %></td>
+    </tr>
+    <tr>
+      <th>Metadata</th>
+      <td><pre class="sinaliza-json"><%= JSON.pretty_generate(@event.metadata) %></pre></td>
+    </tr>
+    <tr>
+      <th>IP address</th>
+      <td><%= @event.ip_address || "-" %></td>
+    </tr>
+    <tr>
+      <th>User agent</th>
+      <td><%= @event.user_agent || "-" %></td>
+    </tr>
+    <tr>
+      <th>Request ID</th>
+      <td><%= @event.request_id || "-" %></td>
+    </tr>
+    <tr>
+      <th>Created at</th>
+      <td><%= @event.created_at.strftime("%Y-%m-%d %H:%M:%S %Z") %></td>
+    </tr>
+  </table>
+
+  <% if @children.any? %>
+    <h2>Sub-events</h2>
+
+    <table class="sinaliza-table">
+      <thead>
+        <tr>
+          <th>Time</th>
+          <th>Name</th>
+          <th>Source</th>
+          <th>Actor</th>
+          <th>Target</th>
+          <th></th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @children.each do |child| %>
+          <tr>
+            <td class="sinaliza-time"><%= child.created_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+            <td><span class="sinaliza-badge"><%= child.name %></span></td>
+            <td><span class="sinaliza-badge sinaliza-badge--source"><%= child.source %></span></td>
+            <td><%= child.actor ? "#{child.actor_type}##{child.actor_id}" : "-" %></td>
+            <td><%= child.target ? "#{child.target_type}##{child.target_id}" : "-" %></td>
+            <td><%= link_to "Detail", event_path(child), class: "sinaliza-link" %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>

data/config/routes.rb

@@ -0,0 +1,4 @@
+Sinaliza::Engine.routes.draw do
+  resources :events, only: [ :index, :show ]
+  root to: "events#index"
+end

data/db/migrate/20260219000000_create_sinaliza_events.rb

@@ -0,0 +1,20 @@
+class CreateSinalizaEvents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :sinaliza_events do |t|
+      t.string :name, null: false
+      t.references :actor, polymorphic: true, index: true
+      t.references :target, polymorphic: true, index: true
+      t.json :metadata, default: {}
+      t.string :source, default: "manual"
+      t.string :ip_address
+      t.string :user_agent
+      t.string :request_id
+
+      t.timestamps
+    end
+
+    add_index :sinaliza_events, :name
+    add_index :sinaliza_events, :source
+    add_index :sinaliza_events, :created_at
+  end
+end

data/db/migrate/20260219100000_add_parent_id_to_sinaliza_events.rb

@@ -0,0 +1,5 @@
+class AddParentIdToSinalizaEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :sinaliza_events, :parent, null: true, foreign_key: { to_table: :sinaliza_events }, index: true
+  end
+end

data/lib/sinaliza/configuration.rb

@@ -0,0 +1,12 @@
+module Sinaliza
+  class Configuration
+    attr_accessor :actor_method, :default_source, :record_request_info, :purge_after
+
+    def initialize
+      @actor_method = :current_user
+      @default_source = "manual"
+      @record_request_info = true
+      @purge_after = nil
+    end
+  end
+end

data/lib/sinaliza/engine.rb

@@ -0,0 +1,5 @@
+module Sinaliza
+  class Engine < ::Rails::Engine
+    isolate_namespace Sinaliza
+  end
+end

data/lib/sinaliza/version.rb

@@ -0,0 +1,3 @@
+module Sinaliza
+  VERSION = "0.1.0"
+end

data/lib/sinaliza.rb

@@ -0,0 +1,48 @@
+require "sinaliza/version"
+require "sinaliza/engine"
+require "sinaliza/configuration"
+
+module Sinaliza
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def record(name:, actor: nil, target: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
+      parent_id = parent.is_a?(Sinaliza::Event) ? parent.id : parent
+
+      Sinaliza::Event.create!(
+        name: name,
+        actor: actor,
+        target: target,
+        parent_id: parent_id,
+        metadata: metadata,
+        source: source || configuration.default_source,
+        ip_address: ip_address,
+        user_agent: user_agent,
+        request_id: request_id
+      )
+    end
+
+    def record_later(name:, actor: nil, target: nil, parent: nil, metadata: {}, source: nil, ip_address: nil, user_agent: nil, request_id: nil)
+      attributes = {
+        name: name,
+        metadata: metadata,
+        source: source || configuration.default_source,
+        ip_address: ip_address,
+        user_agent: user_agent,
+        request_id: request_id
+      }
+
+      attributes[:actor] = actor.to_global_id.to_s if actor
+      attributes[:target] = target.to_global_id.to_s if target
+      attributes[:parent_id] = parent.is_a?(Sinaliza::Event) ? parent.id : parent if parent
+
+      Sinaliza::RecordEventJob.perform_later(attributes)
+    end
+  end
+end

data/lib/tasks/sinaliza_tasks.rake

@@ -0,0 +1,15 @@
+namespace :sinaliza do
+  desc "Purge events older than Sinaliza.configuration.purge_after"
+  task purge: :environment do
+    purge_after = Sinaliza.configuration.purge_after
+
+    if purge_after.nil?
+      puts "No purge_after configured. Set Sinaliza.configuration.purge_after to a duration (e.g., 90.days)."
+      next
+    end
+
+    cutoff = purge_after.ago
+    count = Sinaliza::Event.where(created_at: ...cutoff).delete_all
+    puts "Purged #{count} events older than #{cutoff}."
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: sinaliza
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marcelo Moraes
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+description: Track user actions, system events, and anything worth logging — from
+  models, controllers, or anywhere in your code. Events are stored in the database
+  and viewable through a mountable monitor dashboard.
+email:
+- marcelonmoraes@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/sinaliza/application.css
+- app/controllers/concerns/sinaliza/traceable.rb
+- app/controllers/sinaliza/application_controller.rb
+- app/controllers/sinaliza/events_controller.rb
+- app/helpers/sinaliza/application_helper.rb
+- app/jobs/sinaliza/application_job.rb
+- app/jobs/sinaliza/record_event_job.rb
+- app/mailers/sinaliza/application_mailer.rb
+- app/models/concerns/sinaliza/trackable.rb
+- app/models/sinaliza/application_record.rb
+- app/models/sinaliza/event.rb
+- app/views/layouts/sinaliza/application.html.erb
+- app/views/sinaliza/events/_filters.html.erb
+- app/views/sinaliza/events/index.html.erb
+- app/views/sinaliza/events/show.html.erb
+- config/routes.rb
+- db/migrate/20260219000000_create_sinaliza_events.rb
+- db/migrate/20260219100000_add_parent_id_to_sinaliza_events.rb
+- lib/sinaliza.rb
+- lib/sinaliza/configuration.rb
+- lib/sinaliza/engine.rb
+- lib/sinaliza/version.rb
+- lib/tasks/sinaliza_tasks.rake
+homepage: https://github.com/marcelonmoraes/sinaliza
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/marcelonmoraes/sinaliza
+  source_code_uri: https://github.com/marcelonmoraes/sinaliza/tree/main
+  changelog_uri: https://github.com/marcelonmoraes/sinaliza/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Rails engine for recording and browsing application events.
+test_files: []