RubyGems - event_timeline - Versions diffs - 0.1.0 → 0.2.1 - Mend

event_timeline 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

checksums.yaml +4 -4
data/README.md +43 -76
data/Rakefile +3 -1
data/app/views/event_timeline/sessions/show.html.erb +69 -27
data/app/views/layouts/event_timeline/application.html.erb +59 -0
data/lib/event_timeline/call_tracker.rb +168 -158
data/lib/event_timeline/configuration.rb +23 -8
data/lib/event_timeline/engine.rb +4 -6
data/lib/event_timeline/middleware.rb +12 -2
data/lib/event_timeline/rotation_service.rb +29 -2
data/lib/event_timeline/value_filter.rb +85 -0
data/lib/event_timeline/value_inspector.rb +66 -0
data/lib/event_timeline/version.rb +1 -1
data/lib/event_timeline.rb +2 -0
data/lib/generators/event_timeline/install/install_generator.rb +42 -0
data/{db/migrate/20260103180115_create_event_timeline_sessions.rb → lib/generators/event_timeline/install/templates/create_event_timeline_sessions.rb} +2 -2
data/lib/generators/event_timeline/install/templates/initializer.rb +45 -0
metadata +42 -6

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acfe8f6da4ca9044255ba5db0c60ea66e6aaedfebd3b9c47a36eb2ace19631f6
-  data.tar.gz: 9659ba87a4dd38ac503ddb6ee5573fb6088789240472e4e9f4cbe2ff0e063983
+  metadata.gz: 7f9b39a082143ef828a48c1ba89377103062e5fd2d356658d257964727402c22
+  data.tar.gz: f332374e2650e04ae7cfe4dee1ae27d98b11d268486284afbd02ddba8def7576
 SHA512:
-  metadata.gz: 2d4e4efbc26ca24019666469a1d64d2f183f7c2264a0aecef97d61913fe018299f7fac4d00fa6e37d15f7fb39b064cd90d344bc02ba60f2e33460e309e4a3f42
-  data.tar.gz: fab0b6ee70307348d2513ade4988e94bbe1abaca374bcac8ea5b6b64a4f14519ac8bfe226841e047f3cdbc3e5c8a066b834e818abea6d5d1ca6b1662de97c1c2
+  metadata.gz: c7ff33b22475ea362d891023c7fc942e9ee85878d13fba5cf113426e3aea0ba1b48e10ad9a6f0ea101b5dd740900beaacd65b021a2a0903fc70f8d51ba2bc9b1
+  data.tar.gz: 44ccc4f17fdb6e65f247a5209cec9cea0e6f458593ad113522b1da7056f9ca846db487a1f0d6cbbbcd5faca12c6be9be5ca1c917d17ae52674f23a58d43b25e3

data/README.md CHANGED Viewed

@@ -1,128 +1,95 @@
 # EventTimeline
-Ever wished you could replay what happened during a request? EventTimeline tracks method calls in your Rails app so you can see exactly how your code executed.
+A Rails engine that records method calls during requests so you can see what actually happened.
-## What it does
+## Why?
-EventTimeline records method calls and returns as they happen, letting you:
+You get a bug report: "Order failed for user X". You check the logs, see a 500 error, but the stack trace doesn't tell you what state the app was in or what data was being processed.
-- See the exact sequence of method calls during a request
-- Inspect parameters passed to each method
-- View return values
-- Track execution flow across multiple services
-- Debug production issues by replaying what actually happened
+EventTimeline records the method calls, parameters, and return values during the request. You visit `/event_timeline/sessions/<request_id>` and see exactly what happened.
-## Installation
-Add to your Gemfile:
+## Install
 ```ruby
 gem 'event_timeline'
 ```
-Then:
 ```bash
 bundle install
 rails generate event_timeline:install
 rails db:migrate
 ```
-## Basic Usage
+## Setup
-### 1. Configure what to track
+Tell it what to track:
 ```ruby
 # config/initializers/event_timeline.rb
 EventTimeline.configure do |config|
-  # Track specific paths
   config.watch 'app/services'
-  config.watch 'app/models/order.rb'
-  config.watch 'lib/payment_processor'
+  config.watch 'app/models'
 end
 ```
-### 2. View the timeline
-Visit `/event_timeline/sessions/:request_id` to see what happened during any request.
-Example: Your logs show request ID `abc-123-def` failed? Go to `/event_timeline/sessions/abc-123-def` and see every method that was called.
+## Usage
-## Real-world Example
-Let's say a payment fails in production. Here's what you'd see:
+Make a request, grab the request ID from logs, visit:
 ```
-OrdersController#create
-  Order#initialize
-    Order#validate_items
-    Order#calculate_total
-  Order#save
-  PaymentService#charge
-    PaymentGateway#create_charge
-      <- Returns: {error: "Insufficient funds"}
-    PaymentService#handle_failure
-      Order#mark_as_failed
-      CustomerMailer#payment_failed
+/event_timeline/sessions/abc-123-def
 ```
