callstacking-rails 0.1.2 → 0.1.3

data/README.md

@@ -1,4 +1,4 @@
-# Checkpoint::Rails
+# Callstacking::Rails
 
 Callstacking is a rolling, checkpoint debugger for Rails.  It records all of the critical method calls within your app, along with their important context (param/argument/return/local variable values).  
 
@@ -17,13 +17,13 @@ For method returns ↳, the final values of the local variables will be listed w
 
 Subsequent calls within a method are visibly nested.
 
-Checkpoint is a Rails engine that you mount within your Rails app.
+Callstacking is a Rails engine that you mount within your Rails app.
 
 Here's a sample debugging sessions recorded from a Jumpstart Rails based app I've been working on.  This is a request for the main page ( https://smartk.id/ ).
 
 ![image](https://user-images.githubusercontent.com/4600/190882432-58092e38-7ee2-4138-b13a-f45ff2b09227.png)
 
-Checkpoint Rails records all of the critical method calls within your app, along with their important context (param/argument/return/local variable values).
+Callstacking Rails records all of the critical method calls within your app, along with their important context (param/argument/return/local variable values).
 
 All in a rolling panel, so that you can debug your call chains from any point in the stack.
 
@@ -42,11 +42,54 @@ And then execute:
 ```bash
 $ bundle
 ```
+   
+Register an account at Callstacking.com
+```bash
+callstacking-rails register
+```
+
+Authenticate to your newly created account.
+
+```bash
+callstacking-rails setup
+```
+            
+You're now ready to start tracing.
 
 ## Usage
-When you open a page for your app, once the page has rendered, you will see an arrow on the right hand side.
+Usage:
+
+> callstacking-rails enable
+
+Enables the callstacking tracing.
+
+> callstacking-rails disable
+
+Disables the callstacking tracing.
+
+> callstacking-rails register
+
+Opens a browser window to register as a callstacking.com user.
+
+> callstacking-rails setup
+
+Interactively prompts you for your callstacking.com username/password.
+Stores auth details in `~/.callstacking`.
+
+You can have multiple environments.
+The default is `development`.
+
+The `development:` section in the `~/.callstacking` config contains your credentials.
+
+By setting the RAILS_ENV environment you can maintain multiple settings.
+
+Questions? Create an issue: https://github.com/callstacking/callstacking-rails/issues
+
+
+## Trace Output
+When you open a page for your app, once the page has rendered, you will see an `<<` arrow on the right hand side.
 
-Click the arrow, and observe the full callstack context.
+Click the arrows, and observe the full callstack context.
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [GPLv3 License](https://www.gnu.org/licenses/gpl-3.0.en.html).

data/app/assets/config/callstacking_rails_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/callstacking/rails .css

data/app/controllers/{checkpoint → callstacking}/rails/application_controller.rb

@@ -1,4 +1,4 @@
-module Checkpoint
+module Callstacking
   module Rails
     class ApplicationController < ActionController::Base
     end

data/app/helpers/{checkpoint → callstacking}/rails/application_helper.rb

@@ -1,4 +1,4 @@
-module Checkpoint
+module Callstacking
   module Rails
     module ApplicationHelper
     end

data/app/jobs/{checkpoint → callstacking}/rails/application_job.rb

@@ -1,4 +1,4 @@
-module Checkpoint
+module Callstacking
   module Rails
     class ApplicationJob < ActiveJob::Base
     end

data/app/mailers/{checkpoint → callstacking}/rails/application_mailer.rb

@@ -1,4 +1,4 @@
-module Checkpoint
+module Callstacking
   module Rails
     class ApplicationMailer < ActionMailer::Base
       default from: "from@example.com"

data/app/models/{checkpoint → callstacking}/rails/application_record.rb

@@ -1,4 +1,4 @@
-module Checkpoint
+module Callstacking
   module Rails
     class ApplicationRecord < ActiveRecord::Base
       self.abstract_class = true

data/config/routes.rb

@@ -1,4 +1,4 @@
-Checkpoint::Rails::Engine.routes.draw do
+Callstacking::Rails::Engine.routes.draw do
   resources :traces
   root to: "traces#index"
 end

data/exe/callstacking-rails

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "callstacking/rails/setup"
+require "callstacking/rails/settings"
+
+include Callstacking::Rails::Settings
+
+action = ARGV[0]&.downcase&.strip
+
+if action.nil?
+  Callstacking::Rails::Setup.instructions
+  exit!(1)
+end
+
+read_settings
+
+case action
+  when 'register'
+    `open #{settings.url || Callstacking::Rails::Settings::PRODUCTION_URL}/users/sign_up`
+
+  when 'setup'
+    Callstacking::Rails::Setup.new.start
+
+  when 'enable'
+    Callstacking::Rails::Setup.new.enable_disable
+    puts "Callstacking tracing enabled (#{Callstacking::Rails::Env.environment})"
+
+  when 'disable'
+    Callstacking::Rails::Setup.new.enable_disable(enabled: false)
+    puts "Callstacking tracing disabled (#{Callstacking::Rails::Env.environment})"
+end

data/lib/{checkpoint → callstacking}/rails/client/authenticate.rb

@@ -1,6 +1,7 @@
 require 'json'
+require "callstacking/rails/client/base"
 
-module Checkpoint
+module Callstacking
   module Rails
     module Client
       class Error < StandardError; end

data/lib/{checkpoint → callstacking}/rails/client/base.rb

@@ -1,14 +1,14 @@
 require 'faraday'
 require 'faraday/follow_redirects'
-require "checkpoint/rails/settings"
+require "callstacking/rails/settings"
 
-module Checkpoint
+module Callstacking
   module Rails
     module Client
       class Error < StandardError; end
 
       class Base
-        include Checkpoint::Rails::Settings
+        include Callstacking::Rails::Settings
 
         def initialize
           read_settings

data/lib/{checkpoint → callstacking}/rails/client/trace.rb

@@ -1,4 +1,6 @@
-module Checkpoint
+require "callstacking/rails/client/base"
+
+module Callstacking
   module Rails
     module Client
       class Trace < Base

data/lib/callstacking/rails/engine.rb

@@ -0,0 +1,49 @@
+require "rails"
+require "callstacking/rails/trace"
+require "callstacking/rails/instrument"
+require 'callstacking/rails/spans'
+require "callstacking/rails/setup"
+require "callstacking/rails/settings"
+require "callstacking/rails/loader"
+require "callstacking/rails/client/base"
+require "callstacking/rails/client/authenticate"
+require "callstacking/rails/client/trace"
+require "callstacking/rails/traces_helper"
+
+module Callstacking
+  module Rails
+    class Engine < ::Rails::Engine
+      include Settings
+      isolate_namespace Callstacking::Rails
+
+      read_settings
+
+      spans = Spans.new
+      trace = Trace.new(spans)
+
+      initializer "engine_name.assets.precompile" do |app|
+        app.config.assets.precompile << "checkpoint_rails_manifest.js"
+      end
+
+      initializer 'local_helper.action_controller' do
+        ActiveSupport.on_load :action_controller do
+          helper Callstacking::Rails::TracesHelper
+          include Callstacking::Rails::TracesHelper
+        end
+
+        Callstacking::Rails::Loader.new.on_load(spans) if enabled?
+      end
+
+      initializer :append_before_action do
+        ActionController::Base.send :after_action, :inject_hud
+      end
+
+      if enabled?
+        puts "Callstacking enabled (#{Callstacking::Rails::Env.environment})"
+        trace.tracing
+      else
+        puts "Callstacking disabled (#{Callstacking::Rails::Env.environment})"
+      end
+    end
+  end
+end

data/lib/{checkpoint → callstacking}/rails/env.rb

@@ -1,4 +1,6 @@
-module Checkpoint
+require "active_support/inflector"
+
+module Callstacking
   module Rails
     class Env
       DEFAULT_ENVIRONMENT = "development"

data/lib/callstacking/rails/instrument.rb

@@ -0,0 +1,100 @@
+require 'rails'
+
+# https://stackoverflow.com/q/52932516
+module Callstacking
+  module Rails
+    class Instrument
+      attr_accessor :spans, :klass
+      attr_reader :root
+
+      def initialize(spans, klass)
+        @spans = spans
+        @klass = klass
+        @root  = Regexp.new(::Rails.root.to_s)
+      end
+
+      def instrument_method(method_name, application_level: true)
+        method_path = (klass.instance_method(method_name).source_location.first rescue nil) ||
+          (klass.method(method_name).source_location.first rescue nil)
+
+        # Application level method definitions
+        return unless method_path =~ root if application_level
+
+        tmp_module = find_or_initialize_module
+
+        return if tmp_module.instance_methods.include?(method_name) ||
+                    tmp_module.singleton_methods.include?(method_name)
+
+        tmp_module.define_method(method_name) do |*args, &block|
+          method_name = __method__
+
+          path = method(__method__).super_method.source_location.first
+          line_no = method(__method__).super_method.source_location.last
+
+          p, l = caller.find { |c| c.to_s =~ /#{::Rails.root.to_s}/}&.split(':')
+
+          spans = tmp_module.instance_variable_get(:@spans)
+          klass = tmp_module.instance_variable_get(:@klass)
+
+          arguments = Callstacking::Rails::Instrument.arguments_for(method(__method__).super_method, args)
+          
+          spans.call_entry(klass, method_name, arguments, p || path, l || line_no)
+          return_val = super(*args, &block)
+          spans.call_return(klass, method_name, p || path, l || line_no, return_val)
+
+          return_val
+        end
+      end
+
+      def find_or_initialize_module
+        module_name = "#{klass.name.gsub('::', '')}Span"
+        module_index = klass.ancestors.map(&:to_s).index(module_name)
+
+        unless module_index
+          new_module = Object.const_set(module_name, Module.new)
+
+          new_module.instance_variable_set("@klass", klass)
+          new_module.instance_variable_set("@spans", spans)
+
+          klass.prepend new_module
+          klass.singleton_class.prepend new_module if klass.class == Module
+
+          return find_or_initialize_module
+        end
+
+        klass.ancestors[module_index]
+      end
+
+      def instrument_klass(application_level: true)
+        relevant = all_methods - filtered
+        relevant.each { |method| instrument_method(method, application_level: application_level) }
+      end
+
+      def self.arguments_for(m, args)
+        param_names = m.parameters&.map(&:last)
+        return {} if param_names.nil?
+
+        param_names.map.with_index do |param, index|
+          next if [:&, :*, :**].include?(param)
+          [param, args[index]]
+        end.compact.to_h
+      end
+
+      private
+
+      def all_methods
+        @all_methods ||= (klass.instance_methods +
+          klass.private_instance_methods(false) +
+          klass.protected_instance_methods(false) +
+          klass.methods +
+          klass.singleton_methods).uniq
+      end
+
+      def filtered
+        @filtered ||= (Object.instance_methods + Object.private_instance_methods +
+          Object.protected_instance_methods + Object.methods(false)).uniq
+      end
+
+    end
+  end
+end

data/lib/callstacking/rails/loader.rb

@@ -0,0 +1,29 @@
+require "rails"
+
+module Callstacking
+  module Rails
+    class Loader
+      attr_accessor :loader, :root, :once
+      def initialize
+        @root = Regexp.new(::Rails.root.to_s)
+      end
+
+      def on_load(spans)
+        trace = TracePoint.new(:end) do |tp|
+          klass = tp.self
+          path  = tp.path
+
+          Instrument.new(spans, klass).instrument_klass if path =~ root
+        end
+
+        trace.enable
+
+        Instrument.new(spans, ActionView::PartialRenderer).instrument_method(:render,
+                                                                             application_level: false)
+        
+        Instrument.new(spans, ActionView::TemplateRenderer).instrument_method( :render,
+                                                                               application_level: false)
+      end
+    end
+  end
+end

data/lib/{checkpoint → callstacking}/rails/settings.rb

@@ -1,8 +1,8 @@
 require "active_support/concern"
 require "active_support/core_ext/class/attribute_accessors"
-require "checkpoint/rails/env"
+require "callstacking/rails/env"
 
-module Checkpoint
+module Callstacking
   module Rails
     module Settings
       extend ActiveSupport::Concern
@@ -11,7 +11,7 @@ module Checkpoint
         attr_accessor :settings
       end
 
-      SETTINGS_FILE = "#{Dir.home}/.callstacking-rails"
+      SETTINGS_FILE = "#{Dir.home}/.callstacking"
       PRODUCTION_URL = "https://callstacking.com"
 
       def url
@@ -30,8 +30,16 @@ module Checkpoint
         File.write(SETTINGS_FILE, new_settings.to_yaml)
       end
 
+      def enabled?
+        settings[:enabled]
+      end
+
+      def disabled?
+        !enabled?
+      end
+
       def read_settings
-        @@settings = @settings = complete_settings.dig(::Checkpoint::Rails::Env.environment, :settings)
+        @@settings = @settings = complete_settings.dig(::Callstacking::Rails::Env.environment, :settings)
       rescue StandardError => e
         puts e.full_message
         puts e.backtrace.join("\n")
@@ -39,7 +47,7 @@ module Checkpoint
       end
 
       def complete_settings
-        YAML.load(File.read(Checkpoint::Rails::Client::Base::SETTINGS_FILE)) rescue {}
+        YAML.load(File.read(SETTINGS_FILE)) rescue {}
       end
     end
   end

data/lib/callstacking/rails/setup.rb

@@ -0,0 +1,115 @@
+require 'yaml'
+require "callstacking/rails/settings"
+require "callstacking/rails/client/authenticate"
+require "callstacking/rails/env"
+
+module Callstacking
+  module Rails
+    class Setup
+      include ::Callstacking::Rails::Settings
+      extend ::Callstacking::Rails::Settings
+
+      attr_accessor :client
+
+      def initialize
+        read_settings
+      end
+
+      def client
+        @client = Callstacking::Rails::Client::Authenticate.new
+      end
+
+      def start
+        email      = prompt("Enter email:")
+        password   = prompt("Enter password:")
+
+        url = if Callstacking::Rails::Env.production? && ENV['CHECKPOINT_RAILS_LOCAL_TEST'].nil?
+                PRODUCTION_URL
+              else
+                prompt("Enter URL for #{Callstacking::Rails::Env.environment} API calls [#{PRODUCTION_URL}]:") || PRODUCTION_URL
+              end
+
+        save(email, password, url)
+
+        puts "Authentication successful."
+        puts "Settings saved to #{SETTINGS_FILE}"
+      rescue StandardError => e
+        puts "Problem authenticating: #{e.message}"
+      end
+
+      def enable_disable(enabled: true)
+        settings[:enabled] = enabled
+
+        props = { Callstacking::Rails::Env.environment => {
+          settings: settings
+        } }
+
+        write_settings(complete_settings.merge(props))
+      end
+
+      def prompt(label)
+        puts label
+        value = STDIN.gets.chomp
+        puts
+
+        return nil if value == ''
+        value
+      end
+
+      def token(email, password)
+        client.login(email, password)
+      end
+
+      def save(email, password, url)
+        props = { auth_token: '',
+                  url: url,
+                  enabled: true
+        }
+
+        props = { Callstacking::Rails::Env.environment => {
+          settings: props
+        } }
+
+        write_settings(complete_settings.merge(props))
+
+        props[Callstacking::Rails::Env.environment][:settings][:auth_token] = token(email, password)
+
+        write_settings(complete_settings.merge(props))
+
+        read_settings
+      end
+
+      def self.instructions
+        read_settings
+        puts "loading environment #{Callstacking::Rails::Env.environment}"
+        puts
+        puts "Usage: "
+        puts
+        puts "  > callstacking-rails enable"
+        puts
+        puts "    Enables the callstacking tracing."
+        puts
+        puts "  > callstacking-rails disable"
+        puts
+        puts "    Disables the callstacking tracing."
+        puts
+        puts "  > callstacking-rails register"
+        puts
+        puts "    Opens a browser window to register as a callstacking.com user."
+        puts
+        puts "  > callstacking-rails setup"
+        puts
+        puts "    Interactively prompts you for your callstacking.com username/password."
+        puts "    Stores auth details in #{SETTINGS_FILE}"
+        puts
+        puts " You can have multiple environments."
+        puts " The default is #{Callstacking::Rails::Env::DEFAULT_ENVIRONMENT}."
+        puts
+        puts " The #{Callstacking::Rails::Env.environment}: section in the #{SETTINGS_FILE} contains your credentials."
+        puts " By setting the RAILS_ENV environment you can maintain multiple settings."
+        puts
+        puts "Questions? Create an issue: https://github.com/callstacking/callstacking-rails/issues"
+      end
+    end
+  end
+end

data/lib/callstacking/rails/spans.rb

@@ -0,0 +1,53 @@
+module Callstacking
+  module Rails
+    class Spans
+      attr_accessor :order_num, :nesting_level, :previous_entry
+      attr_accessor :call_entry_callback, :call_return_callback
+
+      def initialize
+        @nesting_level = -1
+        @order_num = -1
+        @previous_entry = nil
+      end
+
+      def increment_order_num
+        @order_num+=1
+        @order_num
+      end
+
+      def increment_nesting_level
+        @nesting_level+=1
+        @nesting_level
+      end
+
+      def call_entry(klass, method_name, arguments, path, line_no)
+        @nesting_level+=1
+        @previous_entry = previous_event(klass, method_name)
+        @call_entry_callback.call(@nesting_level, increment_order_num, klass, method_name, arguments, path, line_no)
+      end
+
+      def call_return(klass, method_name, path, line_no, return_val)
+        @call_return_callback.call(coupled_callee(klass, method_name), @nesting_level,
+                                   increment_order_num, klass, method_name, path, line_no, return_val)
+        @nesting_level-=1
+      end
+
+      def on_call_entry(&block)
+        @call_entry_callback = block
+      end
+
+      def on_call_return(&block)
+        @call_return_callback = block
+      end
+
+      private
+      def previous_event(klass, method_name)
+        "#{klass}:#{method_name}"
+      end
+
+      def coupled_callee(klass, method_name)
+        previous_entry == previous_event(klass, method_name)
+      end
+    end
+  end
+end