rails_trace_viewer 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee7089d7fb74980ab3da97dff49ad0db37fca991d11c26deea295884f53d507e
-  data.tar.gz: c28776d4e3cd56a26cdd9cd9a30fe9b36079149e1614582c8a00f779109f0dfe
+  metadata.gz: 5ff338c196864dc973331301d6fbdbbc50de7ab3940ae012458f73bdfe5b0183
+  data.tar.gz: b9b535f0575a9972380c9fca35faa82305298b23c64b524182c2ed01df92bc51
 SHA512:
-  metadata.gz: 119bdb43c3f579398839a527253273a740aa7039f05b7b9918aefd3abda410fb51d44154d04349d4fa3a33860e84a66381506cb08cb1efdfe1e72388204db843
-  data.tar.gz: 3cf763350d1b8df9bb775609fb5be65d84c8014f2c161b23b765dc32faa4876636f37fe20b9bf94361789236763d7c3c41253d7d34cbfda11dea9f866a4d82a1
+  metadata.gz: 824699687247af12dc1abf2fd5be2c5bc45e12896606042c531fec5a6d6918a9b4ae06b7c8990b32ce3cbdb1cf77d5e7a6769e34261c633eef3eec8fb413ce22
+  data.tar.gz: b140ba6bc597e257e286ed3c1d092660041ca5003b5b278dee51d962436ab54a566e01b4d5d331c4c7a5d444024e66691833800b3589a0d6e861297fcdabc4c6

data/README.md

@@ -2,6 +2,8 @@
 
 An educational and debugging tool for Ruby on Rails to visualize the request lifecycle in real-time.
 