-Now you know exactly where things went wrong and what data was involved.
+You'll see the call timeline with params and return values. If the request crashed, you'll see the exception with its source location and backtrace.
-## Configuration Options
+## Configuration
 ```ruby
 EventTimeline.configure do |config|
-  # Filter sensitive data
-  config.add_filtered_attributes :credit_card, :ssn, :api_key
+  # What to track
+  config.watch 'app/services'
+  config.watch 'lib/payments'
-  # Custom PII filtering
-  config.filter_pii do |key, value|
-    return '<REDACTED>' if key.to_s =~ /bank_account/
-  end
+  # Filter sensitive params (these are filtered by default: password, token, secret, etc.)
+  config.add_filtered_attributes :credit_card, :ssn
-  # Customize how events are described
-  config.narrator do |event|
-    case event.name
-    when /Stripe/
-      "[PAYMENT] #{event.name}"
-    else
-      event.name
-    end
+  # Custom filtering
+  config.filter_pii do |key, value, context|
+    key.to_s.include?('account_number') ? true : nil
   end
-  # Data retention (defaults shown)
-  config.max_events_per_correlation = 500     # Per request
-  config.max_total_events = 10_000            # Total stored
-  config.max_event_age = 1.month              # Auto-delete after
+  # Retention
+  config.max_events_per_correlation = 500
+  config.max_total_events = 10_000
+  config.max_event_age = 1.month
+  # Truncation
+  config.max_string_length = 100
+  config.max_inspect_length = 200
 end
 ```
-## Performance
+## Runtime control
-EventTimeline uses TracePoint which has minimal overhead. Data is automatically rotated to prevent unbounded growth:
-- Old events are deleted after 1 month
-- Per-request events are capped at 500
-- Total events are capped at 10,000
-## Pro Tips
-1. **Production Debugging**: When users report issues, ask for their request ID from the logs. EventTimeline will show you exactly what happened.
+```ruby
+EventTimeline::CallTracker.uninstall!   # stop tracking
+EventTimeline::CallTracker.install!     # start tracking
+EventTimeline::CallTracker.installed?   # check status
+```
-2. **Development**: Watch your code execute in real-time. Great for understanding unfamiliar codebases.
+## Custom correlation IDs
-3. **Testing**: Verify your code follows the expected execution path.
+For background jobs or anything outside a request:
-4. **Correlation IDs**: EventTimeline automatically groups events by request ID, but you can set custom correlation IDs:
-   ```ruby
-   EventTimeline::CurrentCorrelation.id = "import-job-#{job.id}"
-   ```
+```ruby
+EventTimeline::CurrentCorrelation.id = "import-job-#{job.id}"
+```
 ## Limitations
-- Only tracks Ruby method calls (not database queries or external HTTP calls)
-- TracePoint doesn't work with some metaprogramming techniques
-- Large payloads are truncated to keep storage reasonable
+- Only tracks Ruby method calls (not SQL queries or HTTP calls)
+- TracePoint has some overhead - probably don't enable in high-traffic production without sampling
+- Large values get truncated
 ## License

data/Rakefile CHANGED Viewed

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 require 'bundler/setup'
 require 'bundler/gem_tasks'
+# Load all rake tasks
+Dir.glob('tasks/**/*.rake').each { |task| load task }

data/app/views/event_timeline/sessions/show.html.erb CHANGED Viewed

@@ -1,40 +1,82 @@
 <div class="container">
   <h1>Timeline for <span class="correlation-id"><%= @correlation_id %></span></h1>
+  <% has_exception = @events.any? { |e| e.category == 'exception' } %>
+  <% if @events.any? %>
+    <div class="status-badge <%= has_exception ? 'failed' : 'success' %>">
+      <%= has_exception ? 'FAILED' : 'SUCCESS' %>
+    </div>
+  <% end %>
   <div class="timeline">
     <% @events.each do |event| %>
       <% is_return = event.category == "method_return" %>
-      <div class="event <%= event.severity %> <%= 'return' if is_return %>">
-        <div class="event-header">
-          <span class="event-name">
-            <% if is_return %>
-              &lt;- <%= event.name.gsub('_return', '') %>
-            <% else %>
-              <%= narrate_event(event) %>
-            <% end %>
-          </span>
+      <% is_exception = event.category == "exception" %>
+      <% if is_exception %>
+        <div class="event exception">
+          <div class="exception-header">
+            <%= event.payload['exception_class'] %>
+          </div>
+          <div class="exception-message">
+            <%= event.payload['message'] %>
+          </div>
+          <% if event.payload['source_file'] %>
+            <div class="exception-location">
+              Raised in <strong><%= event.payload['source_method'] %></strong>
+              at <%= event.payload['source_file'] %>:<%= event.payload['source_line'] %>
+            </div>
+          <% end %>
           <span class="event-time"><%= event.occurred_at.strftime("%H:%M:%S.%L") %></span>
+          <% if event.payload['backtrace'].present? %>
+            <details>
+              <summary>Show backtrace</summary>
+              <div class="exception-backtrace">
+                <% event.payload['backtrace'].each do |line| %>
+                  <div class="exception-backtrace-line"><%= line %></div>
+                <% end %>
+              </div>
+            </details>
+          <% end %>
         </div>
