callstacking-rails 0.1.0

data/README.md

@@ -0,0 +1,95 @@
+# 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).  
+
+You no longer need to debug with `binding.pry` or `puts` statements, as the entire callstack for a given request is captured.
+
+Demo video:
+[![Watch the video](https://user-images.githubusercontent.com/4600/190929740-fc68e18f-9572-41be-9719-cc6a8077e97f.png)](https://www.youtube.com/watch?v=NGqnwcNWv_k)
+
+Class method calls are labeled.  Return values for those calls are denoted with ↳
+
+Arguments for a method will be listed along with their calling values.
+
+For method returns ↳, the final values of the local variables will be listed when you hover over the entry.
+
+<img width="1695" alt="CleanShot 2022-09-17 at 21 10 32@2x" src="https://user-images.githubusercontent.com/4600/190882603-a99e9358-9754-4cbf-ac68-a41d53afe747.png">
+
+Subsequent calls within a method are visibly nested.
+
+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)
+
+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.
+
+You'll never have to debug with `puts` statements ever again.
+
+Calls are visibly nested so that it's easy to see which calls are issued from which parent methods.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "callstacking-rails"
+```
+
+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
+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-rails`.
+
+You can have multiple environments.
+The default is `development`.
+
+The `development:` section in the `~/.callstacking-rails` 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 arrows, and observe the full callstack context.
+
+## License
+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/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/callstacking_rails_manifest.js

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

data/app/assets/stylesheets/callstacking/rails/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/callstacking/rails/application_controller.rb

@@ -0,0 +1,6 @@
+module Callstacking
+  module Rails
+    class ApplicationController < ActionController::Base
+    end
+  end
+end

data/app/helpers/callstacking/rails/application_helper.rb

@@ -0,0 +1,6 @@
+module Callstacking
+  module Rails
+    module ApplicationHelper
+    end
+  end
+end

data/app/jobs/callstacking/rails/application_job.rb

@@ -0,0 +1,6 @@
+module Callstacking
+  module Rails
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/mailers/callstacking/rails/application_mailer.rb

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

data/app/models/callstacking/rails/application_record.rb

@@ -0,0 +1,7 @@
+module Callstacking
+  module Rails
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+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/callstacking/rails/client/authenticate.rb

@@ -0,0 +1,23 @@
+require 'json'
+require "callstacking/rails/client/base"
+
+module Callstacking
+  module Rails
+    module Client
+      class Error < StandardError; end
+
+      class Authenticate < Base
+        URL = "/api/v1/auth.json"
+
+        def login(email, password)
+          resp = post(URL, email: email, password: password)
+
+          raise Faraday::UnauthorizedError if resp&.body.nil?
+
+          body = resp&.body || {}
+          body["token"]
+        end
+      end
+    end
+  end
+end

data/lib/callstacking/rails/client/base.rb

@@ -0,0 +1,56 @@
+require 'faraday'
+require 'faraday/follow_redirects'
+require "callstacking/rails/settings"
+
+module Callstacking
+  module Rails
+    module Client
+      class Error < StandardError; end
+
+      class Base
+        include Callstacking::Rails::Settings
+
+        def initialize
+          read_settings
+        end
+
+        def connection
+          # https://github.com/lostisland/awesome-faraday
+          @connection ||= Faraday.new(url) do |c|
+            c.response :json
+            c.use Faraday::Response::Logger, Logger.new('/tmp/callstacking-rails.log')
+            # c.use Faraday::Response::Logger, nil, { headers: false, bodies: false }
+            c.response :follow_redirects
+            c.use Faraday::Response::RaiseError # raise exceptions on 40x, 50x responses
+            c.request :json # This will set the "Content-Type" header to application/json and call .to_json on the body
+            c.adapter Faraday.default_adapter
+
+            if auth_token?
+              c.request :authorization, :Bearer, auth_token
+            end
+          end
+        end
+
+        def get(url, params = {})
+          connection.get(url, params, headers)
+        end
+
+        def post(url, params = {}, body = {}, headers_ext = {})
+          r(:post, url, params, body, headers_ext)
+        end
+
+        def patch(url, params = {}, body = {}, headers_ext = {})
+          r(:patch, url, params, body, headers_ext)
+        end
+
+        def r(action, url, params = {}, body = {}, _headers_ext = {})
+          connection.send(action, url) do |req|
+            req.params.merge!(params)
+            req.body = body
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/callstacking/rails/client/trace.rb

@@ -0,0 +1,35 @@
+require "callstacking/rails/client/base"
+
+module Callstacking
+  module Rails
+    module Client
+      class Trace < Base
+        CREATE_URL = "/api/v1/traces.json"
+        UPDATE_URL = "/api/v1/traces/:id.json"
+
+        def create(method_name, klass, action_name, format_name, root_path, url, request_id, headers, params)
+          resp = post(CREATE_URL,
+                      {},
+                      { method_name: method_name,
+                        klass: klass,
+                        action_name: action_name,
+                        format_name: format_name,
+                        root_path: root_path,
+                        url: url,
+                        request_id: request_id,
+                        h: headers.to_h,
+                        p: params.to_h,
+                      })
+
+          return resp.body["trace_id"], resp.body["pulse_interval"]
+        end
+
+        def upsert(trace_id, traces)
+          resp = patch(UPDATE_URL.gsub(':id', trace_id), {}, traces)
+
+          resp.status
+        end
+      end
+    end
+  end
+end

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/callstacking/rails/env.rb

@@ -0,0 +1,17 @@
+require "active_support/inflector"
+
+module Callstacking
+  module Rails
+    class Env
+      DEFAULT_ENVIRONMENT = "development"
+
+      cattr_accessor :environment
+
+      @@environment = (ENV['RAILS_ENV'] || DEFAULT_ENVIRONMENT).parameterize(separator: '_').to_sym
+
+      def self.production?
+        @@environment == DEFAULT_ENVIRONMENT.parameterize(separator: '_').to_sym
+      end
+    end
+  end
+end

data/lib/callstacking/rails/instrument.rb

@@ -0,0 +1,88 @@
+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)
+
+          spans.call_entry(klass, method_name, 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
+
+      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/callstacking/rails/settings.rb

@@ -0,0 +1,54 @@
+require "active_support/concern"
+require "active_support/core_ext/class/attribute_accessors"
+require "callstacking/rails/env"
+
+module Callstacking
+  module Rails
+    module Settings
+      extend ActiveSupport::Concern
+
+      included do |base|
+        attr_accessor :settings
+      end
+
+      SETTINGS_FILE = "#{Dir.home}/.callstacking-rails"
+      PRODUCTION_URL = "https://callstacking.com"
+
+      def url
+        settings[:url]
+      end
+
+      def auth_token
+        settings[:auth_token]
+      end
+
+      def auth_token?
+        auth_token.present?
+      end
+
+      def write_settings(new_settings)
+        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(::Callstacking::Rails::Env.environment, :settings)
+      rescue StandardError => e
+        puts e.full_message
+        puts e.backtrace.join("\n")
+        return {}
+      end
+
+      def complete_settings
+        YAML.load(File.read(SETTINGS_FILE)) rescue {}
+      end
+    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