+[![Watch the Demo](https://img.youtube.com/vi/Zwg3rROyaH0/maxresdefault.jpg)](https://youtu.be/Zwg3rROyaH0)
+
 Rails Trace Viewer provides a beautiful, interactive Call Stack Tree that visualizes how your Rails application processes requests. It traces the flow from the Controller through Models, Views, SQL Queries, and even across process boundaries into Sidekiq Background Jobs.
 
 ---
@@ -95,6 +97,7 @@ Rails.application.routes.draw do
 end
 ```
 
+**🛑 Need to disable the gem?** Simply comment out the `mount RailsTraceViewer::Engine => '/rails_trace_viewer'` line above. The gem detects this and **shuts down completely** (Zero Overhead).
 ---
 
 ### 3. Configure Action Cable (Redis)
@@ -197,6 +200,11 @@ The viewer uses specific colors to represent different parts of the call stack:
 
 ## 🛠️ Troubleshooting
 
+### **"My app hangs or loads very slowly when the viewer is open."**
+* **Check your Web Server:** Ensure you are using a multi-threaded server like **Puma**.
+* **Why?** This gem uses ActionCable (WebSockets). Single-threaded servers (like **WEBrick**) cannot handle the persistent WebSocket connection and regular HTTP requests at the same time, causing the app to block.
+* **Fix:** Add `gem 'puma'` to your Gemfile and remove `gem 'webrick'`.
+
 ### **"I see the Enqueue node, but the trace stops there."**
 - Ensure **Sidekiq is running**.
 - Ensure `config/cable.yml` uses **Redis**, not the async adapter.

data/app/channels/rails_trace_viewer/trace_channel.rb

@@ -1,5 +1,5 @@
 module RailsTraceViewer
-  class TraceChannel < ApplicationCable::Channel
+  class TraceChannel < ActionCable::Channel::Base
     def subscribed
       stream_from "rails_trace_viewer"
     end

data/app/controllers/rails_trace_viewer/traces_controller.rb

@@ -1,5 +1,7 @@
 module RailsTraceViewer
   class TracesController < ActionController::Base
+    layout false
+    
     def show
     end
   end

data/app/views/rails_trace_viewer/traces/show.html.erb

@@ -19,9 +19,27 @@
       overflow: hidden; 
       cursor: grab; 
       background: #f8fafc;
+      position: relative;
     }
     .trace-container:active { cursor: grabbing; }
 
+    /* Empty State Styling */
+    .empty-state {
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      text-align: center;
+      transition: opacity 0.5s ease-out, visibility 0.5s;
+      opacity: 1;
+      visibility: visible;
+      pointer-events: none;
+    }
+    .empty-state.hidden {
+      opacity: 0;
+      visibility: hidden;
+    }
+
     /* Nodes */
     .node rect { rx: 6; ry: 6; stroke-width: 1px; transition: all 0.2s; filter: drop-shadow(0 2px 4px rgb(0 0 0 / 0.05)); }
     .node:hover rect { stroke-width: 2px; stroke: #6366f1; cursor: pointer; transform: translateY(-1px); }
@@ -95,7 +113,7 @@
     <button id="clear-btn" class="px-3 py-2 text-sm font-medium text-red-600 bg-white border border-slate-300 rounded-md hover:bg-red-50 flex items-center gap-2 transition-all active:scale-95">
       <span>🗑</span> Clear
     </button>
-    <button id="learn-btn" class="px-3 py-2 text-sm font-medium text-indigo-600 bg-indigo-50 border border-indigo-200 rounded-md hover:bg-indigo-100 flex items-center gap-2 transition-all active:scale-95">
+    <button id="learn-btn" class="px-3 py-2 text-sm font-medium text-indigo-600 bg-white border border-indigo-200 rounded-md hover:bg-indigo-100 flex items-center gap-2 transition-all active:scale-95">
       <span>📖</span> Learn
     </button>
   </div>
@@ -103,6 +121,13 @@
 
 <div class="flex h-full">
   <div id="trace-visualization" class="trace-container"></div>
+    <div id="empty-state" class="empty-state">
+      <div class="mb-4 inline-block p-4 bg-white rounded-full shadow-sm">
+        <svg class="w-8 h-8 text-slate-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
+      </div>
+      <h3 class="text-lg font-medium text-slate-700">Waiting for Activity...</h3>
+      <p class="text-sm text-slate-400 mt-2">Trigger a web request, a job, a background worker, or a method to see the trace.</p>
+    </div>
   <div id="detail-drawer" class="drawer">
     <div class="p-5 border-b border-slate-100 flex justify-between items-center bg-slate-50">
       <h2 class="font-bold text-slate-800 text-lg" id="drawer-title">Details</h2>
@@ -116,6 +141,7 @@
 document.addEventListener("DOMContentLoaded", () => {
   const container = document.getElementById("trace-visualization");
   const drawer = document.getElementById("detail-drawer");
+  const emptyState = document.getElementById("empty-state");
   let graphs = {}; 
   let nodeBuffer = {};
   let verticalOffset = 60;
@@ -150,6 +176,9 @@ document.addEventListener("DOMContentLoaded", () => {
       received(data) {
         if (!data || !data.node) return;
         if ((data.node.name || "").includes("RailsTraceViewer")) return;
+        
+        emptyState.classList.add("hidden");
+
         addNodeToGraph(data.trace_id, data.node);
         
         if (this.redrawTimer) clearTimeout(this.redrawTimer);
@@ -215,7 +244,17 @@ document.addEventListener("DOMContentLoaded", () => {
 
   function renderSingleDAG(G, yOffset) {
     const dag = new dagre.graphlib.Graph();
-    dag.setGraph({ rankdir: "LR", nodesep: 25, ranksep: 60 });
+
+    const parentCounts = {};
+    G.edges.forEach(e => {
+      parentCounts[e.source] = (parentCounts[e.source] || 0) + 1;
+    });
+    
+    const maxChildren = Math.max(...Object.values(parentCounts), 0);
+
+    const dynamicRankSep = Math.min(800, Math.max(60, 40 + (maxChildren * 18)));
+
+    dag.setGraph({ rankdir: "LR", nodesep: 25, ranksep: dynamicRankSep });
     dag.setDefaultEdgeLabel(() => ({}));
 
     Object.values(G.nodes).forEach(n => {
@@ -229,16 +268,13 @@ document.addEventListener("DOMContentLoaded", () => {
 
     if (dag.graph().height) G.height = dag.graph().height;
     
-    let minX = Infinity, maxX = -Infinity;
-    let minY = Infinity, maxY = -Infinity;
-
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
     Object.values(G.nodes).forEach(n => {
       const nodeInfo = dag.node(n.id);
       const nx1 = nodeInfo.x - (nodeInfo.width / 2);
       const nx2 = nodeInfo.x + (nodeInfo.width / 2);
       const ny1 = nodeInfo.y - (nodeInfo.height / 2);
       const ny2 = nodeInfo.y + (nodeInfo.height / 2);
-
       if (nx1 < minX) minX = nx1;
       if (nx2 > maxX) maxX = nx2;
       if (ny1 < minY) minY = ny1;
@@ -248,36 +284,28 @@ document.addEventListener("DOMContentLoaded", () => {
     if (minX === Infinity) { minX = 0; maxX = 0; minY = 0; maxY = 0; }
 
     G.bounds = {
-      minX: minX,
-      maxX: maxX,
-      minY: minY + yOffset,
-      maxY: maxY + yOffset,
-      width: maxX - minX,
-      height: maxY - minY,
-      centerX: minX + (maxX - minX) / 2,
-      centerY: (minY + yOffset) + (maxY - minY) / 2
+      minX: minX, maxX: maxX, minY: minY + yOffset, maxY: maxY + yOffset,
+      width: maxX - minX, height: maxY - minY,
+      centerX: minX + (maxX - minX) / 2, centerY: (minY + yOffset) + (maxY - minY) / 2
     };
 
     g.selectAll(`.link-${G.id}`).data(dag.edges()).enter().append("path")
-      .attr("class", "link").attr("d", e => {
+      .attr("class", "link")
+      .attr("d", e => {
         const pts = dag.edge(e).points;
-        return d3.line().x(d => d.x).y(d => d.y + yOffset).curve(d3.curveBasis)(pts);
+        return d3.line().x(d => d.x).y(d => d.y + yOffset).curve(d3.curveMonotoneX)(pts);
       });
 
     const nodeGroup = g.selectAll(`.node-${G.id}`).data(dag.nodes()).enter().append("g")
       .attr("class", d => `node node-type-${dag.node(d).type}`)
+      .attr("id", d => `node-${d}`) 
       .attr("transform", d => `translate(${dag.node(d).x}, ${dag.node(d).y + yOffset})`)
       .on("click", (e, d) => { e.stopPropagation(); showDrawer(dag.node(d).fullData); });
 
-    nodeGroup.append("rect")
-      .attr("width", NODE_WIDTH).attr("height", NODE_HEIGHT).attr("x", -NODE_WIDTH / 2).attr("y", -NODE_HEIGHT / 2);
-
-    nodeGroup.append("text")
-      .attr("x", 0).attr("y", 0).attr("dy", "0.35em")
+    nodeGroup.append("rect").attr("width", NODE_WIDTH).attr("height", NODE_HEIGHT).attr("x", -NODE_WIDTH / 2).attr("y", -NODE_HEIGHT / 2);
+    nodeGroup.append("text").attr("x", 0).attr("y", 0).attr("dy", "0.35em")
       .text(d => dag.node(d).label).classed("label-title", true).style("text-anchor", "middle"); 
-
-    nodeGroup.append("text")
-      .attr("x", (NODE_WIDTH / 2) - 10).attr("y", (NODE_HEIGHT / 2) - 6)
+    nodeGroup.append("text").attr("x", (NODE_WIDTH / 2) - 10).attr("y", (NODE_HEIGHT / 2) - 6)
       .text(d => dag.node(d).type.replace(/_/g, " ")).classed("label-type", true).style("text-anchor", "end");
   }
 
@@ -347,9 +375,12 @@ rails s</div>
           <div class="flex items-center gap-2"><span class="w-3 h-3 bg-purple-100 border border-purple-300 rounded"></span> Job Enqueue</div>
           <div class="flex items-center gap-2"><span class="w-3 h-3 bg-pink-100 border border-pink-300 rounded"></span> Job Perform</div>
           <div class="flex items-center gap-2"><span class="w-3 h-3 bg-amber-100 border border-amber-300 rounded"></span> SQL Query</div>
+          <div class="flex items-center gap-2"><span class="w-3 h-3 bg-emerald-100 border border-emerald-300 rounded"></span> View Render</div>
         </div>
       </div>
 
+      <div class="help-section"><div class="help-title"><span>📚</span> Resources</div><div class="help-text"><p class="mb-2">To learn more, read the <a href="https://github.com/Aditya-JOSH/rails_trace_viewer/blob/main/README.md" target="_blank" class="text-indigo-600 hover:underline font-medium">Project Documentation</a>.</p><p>Found an issue? Report it on <a href="https://github.com/Aditya-JOSH/rails_trace_viewer/issues" target="_blank" class="text-indigo-600 hover:underline font-medium">GitHub Issues</a>.</p></div></div>
+
       <div class="mt-12 pt-6 border-t border-slate-200">
         <div class="text-xs font-bold text-slate-400 uppercase tracking-wider mb-3">Created By</div>
         <a href="https://www.linkedin.com/in/aditya-kolekar-5a54611b5/" target="_blank" class="flex items-center gap-4 p-4 bg-white border border-slate-200 rounded-xl shadow-sm hover:shadow-md hover:border-blue-200 transition-all group text-decoration-none">
@@ -373,6 +404,7 @@ rails s</div>
     redrawAllGraphs();
     drawer.classList.remove("open");
     console.log("🧹 Clearing traces & reconnecting...");
+    emptyState.classList.remove("hidden");
     setupSubscription(); 
   };
 
@@ -393,7 +425,8 @@ rails s</div>
     const tX = (viewW / 2) - (G.bounds.centerX * scale);
     const tY = (viewH / 2) - (G.bounds.centerY * scale);
 
-    svg.transition().duration(800).call(zoom.transform, d3.zoomIdentity.translate(tX, tY).scale(scale));
+    svg.transition().duration(2500).ease(d3.easeCubicOut)
+       .call(zoom.transform, d3.zoomIdentity.translate(tX, tY).scale(scale));
   };
 
   document.getElementById("learn-btn").onclick = showLearn;
@@ -407,4 +440,4 @@ rails s</div>
 });
 </script>
 </body>
-</html>
+</html>

data/lib/rails_trace_viewer/engine.rb

@@ -2,31 +2,48 @@ module RailsTraceViewer
   class Engine < ::Rails::Engine
     isolate_namespace RailsTraceViewer
 
-    initializer "rails_trace_viewer.subscribe", after: :load_config_initializers do
-      ActiveSupport.on_load(:action_controller) do
-        RailsTraceViewer::Subscribers::ControllerSubscriber.attach
+    config.to_prepare do
+      if Rails.application.routes.routes.empty?
+        Rails.application.reload_routes!
       end
 
-      ActiveSupport.on_load(:active_record) do
-        RailsTraceViewer::Subscribers::SqlSubscriber.attach
-      end
+      is_mounted = Rails.application.routes.routes.any? do |route|
+        app = route.app
+        while app.respond_to?(:app) && app != app.app
+          app = app.app
+        end
+        match_class = (app == RailsTraceViewer::Engine) || (app.to_s.include?("RailsTraceViewer::Engine"))
 
-      ActiveSupport.on_load(:action_view) do
-        RailsTraceViewer::Subscribers::ViewSubscriber.attach
-      end
+        path_match = (route.path.spec.to_s rescue "").include?("/rails_trace_viewer")
 
-      ActiveSupport.on_load(:active_job) do
-        RailsTraceViewer::Subscribers::ActiveJobSubscriber.attach
+        match_class || path_match
       end
 
-      Rails.application.reloader.to_prepare do
-        RailsTraceViewer::Subscribers::SidekiqSubscriber.attach
+      if is_mounted
+        RailsTraceViewer.enabled = true
+        
+        unless @booted_message_shown
+          puts "✅ [RailsTraceViewer] Engine mounted. Tracing is ACTIVE."
+          @booted_message_shown = true
+        end
+
+        RailsTraceViewer::Subscribers::ControllerSubscriber.attach
+        RailsTraceViewer::Subscribers::SqlSubscriber.attach
+        RailsTraceViewer::Subscribers::ViewSubscriber.attach
+        RailsTraceViewer::Subscribers::ActiveJobSubscriber.attach
+        RailsTraceViewer::Subscribers::SidekiqSubscriber.attach if defined?(Sidekiq)
         RailsTraceViewer::Subscribers::MethodSubscriber.attach
+
+        RailsTraceViewer::Collector.start_sweeper!
+
+      else
+        RailsTraceViewer.enabled = false
+        
+        unless @booted_message_shown
+          puts "🚫 [RailsTraceViewer] Engine route not found. Tracing DISABLED (Zero Overhead)."
+          @booted_message_shown = true
+        end
       end
     end
-    
-    initializer "rails_trace_viewer.start_sweeper" do
-      RailsTraceViewer::Collector.start_sweeper!
-    end
   end
 end

data/lib/rails_trace_viewer/subscribers/method_subscriber.rb

@@ -12,6 +12,12 @@ module RailsTraceViewer
           is_app_path = path.start_with?(Rails.root.to_s) && 
                         !path.include?("/vendor/") && 
                         !path.include?("rails_trace_viewer")
+
+          is_view_related = path.include?("/app/views/")
+          
+          # Only trace Controllers, Models, Jobs, Services. Skip Views.
+          next unless is_app_path && !is_view_related
+
           is_active_job = (tp.defined_class < ApplicationJob) rescue false
           is_sidekiq_worker = (tp.defined_class.include?(Sidekiq::Worker)) rescue false
 

data/lib/rails_trace_viewer/subscribers/view_subscriber.rb

@@ -1,32 +1,59 @@
 module RailsTraceViewer
   module Subscribers
     class ViewSubscriber
-      EVENTS = ["render_template.action_view", "render_partial.action_view"]
-
       def self.attach
         return if @attached
         @attached = true
 
-        EVENTS.each do |event|
-          ActiveSupport::Notifications.subscribe(event) do |*_args, payload|
-            next unless RailsTraceViewer::TraceContext.active?
-
-            file = payload[:identifier]
-            next unless file && file.include?(Rails.root.join("app").to_s)
-
-            node = {
-              id: SecureRandom.uuid,
-              parent_id: RailsTraceViewer::TraceContext.parent_id,
-              type: "view",
-              name: file.split("/app/").last,
-              source: file.sub(Rails.root.to_s, ''),
-              layout: payload[:layout],
-              full_path: file,
-              children: []
-            }
-
-            RailsTraceViewer::Collector.add_node(RailsTraceViewer::TraceContext.trace_id, node)
-          end
+        subscriber = new
+        ActiveSupport::Notifications.subscribe("render_template.action_view", subscriber)
+        ActiveSupport::Notifications.subscribe("render_partial.action_view", subscriber)
+      end
+
+      def start(name, id, payload)
+        file = payload[:identifier]
+        
+        return unless file && file.start_with?(Rails.root.to_s)
+
+        if !RailsTraceViewer::TraceContext.active?
+          trace_id = SecureRandom.uuid
+          RailsTraceViewer::TraceContext.start!(trace_id)
+          RailsTraceViewer::Collector.start_trace(trace_id)
+          Thread.current["rtv_view_root_#{id}"] = true
+        end
+
+        trace_id = RailsTraceViewer::TraceContext.trace_id
+        parent_id = RailsTraceViewer::TraceContext.parent_id
+        node_id = SecureRandom.uuid
+
+        Thread.current["rtv_view_node_#{id}"] = node_id
+
+        relative_path = file.sub(Rails.root.to_s, '')
+
+        node = {
+          id: node_id,
+          parent_id: parent_id,
+          type: "view",
+          name: relative_path.split("/").last,
+          source: relative_path,
+          layout: payload[:layout],
+          full_path: file,
+          children: []
+        }
+
+        RailsTraceViewer::Collector.add_node(trace_id, node)
+        RailsTraceViewer::TraceContext.push(node_id)
+      end
+
+      def finish(name, id, payload)
+        if Thread.current["rtv_view_node_#{id}"]
+          RailsTraceViewer::TraceContext.pop
+          Thread.current["rtv_view_node_#{id}"] = nil
+        end
+
+        if Thread.current["rtv_view_root_#{id}"]
+          RailsTraceViewer::TraceContext.stop!
+          Thread.current["rtv_view_root_#{id}"] = nil
         end
       end
     end

data/lib/rails_trace_viewer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsTraceViewer
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/rails_trace_viewer.rb

@@ -18,5 +18,14 @@ require "rails_trace_viewer/subscribers/sidekiq_subscriber"
 require "rails_trace_viewer/subscribers/method_subscriber"
 
 module RailsTraceViewer
-  # Public API can be added here later
+  mattr_accessor :enabled
+  self.enabled = true
+
+  def self.enabled?
+    !!self.enabled
+  end
+
+  def self.configure
+    yield self
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rails_trace_viewer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Aditya-JOSH 
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -102,6 +101,7 @@ metadata:
   homepage_uri: https://github.com/Aditya-JOSH/rails_trace_viewer
   source_code_uri: https://github.com/Aditya-JOSH/rails_trace_viewer
   changelog_uri: https://github.com/Aditya-JOSH/rails_trace_viewer/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/Aditya-JOSH/rails_trace_viewer/blob/main/README.md
 post_install_message: 'Thanks for installing Rails Trace Viewer! Don''t forget to
   mount the engine in your config/routes.rb: mount RailsTraceViewer::Engine => ''/rails_trace_viewer'''
 rdoc_options: []
@@ -118,8 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Visualize Rails request flow in real-time.
 test_files: []