-        <% if event.payload.present? %>
-          <% if is_return %>
-            <div style="font-size: 14px; color: #059862;">
-              Returns: <%= event.payload['return_value'] %>
-            </div>
-          <% elsif event.payload['params'].present? && !event.payload['params'].empty? %>
-            <div style="font-size: 14px; color: #0066cc;">
-              Params: <%= event.payload['params'].inspect %>
-            </div>
+      <% else %>
+        <div class="event <%= event.severity %> <%= 'return' if is_return %>">
+          <div class="event-header">
+            <span class="event-name">
+              <% if is_return %>
+                &lt;- <%= event.name.gsub('_return', '') %>
+              <% else %>
+                <%= narrate_event(event) %>
+              <% end %>
+            </span>
+            <span class="event-time"><%= event.occurred_at.strftime("%H:%M:%S.%L") %></span>
+          </div>
+          <% if event.payload.present? %>
+            <% if is_return %>
+              <div style="font-size: 14px; color: #059862;">
+                Returns: <%= event.payload['return_value'] %>
+              </div>
+            <% elsif event.payload['params'].present? && !event.payload['params'].empty? %>
+              <div style="font-size: 14px; color: #0066cc;">
+                Params: <%= event.payload['params'].inspect %>
+              </div>
+            <% end %>
+            <details>
+              <summary>Show full payload</summary>
+              <div class="event-payload">
+                <%= JSON.pretty_generate(event.payload) %>
+              </div>
+            </details>
           <% end %>
-          <details>
-            <summary>Show full payload</summary>
-            <div class="event-payload">
-              <%= JSON.pretty_generate(event.payload) %>
-            </div>
-          </details>
-        <% end %>
-      </div>
+        </div>
+      <% end %>
     <% end %>
     <% if @events.empty? %>

data/app/views/layouts/event_timeline/application.html.erb CHANGED Viewed

@@ -61,6 +61,65 @@
       background: #dc3545;
       border-color: #dc3545;
     }
+    .event.exception {
+      background: #fff5f5;
+      border: 2px solid #dc3545;
+    }
+    .event.exception::before {
+      background: #dc3545;
+      border-color: #dc3545;
+      width: 14px;
+      height: 14px;
+      left: -27px;
+      top: 18px;
+    }
+    .exception-header {
+      color: #dc3545;
+      font-weight: bold;
+      font-size: 16px;
+    }
+    .exception-message {
+      background: #f8d7da;
+      color: #721c24;
+      padding: 10px 15px;
+      border-radius: 4px;
+      margin: 10px 0;
+      font-family: monospace;
+    }
+    .exception-location {
+      font-size: 13px;
+      color: #666;
+      margin-bottom: 10px;
+    }
+    .exception-backtrace {
+      background: #282c34;
+      color: #abb2bf;
+      padding: 15px;
+      border-radius: 4px;
+      font-family: monospace;
+      font-size: 12px;
+      overflow-x: auto;
+      margin-top: 10px;
+    }
+    .exception-backtrace-line {
+      margin: 2px 0;
+    }
+    .status-badge {
+      display: inline-block;
+      padding: 4px 10px;
+      border-radius: 4px;
+      font-size: 12px;
+      font-weight: bold;
+      margin-bottom: 15px;
+    }
+    .status-badge.success {
+      background: #d4edda;
+      color: #155724;
+    }
+    .status-badge.failed {
+      background: #f8d7da;
+      color: #721c24;
+    }
     .event.warning::before {
       background: #ffc107;
       border-color: #ffc107;

data/lib/event_timeline/call_tracker.rb CHANGED Viewed

@@ -2,201 +2,211 @@
 module EventTimeline
   class CallTracker
+    THREAD_KEY_METHOD_STACK = :event_timeline_method_stack
+    THREAD_KEY_EVENT_BUFFER = :event_timeline_event_buffer
     class << self
+      attr_reader :call_trace, :return_trace
       def install!
-        @last_location = {}
-        @method_stack = Hash.new { |h, k| h[k] = [] }
-        call_trace = TracePoint.new(:call) do |tp|
-          next unless EventTimeline.configuration&.watched?(tp.path)
-          current_location = "#{tp.path}:#{tp.lineno}"
-          correlation_id = CurrentCorrelation.id || determine_correlation_id
-          if @last_location[correlation_id] != current_location
-            @last_location[correlation_id] = current_location
-            # Capture method arguments
-            params = capture_params(tp)
-            event_id = SecureRandom.uuid
-            @method_stack[correlation_id].push({
-                                                 event_id: event_id,
-                                                 method: "#{tp.defined_class}##{tp.method_id}"
-                                               })
-            Session.create!(
-              name: "#{tp.defined_class}##{tp.method_id}",
-              severity: 'info',
-              category: 'method_call',
-              payload: {
-                event_id: event_id,
-                file: tp.path,
-                line: tp.lineno,
-                class: tp.defined_class.to_s,
-                method: tp.method_id.to_s,
-                params: params
-              },
-              correlation_id: correlation_id,
-              occurred_at: Time.current
-            )
-            # Enforce rotation limits
-            RotationService.enforce_correlation_limit(correlation_id)
-            RotationService.cleanup_if_needed
-          end
-        rescue StandardError => e
-          Rails.logger.error "EventTimeline call tracking failed: #{e.message}" if defined?(Rails.logger)
-        end
+        return if installed?
-        return_trace = TracePoint.new(:return) do |tp|
-          next unless EventTimeline.configuration&.watched?(tp.path)
-          correlation_id = CurrentCorrelation.id || determine_correlation_id
-          method_info = @method_stack[correlation_id].find { |m| m[:method] == "#{tp.defined_class}##{tp.method_id}" }
-          if method_info
-            @method_stack[correlation_id].delete(method_info)
-            Session.create!(
-              name: "#{tp.defined_class}##{tp.method_id}_return",
-              severity: 'info',
-              category: 'method_return',
-              payload: {
-                event_id: method_info[:event_id],
-                return_value: filter_sensitive_data(:return_value, tp.return_value, { context: :return_value }),
-                class: tp.defined_class.to_s,
-                method: tp.method_id.to_s
-              },
-              correlation_id: correlation_id,
-              occurred_at: Time.current
-            )
-          end
-        rescue StandardError => e
-          Rails.logger.error "EventTimeline return tracking failed: #{e.message}" if defined?(Rails.logger)
-        end
+        @call_trace = TracePoint.new(:call) { |tp| handle_call(tp) }
+        @return_trace = TracePoint.new(:return) { |tp| handle_return(tp) }
-        call_trace.enable
-        return_trace.enable
+        @call_trace.enable
+        @return_trace.enable
       end
-      private
+      def uninstall!
+        @call_trace&.disable
+        @return_trace&.disable
+        @call_trace = nil
+        @return_trace = nil
+      end
-      def capture_params(tp)
-        method = tp.self.method(tp.method_id)
-        params = {}
+      def installed?
+        @call_trace&.enabled? || @return_trace&.enabled?
+      end
-        method.parameters.each_value do |name|
-          if tp.binding.local_variable_defined?(name)
-            value = tp.binding.local_variable_get(name)
-            params[name] = filter_sensitive_data(name, value, { context: :parameter })
-          end
-        end
+      def flush_events(correlation_id)
+        buffer = thread_event_buffer
+        return if buffer.empty?
-        params
+        buffer_size = buffer.size
+        Session.insert_all(buffer)
+        RotationService.enforce_correlation_limit(correlation_id, buffer_size)
+        RotationService.cleanup_if_needed
       rescue StandardError => e
-        { error: "Failed to capture params: #{e.message}" }
+        Rails.logger.error "EventTimeline flush failed: #{e.message}" if defined?(Rails.logger)
       end
-      def safe_inspect(value)
-        case value
-        when String
-          value.length > 100 ? "#{value[0..100]}..." : value
-        when Hash, Array
-          value.inspect.length > 200 ? "#{value.class}[#{value.size} items]" : value.inspect
-        when defined?(ActiveRecord::Base) && ActiveRecord::Base
-          inspect_activerecord(value)
-        when defined?(ActiveModel::Model) && ActiveModel::Model
-          inspect_model(value)
-        when Class
-          value.name
-        when Module
-          value.name
-        else
-          simple_inspect(value)
-        end
+      def cleanup_thread_state(correlation_id)
+        thread_method_stack.delete(correlation_id)
+        Thread.current[THREAD_KEY_EVENT_BUFFER] = []
+      end
+      def record_exception(exception, correlation_id)
+        backtrace = clean_backtrace(exception.backtrace || [])
+        source_location = extract_source_location(backtrace)
+        buffer_event(
+          name: "EXCEPTION: #{exception.class.name}",
+          severity: 'error',
+          category: 'exception',
+          payload: {
+            exception_class: exception.class.name,
+            message: exception.message,
+            backtrace: backtrace.first(10),
+            source_file: source_location[:file],
+            source_line: source_location[:line],
+            source_method: source_location[:method]
+          },
+          correlation_id: correlation_id,
+          occurred_at: Time.current
+        )
       rescue StandardError => e
-        "<inspect failed: #{e.message}>"
+        Rails.logger.error "EventTimeline exception recording failed: #{e.message}" if defined?(Rails.logger)
+      end
+      private
+      def clean_backtrace(backtrace)
+        # Filter out gem internals, keep app code
+        backtrace.reject { |line| line.include?('/gems/') || line.include?('/ruby/') }
       end
-      def inspect_activerecord(record)
-        if record.persisted?
-          id_attr = record.class.primary_key
-          id_value = record.send(id_attr) if id_attr
-          "#{record.class.name}(#{id_attr}: #{id_value})"
+      def extract_source_location(backtrace)
+        return { file: nil, line: nil, method: nil } if backtrace.empty?
+        # Parse first line: "/path/to/file.rb:123:in `method_name'"
+        if backtrace.first =~ /\A(.+):(\d+):in `(.+)'\z/
+          { file: ::Regexp.last_match(1), line: ::Regexp.last_match(2).to_i, method: ::Regexp.last_match(3) }
         else
-          "#{record.class.name}(new_record)"
+          { file: backtrace.first, line: nil, method: nil }
         end
+      end
+      def handle_call(tp)
+        return unless EventTimeline.configuration&.watched?(tp.path)
+        correlation_id = CurrentCorrelation.id || determine_correlation_id
+        event_id = SecureRandom.uuid
+        push_to_stack(correlation_id, event_id, tp)
+        buffer_call_event(correlation_id, event_id, tp)
       rescue StandardError => e
-        "#{record.class.name}(<inspection failed>)"
+        Rails.logger.error "EventTimeline call tracking failed: #{e.message}" if defined?(Rails.logger)
       end
-      def inspect_model(model)
-        "#{model.class.name}(#{model.class.attribute_names.size} attributes)"
+      def handle_return(tp)
+        # Skip watched? check - if we didn't track the call, pop_from_stack returns nil
+        correlation_id = CurrentCorrelation.id
+        return unless correlation_id
+        method_info = pop_from_stack(correlation_id, tp)
+        return unless method_info
+        buffer_return_event(correlation_id, method_info, tp)
       rescue StandardError => e
-        "#{model.class.name}(<inspection failed>)"
+        Rails.logger.error "EventTimeline return tracking failed: #{e.message}" if defined?(Rails.logger)
       end
-      def simple_inspect(value)
-        result = value.inspect
-        if result.length > 200
-          "#{value.class.name}[#{result.length} chars]"
-        else
-          result
-        end
+      def push_to_stack(correlation_id, event_id, tp)
+        stack = thread_method_stack[correlation_id] ||= []
+        stack.push(
+          event_id: event_id,
+          method: method_signature(tp)
+        )
       end
-      def filter_sensitive_data(key, value, context = {})
-        if EventTimeline.configuration&.should_filter?(key, value, context)
-          case value
-          when String
-            '<FILTERED>'
-          when Hash
-            filter_hash(value)
-          when Array
-            value.map.with_index { |item, index| filter_sensitive_data("item_#{index}", item, context) }
-          when defined?(ActiveRecord::Base) && ActiveRecord::Base
-            filter_activerecord(value)
-          else
-            '<FILTERED>'
-          end
-        else
-          safe_inspect(value)
-        end
+      def pop_from_stack(correlation_id, tp)
+        stack = thread_method_stack[correlation_id]
+        return unless stack
+        signature = method_signature(tp)
+        # Find the LAST matching entry (proper LIFO for recursion)
+        index = stack.rindex { |m| m[:method] == signature }
+        return unless index
+        stack.delete_at(index)
       end
-      def filter_hash(hash)
-        filtered = {}
-        hash.each do |key, value|
-          filtered[key] = filter_sensitive_data(key, value, { context: :hash_value })
-        end
-        filtered
+      def method_signature(tp)
+        "#{tp.defined_class}##{tp.method_id}"
       end
-      def filter_activerecord(record)
-        if EventTimeline.configuration&.should_filter?(:activerecord, record, { context: :model })
-          '<FILTERED>'
-        else
-          # Show model with filtered attributes
-          filtered_attrs = {}
-          record.attributes.each do |key, value|
-            filtered_attrs[key] = if EventTimeline.configuration&.should_filter?(key, value, { context: :attribute })
-                                    '<FILTERED>'
-                                  else
-                                    safe_inspect(value)
-                                  end
+      def buffer_call_event(correlation_id, event_id, tp)
+        buffer_event(
+          name: method_signature(tp),
+          severity: 'info',
+          category: 'method_call',
+          payload: {
+            event_id: event_id,
+            file: tp.path,
+            line: tp.lineno,
+            class: tp.defined_class.to_s,
+            method: tp.method_id.to_s,
+            params: capture_params(tp)
+          },
+          correlation_id: correlation_id,
+          occurred_at: Time.current
+        )
+      end
+      def buffer_return_event(correlation_id, method_info, tp)
+        buffer_event(
+          name: "#{method_signature(tp)}_return",
+          severity: 'info',
+          category: 'method_return',
+          payload: {
+            event_id: method_info[:event_id],
+            return_value: ValueFilter.filter(:return_value, tp.return_value, { context: :return_value }),
+            class: tp.defined_class.to_s,
+            method: tp.method_id.to_s
+          },
+          correlation_id: correlation_id,
+          occurred_at: Time.current
+        )
+      end
+      def thread_method_stack
+        Thread.current[THREAD_KEY_METHOD_STACK] ||= {}
+      end
+      def thread_event_buffer
+        Thread.current[THREAD_KEY_EVENT_BUFFER] ||= []
+      end
+      def buffer_event(event)
+        thread_event_buffer << event
+      end
+      def capture_params(tp)
+        method = tp.self.method(tp.method_id)
+        params = {}
+        method.parameters.each do |_type, name|
+          next unless name
+          if tp.binding.local_variable_defined?(name)
+            value = tp.binding.local_variable_get(name)
+            params[name] = ValueFilter.filter(name, value, { context: :parameter })
           end
-          "#{inspect_activerecord(record)} {#{filtered_attrs.map { |k, v| "#{k}: #{v}" }.join(', ')}}"
         end
+        params
       rescue StandardError => e
-        "#{inspect_activerecord(record)} <filtering failed>"
+        { error: "Failed to capture params: #{e.message}" }
       end
       def determine_correlation_id
         if Thread.current[:request_id]
           Thread.current[:request_id]
-        elsif defined?(ActiveJob::Base) && ActiveJob::Base.current_execution&.job_id
-          ActiveJob::Base.current_execution.job_id
+        elsif Thread.current[:active_job_id]
+          Thread.current[:active_job_id]
         else
           SecureRandom.uuid.tap { |id| CurrentCorrelation.id = id }
         end

data/lib/event_timeline/configuration.rb CHANGED Viewed

@@ -3,15 +3,19 @@
 module EventTimeline
   class Configuration
     attr_accessor :narrator_proc, :watched_paths, :pii_filter_proc, :filtered_attributes,
-                  :max_events_per_correlation, :max_total_events, :cleanup_threshold, :max_event_age
+                  :max_events_per_correlation, :max_total_events, :cleanup_threshold, :max_event_age,
+                  :max_string_length, :max_inspect_length
     def initialize
       @watched_paths = []
+      @watched_cache = {}                 # Cache for watched? lookups
       @filtered_attributes = default_filtered_attributes
-      @max_events_per_correlation = 500 # Max events per correlation_id
-      @max_total_events = 10_000 # Max total events before cleanup
-      @cleanup_threshold = 0.8           # Start cleanup at 80% of max
-      @max_event_age = 1.month           # Delete events older than this
+      @max_events_per_correlation = 500   # Max events per correlation_id
+      @max_total_events = 10_000          # Max total events before cleanup
+      @cleanup_threshold = 0.8            # Start cleanup at 80% of max
+      @max_event_age = 1.month            # Delete events older than this
+      @max_string_length = 100            # Truncate strings longer than this
+      @max_inspect_length = 200           # Truncate inspected values longer than this
     end
     def narrator(&block)
@@ -20,16 +24,23 @@ module EventTimeline
     def watch(path)
       @watched_paths << normalize_path(path)
+      @watched_cache.clear # Invalidate cache when paths change
     end
     def watched?(file_path)
       return false if @watched_paths.empty?
-      @watched_paths.any? do |pattern|
-        File.fnmatch?(pattern, file_path, File::FNM_PATHNAME)
+      @watched_cache.fetch(file_path) do
+        @watched_cache[file_path] = @watched_paths.any? do |pattern|
+          File.fnmatch?(pattern, file_path, File::FNM_PATHNAME)
+        end
       end
     end
+    def clear_watched_cache!
+      @watched_cache.clear
+    end
     def filter_pii(&block)
       @pii_filter_proc = block if block_given?
     end
@@ -81,7 +92,11 @@ module EventTimeline
     def normalize_path(path)
       path = path.to_s
       path = "#{Rails.root}/#{path}" unless path.start_with?('/')
-      "#{path.gsub(%r{/$}, '')}/**/*.rb" unless path.include?('*')
+      if path.include?('*')
+        path
+      else
+        "#{path.gsub(%r{/$}, '')}/**/*.rb"
+      end
     end
   end
 end

data/lib/event_timeline/engine.rb CHANGED Viewed

@@ -4,14 +4,12 @@ module EventTimeline
   class Engine < ::Rails::Engine
     isolate_namespace EventTimeline
-    initializer 'timeline.install_call_tracker' do
-      ActiveSupport.on_load(:after_initialize) do
-        EventTimeline::CallTracker.install!
-      end
+    initializer 'event_timeline.setup_middleware' do |app|
+      app.middleware.use EventTimeline::Middleware
     end
-    initializer 'timeline.setup_middleware' do |app|
-      app.middleware.use EventTimeline::Middleware
+    config.after_initialize do
+      EventTimeline::CallTracker.install! if EventTimeline.configuration
     end
   end
 end

data/lib/event_timeline/middleware.rb CHANGED Viewed

@@ -8,11 +8,21 @@ module EventTimeline
     def call(env)
       request = ActionDispatch::Request.new(env)
-      CurrentCorrelation.id = request.request_id
-      Thread.current[:request_id] = request.request_id
+      correlation_id = request.request_id
+      CurrentCorrelation.id = correlation_id
+      Thread.current[:request_id] = correlation_id
       @app.call(env)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      # Capture the exception before re-raising
+      CallTracker.record_exception(e, correlation_id) if correlation_id
+      raise
     ensure
+      # Flush buffered events to database
+      CallTracker.flush_events(correlation_id) if correlation_id
+      # Clean up thread-local state
+      CallTracker.cleanup_thread_state(correlation_id) if correlation_id
       CurrentCorrelation.reset
       Thread.current[:request_id] = nil
     end

data/lib/event_timeline/rotation_service.rb CHANGED Viewed

@@ -2,10 +2,19 @@
 module EventTimeline
   class RotationService
+    CLEANUP_CHECK_INTERVAL = 100 # Only check every N flushes
     class << self
-      def cleanup_if_needed
+      def cleanup_if_needed(force: false)
         return unless EventTimeline.configuration
+        unless force
+          # Probabilistic check - only run expensive Session.count every N requests
+          @flush_counter ||= 0
+          @flush_counter += 1
+          return unless (@flush_counter % CLEANUP_CHECK_INTERVAL).zero?
+        end
         total_count = Session.count
         max_total = EventTimeline.configuration.max_total_events
         threshold = (max_total * EventTimeline.configuration.cleanup_threshold).to_i
@@ -15,11 +24,23 @@ module EventTimeline
         perform_cleanup(total_count, max_total)
       end
-      def enforce_correlation_limit(correlation_id)
+      def enforce_correlation_limit(correlation_id, buffer_size = 0, force: false)
         return unless EventTimeline.configuration
         max_per_correlation = EventTimeline.configuration.max_events_per_correlation
+        unless force
+          # Track in-memory counts to avoid DB query on every flush
+          @correlation_counts ||= {}
+          @correlation_counts[correlation_id] ||= 0
+          @correlation_counts[correlation_id] += buffer_size
+          # Only hit DB when we think we might be near the limit
+          return unless @correlation_counts[correlation_id] >= (max_per_correlation * 0.9)
+        end
         current_count = Session.where(correlation_id: correlation_id).count
+        @correlation_counts[correlation_id] = current_count if @correlation_counts # Sync with reality
         return unless current_count >= max_per_correlation
@@ -30,10 +51,16 @@ module EventTimeline
                                .limit(current_count - keep_count)
         Session.where(id: oldest_events.pluck(:id)).delete_all
+        @correlation_counts[correlation_id] = keep_count if @correlation_counts
         Rails.logger.info "EventTimeline: Rotated #{current_count - keep_count} events for correlation #{correlation_id}" if defined?(Rails.logger)
       end
+      def reset_counters!
+        @flush_counter = 0
+        @correlation_counts = {}
+      end
       private
       def perform_cleanup(current_count, max_count)

data/lib/event_timeline/value_filter.rb ADDED Viewed

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module EventTimeline
+  class ValueFilter
+    FILTERED = '<FILTERED>'
+    class << self
+      def filter(key, value, context = {})
+        if should_filter?(key, value, context)
+          filter_sensitive_value(value, context)
+        else
+          filter_nested(key, value, context)
+        end
+      end
+      private
+      def should_filter?(key, value, context)
+        EventTimeline.configuration&.should_filter?(key, value, context)
+      end
+      def filter_sensitive_value(value, context)
+        case value
+        when String
+          FILTERED
+        when Hash
+          filter_hash(value, context)
+        when Array
+          filter_array(value, context)
+        else
+          return filter_activerecord(value) if ValueInspector.activerecord_model?(value)
+          FILTERED
+        end
+      end
+      def filter_nested(key, value, context)
+        case value
+        when Hash
+          filter_hash(value, context)
+        when Array
+          filter_array(value, context)
+        else
+          return filter_activerecord(value) if ValueInspector.activerecord_model?(value)
+          ValueInspector.inspect(value)
+        end
+      end
+      def filter_hash(hash, context = {})
+        hash.each_with_object({}) do |(key, value), filtered|
+          filtered[key] = filter(key, value, context.merge(context: :hash_value))
+        end
+      end
+      def filter_array(array, context = {})
+        array.map.with_index do |item, index|
+          filter("item_#{index}", item, context)
+        end
+      end
+      def filter_activerecord(record)
+        if should_filter?(:activerecord, record, { context: :model })
+          FILTERED
+        else
+          filter_activerecord_attributes(record)
+        end
+      rescue StandardError
+        "#{ValueInspector.inspect_activerecord(record)} <filtering failed>"
+      end
+      def filter_activerecord_attributes(record)
+        filtered_attrs = record.attributes.each_with_object({}) do |(key, value), attrs|
+          attrs[key] = if should_filter?(key, value, { context: :attribute })
+                         FILTERED
+                       else
+                         ValueInspector.inspect(value)
+                       end
+        end
+        "#{ValueInspector.inspect_activerecord(record)} {#{filtered_attrs.map { |k, v| "#{k}: #{v}" }.join(', ')}}"
+      end
+    end
+  end
+end

data/lib/event_timeline/value_inspector.rb ADDED Viewed

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+module EventTimeline
+  class ValueInspector
+    class << self
+      def inspect(value)
+        return inspect_string(value) if value.is_a?(String)
+        return inspect_collection(value) if value.is_a?(Hash) || value.is_a?(Array)
+        return inspect_activerecord(value) if activerecord_model?(value)
+        return inspect_activemodel(value) if activemodel_model?(value)
+        return value.name if value.is_a?(Class) || value.is_a?(Module)
+        inspect_generic(value)
+      rescue StandardError
+        '<inspect failed>'
+      end
+      def inspect_activerecord(record)
+        if record.persisted?
+          id_attr = record.class.primary_key
+          id_value = record.send(id_attr) if id_attr
+          "#{record.class.name}(#{id_attr}: #{id_value})"
+        else
+          "#{record.class.name}(new_record)"
+        end
+      rescue StandardError
+        "#{record.class.name}(<inspection failed>)"
+      end
+      def activerecord_model?(value)
+        defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
+      end
+      def activemodel_model?(value)
+        return false unless defined?(ActiveModel::Model)
+        value.class.included_modules.include?(ActiveModel::Model)
+      end
+      private
+      def inspect_string(value)
+        max_length = EventTimeline.configuration&.max_string_length || 100
+        value.length > max_length ? "#{value[0...max_length]}..." : value
+      end
+      def inspect_collection(value)
+        max_length = EventTimeline.configuration&.max_inspect_length || 200
+        inspected = value.inspect
+        inspected.length > max_length ? "#{value.class}[#{value.size} items]" : inspected
+      end
+      def inspect_activemodel(model)
+        "#{model.class.name}(#{model.class.attribute_names.size} attributes)"
+      rescue StandardError
+        "#{model.class.name}(<inspection failed>)"
+      end
+      def inspect_generic(value)
+        max_length = EventTimeline.configuration&.max_inspect_length || 200
+        result = value.inspect
+        result.length > max_length ? "#{value.class.name}[#{result.length} chars]" : result
+      end
+    end
+  end
+end

data/lib/event_timeline/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module EventTimeline
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/event_timeline.rb CHANGED Viewed

@@ -4,6 +4,8 @@ require 'event_timeline/version'
 require 'event_timeline/engine'
 require 'event_timeline/configuration'
 require 'event_timeline/current_correlation'
+require 'event_timeline/value_inspector'
+require 'event_timeline/value_filter'
 require 'event_timeline/call_tracker'
 require 'event_timeline/middleware'
 require 'event_timeline/rotation_service'

data/lib/generators/event_timeline/install/install_generator.rb ADDED Viewed

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+require 'rails/generators'
+require 'rails/generators/migration'
+module EventTimeline
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('templates', __dir__)
+      desc 'Creates an EventTimeline initializer and copies migrations'
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/event_timeline.rb'
+      end
+      def copy_migrations
+        migration_template 'create_event_timeline_sessions.rb',
+                           'db/migrate/create_event_timeline_sessions.rb',
+                           skip: true
+      end
+      def show_post_install_message
+        say ''
+        say 'EventTimeline installed successfully!', :green
+        say ''
+        say 'Next steps:'
+        say '  1. Run migrations: rails db:migrate'
+        say '  2. Configure watched paths in config/initializers/event_timeline.rb'
+        say '  3. Visit /event_timeline/sessions/:request_id to view timelines'
+        say ''
+      end
+    end
+  end
+end

data/{db/migrate/20260103180115_create_event_timeline_sessions.rb → lib/generators/event_timeline/install/templates/create_event_timeline_sessions.rb} RENAMED Viewed

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
-class CreateEventTimelineSessions < ActiveRecord::Migration[8.1]
+class CreateEventTimelineSessions < ActiveRecord::Migration[7.0]
   def change
     create_table :event_timeline_sessions do |t|
       t.string :name, null: false
       t.string :severity, default: 'info'
       t.string :category
-      t.jsonb :payload
+      t.json :payload
       t.string :correlation_id, null: false
       t.datetime :occurred_at, null: false

data/lib/generators/event_timeline/install/templates/initializer.rb ADDED Viewed

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+EventTimeline.configure do |config|
+  # Configure which paths to track method calls for.
+  # Supports glob patterns and specific file paths.
+  #
+  # Examples:
+  #   config.watch 'app/services'
+  #   config.watch 'app/models/order.rb'
+  #   config.watch 'lib/payment_processor'
+  #
+  # config.watch 'app/services'
+  # Add additional attributes to filter (beyond the defaults).
+  # Default filtered: password, token, secret, key, credential, auth,
+  #                   session, cookie, ssn, social_security, credit_card,
+  #                   card_number, cvv, pin, private, confidential
+  #
+  # config.add_filtered_attributes :bank_account, :routing_number
+  # Custom PII filtering logic (optional).
+  # Return true to filter, false to keep, nil to use default logic.
+  #
+  # config.filter_pii do |key, value, context|
+  #   return true if key.to_s =~ /account_number/
+  #   nil # Fall back to default filtering
+  # end
+  # Customize how events are displayed in the timeline (optional).
+  #
+  # config.narrator do |event|
+  #   case event.name
+  #   when /Payment/
+  #     "[PAYMENT] #{event.name}"
+  #   else
+  #     event.name.humanize
+  #   end
+  # end
+  # Data retention settings (defaults shown).
+  #
+  # config.max_events_per_correlation = 500  # Max events per request
+  # config.max_total_events = 10_000         # Max total events stored
+  # config.max_event_age = 1.month           # Auto-delete events older than this
+end

metadata CHANGED Viewed

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_timeline
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - svn-arv
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -23,11 +24,39 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: EventTimeline tracks method calls in your Rails app so you can replay
   and debug what happened during any request. Perfect for understanding production
   issues and unfamiliar codebases.
 email:
-- svn-arv@users.noreply.github.com
+- eventtimelinerails@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -43,7 +72,6 @@ files:
 - app/views/event_timeline/sessions/show.html.erb
 - app/views/layouts/event_timeline/application.html.erb
 - config/routes.rb
-- db/migrate/20260103180115_create_event_timeline_sessions.rb
 - lib/event_timeline.rb
 - lib/event_timeline/call_tracker.rb
 - lib/event_timeline/configuration.rb
@@ -51,10 +79,17 @@ files:
 - lib/event_timeline/engine.rb
 - lib/event_timeline/middleware.rb
 - lib/event_timeline/rotation_service.rb
+- lib/event_timeline/value_filter.rb
+- lib/event_timeline/value_inspector.rb
 - lib/event_timeline/version.rb
+- lib/generators/event_timeline/install/install_generator.rb
+- lib/generators/event_timeline/install/templates/create_event_timeline_sessions.rb
+- lib/generators/event_timeline/install/templates/initializer.rb
+homepage: https://github.com/svn-arv/event_timeline
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -62,14 +97,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: Debug Rails apps by replaying method calls from any request
 test_files: []