singed 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5276eb42b69baf43de15c7ad5a3549f048d00865f225998eb4479b6e7723f2b8
+  data.tar.gz: 0f46bfb076f12a4766e060a017f2cb0e9ad6af98a96b8f96ebf05b58205aac21
+SHA512:
+  metadata.gz: 81b34cf130fbe187680d65ba593ee68ce606e72cbb5db99284aba82beb6bf9ac17cef5104850a49ebba7bce87cc8a11b39f4b0897accb9bc6e0cb268ee35168e
+  data.tar.gz: 23e265212f1f70ebe105c218dde2025728782ae1574ef2abcf4705b04e13eeab7bd9b6197442b950517492c5a540a2ebaa99478d7841b4170a8611ff668094a9

data/README.md

@@ -0,0 +1,102 @@
+# Singed
+
+Singed makes it easy to get a flamegraph anywhere in your code base:
+
+## Usage
+
+To profile your code, and launch [speedscope](https://github.com/jlfwong/speedscope) for viewing it:
+
+```ruby
+flamegraph {
+  # your code here
+}
+```
+
+Flamegraphs are saved for later review to `Singed.output_directory`, which is `tmp/speedscope` on Rails. You can adjust this like:
+
+```ruby
+Singed.output_directory = "tmp/slowness-exploration"
+```
+
+### Blockage
+If you are calling it in a loop, or with different variations, you can include a label on the filename:
+
+```ruby
+flamegraph(label: "rspec") {
+  # your code here
+}
+```
+
+You can also skip opening speedscope automatically:
+
+```ruby
+flamegraph(open: false) {
+  # your code here
+}
+```
+
+### RSpec
+
+If you are using RSpec, you can use the `flamegraph` metadata to capture it for you.
+
+```ruby
+# make sure this is required at somepoint, like in a spec/support file!
+require 'singed/rspec' 
+
+RSpec.describe YourClass do
+  it "is slow :(", flamegraph: true do
+    # your code here
+  end
+end
+```
+
+### Controllers
+
+If you want to capture a flamegraph of a controller action, you can call it like:
+
+```ruby
+class EmployeesController < ApplicationController
+  flamegraph :show
+
+  def show
+    # your code here
+  end
+end
+```
+
+This won't catch the entire request though, just once it's been routed to controller and a response has been served.
+
+### Rack/Rails requests
+
+To capture the whole request, there is a middleware which checks for the  `X-Singed` header to be 'true'. With curl, you can do this like:
+
+```shell
+curl -H 'X-Singed: true' https://localhost:3000
+```
+
+PROTIP: use Chrome Developer Tools to record network activity, and copy requests as a curl command. Add `-H 'X-Singed: true'` to it, and you get flamegraphs!
+
+This can also be enabled to always run by setting `SINGED_MIDDLEWARE_ALWAYS_CAPTURE=1`  in the environment.
+
+### Command Line
+
+There is a `singed` command line you can use that will record a flamegraph from the entirety of a command run:
+
+```shell
+$ bundle binstub singed # if you want to be able to call it like bin/singed
+$ bundle exec singed -- bin/rails 
+```
+
+The flamegraph is opened afterwards.
+
+
+## Limitations
+
+When using the auto-opening feature, it's assumed that you are have a browser available on the same host you are profiling code.
+
+The `open` is expected to be available.
+
+## Alternatives
+
+- using [rbspy](https://rbspy.github.io/) directory
+- using [stackprof](https://github.com/tmm1/stackprof) (a dependency of singed) directly

data/exe/singed

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+
+require 'singed/cli'
+if Singed::CLI.chdir_rails_root
+  require './config/environment'
+end
+
+Singed::CLI.new(ARGV).run

data/lib/singed/backtrace_cleaner_ext.rb

@@ -0,0 +1,16 @@
+module ActiveSupport
+  class BacktraceCleaner
+    def filter_line(line)
+      filtered_line = line
+      @filters.each do |f|
+        filtered_line = f.call(filtered_line)
+      end
+
+      filtered_line
+    end
+
+    def silence_line?(line)
+      @silencers.any? { |s| s.call(line) }
+    end
+  end
+end

data/lib/singed/cli.rb

@@ -0,0 +1,168 @@
+require 'shellwords'
+require 'tmpdir'
+require 'optionparser'
+
+# NOTE: we defer requiring singed until we run. that lets Rails load it if its in the gemfile, so the railtie has had a chance to run
+
+module Singed
+  class CLI
+    attr_accessor :argv, :filename, :opts
+
+    def initialize(argv)
+      @argv = argv
+      @opts = OptionParser.new
+
+      parse_argv!
+    end
+
+    def parse_argv!
+      opts.banner = 'Usage: singed [options] <command>'
+
+      opts.on('-h', '--help', 'Show this message') do
+        @show_help = true
+      end
+
+      opts.on('-o', '--output-directory DIRECTORY', 'Directory to write flamegraph to') do |directory|
+        @output_directory = directory
+      end
+
+      opts.order(@argv) do |arg|
+        opts.terminate if arg == '--'
+        break
+      end
+
+      if @argv.empty?
+        @show_help = true
+        @error_message = 'missing command to profile'
+        return
+      end
+
+      return if @show_help
+
+      begin
+        @opts.parse!(argv)
+      rescue OptionParser::InvalidOption => e
+        @show_help = true
+        @error_message = e
+      end
+    end
+
+    def run
+      require 'singed'
+
+      if @error_message
+        puts @error_message
+        puts
+        puts @opts.help
+        exit 1
+      end
+
+      if show_help?
+        puts @opts.help
+        exit 0
+      end
+
+      Singed.output_directory = @output_directory if @output_directory
+      Singed.output_directory ||= Dir.tmpdir
+      @filename = Singed::Flamegraph.generate_filename(label: 'cli')
+
+      options = {
+        format: 'speedscope',
+        file: filename.to_s,
+        silent: nil,
+      }
+
+      rbspy_args = [
+        'record',
+        *options.map { |k, v| ["--#{k}", v].compact }.flatten,
+        '--',
+        *argv,
+      ]
+
+      loop do
+        break unless password_needed?
+
+        puts '🔥📈 Singed needs to run as root, but will drop permissions back to your user. Prompting with sudo now...'
+        prompt_password
+      end
+
+      Bundler.with_unbundled_env do
+        # don't run things with spring, because it forks and rbspy won't see it
+        sudo ['rbspy', *rbspy_args], reason: 'Singed needs to run as root, but will drop permissions back to your user.', env: { 'DISABLE_SPRING' => '1' }
+      end
+
+      unless filename.exist?
+        puts "#{filename} doesn't exist. Maybe rbspy had a failure capturing it? Check the scrollback."
+        exit 1
+      end
+
+      unless adjust_ownership!
+        puts "#{filename} isn't writable!"
+        exit 1
+      end
+
+      # clean the report, similar to how Singed::Report does
+      json = JSON.parse(filename.read).with_indifferent_access
+      json['shared']['frames'].each do |frame|
+        frame[:file] = Singed.filter_line(frame[:file])
+      end
+      filename.write(JSON.dump(json))
+
+      flamegraph = Singed::Flamegraph.new(filename: filename)
+      flamegraph.open
+    end
+
+    def password_needed?
+      !system('sudo --non-interactive true >/dev/null 2>&1')
+    end
+
+    def prompt_password
+      system('sudo true')
+    end
+
+    def adjust_ownership!
+      sudo ['chown', ENV['USER'], filename], reason: "Adjusting ownership of #{filename}, but need root."
+    end
+
+    def show_help?
+      @show_help
+    end
+
+    def sudo(system_args, reason:, env: {})
+      loop do
+        break unless password_needed?
+
+        puts "🔥📈 #{reason} Prompting with sudo now..."
+        prompt_password
+      end
+
+      sudo_args = [
+        'sudo',
+        '--preserve-env',
+        *system_args.map(&:to_s),
+      ]
+
+      puts "$ #{Shellwords.join(sudo_args)}"
+
+      system(env, *sudo_args, exception: true)
+    end
+
+    def self.chdir_rails_root
+      original_cwd = Dir.pwd
+
+      loop do
+        if File.file?('config/environment.rb')
+          return Dir.pwd
+        end
+
+        if Pathname.new(Dir.pwd).root?
+          Dir.chdir(original_cwd)
+          return
+        end
+
+        # Otherwise keep moving upwards in search of an executable.
+        Dir.chdir('..')
+      end
+    end
+  end
+end

data/lib/singed/controller_ext.rb

@@ -0,0 +1,16 @@
+module Singed
+  module ControllerExt
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Define an around_action to generate flamegraph for a controller action.
+      def flamegraph(target_action, ignore_gc: false, interval: 1000)
+        around_action(only: target_action) do |controller, action|
+          controller.flamegraph(ignore_gc: ignore_gc, interval: interval, &action)
+        end
+      end
+    end
+  end
+end

data/lib/singed/flamegraph.rb

@@ -0,0 +1,66 @@
+module Singed
+  class Flamegraph
+    attr_accessor :profile, :filename
+
+    def initialize(label: nil, ignore_gc: false, interval: 1000, filename: nil)
+      # it's been created elsewhere, ie rbspy
+      if filename
+        if ignore_gc
+          raise ArgumentError, 'ignore_gc not supported when given an existing file'
+        end
+
+        if label
+          raise ArgumentError, 'label not supported when given an existing file'
+        end
+
+        @filename = filename
+      else
+        @ignore_gc = ignore_gc
+        @interval = interval
+        @time = Time.now # rubocop:disable Rails/TimeZone
+        @filename = self.class.generate_filename(label: label, time: @time)
+      end
+    end
+
+    def record
+      return yield unless Singed.enabled?
+      return yield if filename.exist? # file existing means its been captured already
+
+      result = nil
+      @profile = StackProf.run(mode: :wall, raw: true, ignore_gc: @ignore_gc, interval: @interval) do
+        result = yield
+      end
+      result
+    end
+
+    def save
+      if filename.exist?
+        raise ArgumentError, "File #{filename} already exists"
+      end
+
+      report = Singed::Report.new(@profile)
+      report.filter!
+      filename.dirname.mkpath
+      filename.open('w') { |f| report.print_json(f) }
+    end
+
+    def open
+      system open_command
+    end
+
+    def open_command
+      @open_command ||= "npx speedscope #{@filename}"
+    end
+
+    def self.generate_filename(label: nil, time: Time.now) # rubocop:disable Rails/TimeZone
+      formatted_time = time.to_formatted_s(:number)
+      basename_parts = ['speedscope', label, formatted_time].compact
+
+      file = Singed.output_directory.join("#{basename_parts.join('-')}.json")
+      # convert to relative directory if it's an absolute path and within the current
+      pwd = Pathname.pwd
+      file = file.relative_path_from(pwd) if file.absolute? && file.to_s.start_with?(pwd.to_s)
+      file
+    end
+  end
+end

data/lib/singed/kernel_ext.rb

@@ -0,0 +1,17 @@
+module Kernel
+  def flamegraph(label = nil, open: true, ignore_gc: false, interval: 1000, &block)
+    fg = Singed::Flamegraph.new(label: label, ignore_gc: ignore_gc, interval: interval)
+    result = fg.record(&block)
+    fg.save
+
+    if open
+      # use npx, so we don't have to add it as a dependency
+      puts "🔥📈 #{'Captured flamegraph, opening with'.colorize(:bold).colorize(:red)}: #{fg.open_command}"
+      fg.open
+    else
+      puts "🔥📈 #{'Captured flamegraph to file'.colorize(:bold).colorize(:red)}: #{fg.filename}"
+    end
+
+    result
+  end
+end

data/lib/singed/rack_middleware.rb

@@ -0,0 +1,35 @@
+# Rack Middleware
+
+require 'rack'
+
+module Singed
+  class RackMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = if capture_flamegraph?(env)
+        flamegraph do
+          @app.call(env)
+        end
+      else
+        @app.call(env)
+      end
+
+      [status, headers, body]
+    end
+
+    def capture_flamegraph?(env)
+      self.class.always_capture? || env['HTTP_X_SINGED'] == 'true'
+    end
+
+    TRUTHY_STRINGS = ['true', '1', 'yes'].freeze
+
+    def self.always_capture?
+      return @always_capture if defined?(@always_capture)
+
+      @always_capture = TRUTHY_STRINGS.include?(ENV.fetch('SINGED_MIDDLEWARE_ALWAYS_CAPTURE', 'false'))
+    end
+  end
+end

data/lib/singed/railtie.rb

@@ -0,0 +1,21 @@
+require 'singed/backtrace_cleaner_ext'
+require 'singed/controller_ext'
+
+module Singed
+  class Railtie < Rails::Railtie
+    initializer 'singed.configure_rails_initialization' do |app|
+      self.class.init!
+
+      app.middleware.use Singed::RackMiddleware
+
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Base.include(Singed::ControllerExt)
+      end
+    end
+
+    def self.init!
+      Singed.output_directory = Rails.root.join('tmp/speedscope')
+      Singed.backtrace_cleaner = Rails.backtrace_cleaner
+    end
+  end
+end

data/lib/singed/report.rb

@@ -0,0 +1,37 @@
+module Singed
+  class Report < StackProf::Report
+    def filter!
+      # copy and paste from StackProf::Report#print_graphviz that does filtering
+      # mark_stack = []
+      list = frames(true)
+      # WIP to filter out frames we care about... unfortunately, speedscope just hangs while loading as is
+      # # build list of frames to mark for keeping
+      # list.each do |addr, frame|
+      #   mark_stack << addr unless Singed.silence_line?(frame[:file])
+      # end
+
+      # # while more addresses to mark
+      # while addr = mark_stack.pop
+      #   frame = list[addr]
+      #   # if it hasn't been marked yet
+      #   unless frame[:marked]
+      #     # collect edges to mark
+      #     if frame[:edges]
+      #       mark_stack += frame[:edges].map{ |addr, weight| addr if list[addr][:total_samples] <= weight*1.2 }.compact
+      #     end
+      #     # mark it so we don't process again
+      #     frame[:marked] = true
+      #   end
+      # end
+      # list = list.select{ |_addr, frame| frame[:marked] }
+      # list.each{ |_addr, frame| frame[:edges]&.delete_if{ |k,v| list[k].nil? } }
+      # end copy-pasted section
+
+      list.each do |_addr, frame|
+        frame[:file] = Singed.filter_line(frame[:file])
+      end
+
+      @data[:frames] = list
+    end
+  end
+end

data/lib/singed/rspec.rb

@@ -0,0 +1,11 @@
+require 'singed'
+
+RSpec.configure do |config|
+  config.around do |example|
+    if example.metadata[:flamegraph]
+      flamegraph { example.run }
+    else
+      example.run
+    end
+  end
+end

data/lib/singed.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'stackprof'
+require 'colorize'
+
+module Singed
+  extend self
+
+  # Where should flamegraphs be saved?
+  def output_directory=(directory)
+    @output_directory = Pathname.new(directory)
+  end
+
+  def self.output_directory
+    @output_directory || raise("output directory hasn't been set!")
+  end
+
+  def enabled=(enabled)
+    @enabled = enabled
+  end
+
+  def enabled?
+    return @enabled if defined?(@enabled)
+
+    @enabled = true
+  end
+
+  def backtrace_cleaner=(backtrace_cleaner)
+    @backtrace_cleaner = backtrace_cleaner
+  end
+
+  def backtrace_cleaner
+    @backtrace_cleaner
+  end
+
+  def silence_line?(line)
+    return backtrace_cleaner.silence_line?(line) if backtrace_cleaner
+
+    false
+  end
+
+  def filter_line(line)
+    return backtrace_cleaner.filter_line(line) if backtrace_cleaner
+
+    line
+  end
+
+  autoload :Flamegraph, 'singed/flamegraph'
+  autoload :Report, 'singed/report'
+  autoload :RackMiddleware, 'singed/rack_middleware'
+end
+
+require 'singed/kernel_ext'
+require 'singed/railtie' if defined?(Rails::Railtie)
+require 'singed/rspec' if defined?(RSpec)

data/singed.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = 'singed'
+
+  spec.version       = '0.1.0'
+  spec.authors       = ['Josh Nichols']
+  spec.email         = ['josh.nichols@gusto.com']
+
+  spec.summary       = 'Quick and easy way to get flamegraphs from a specific part of your code base'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  # spec.metadata['allowed_push_host'] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.files         = Dir['README.md', '*.gemspec', 'lib/**/*', 'exe/**/*']
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r(\Aexe/)) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'colorize'
+  spec.add_dependency 'stackprof'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: singed
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josh Nichols
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-01-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: stackprof
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 
+email:
+- josh.nichols@gusto.com
+executables:
+- singed
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/singed
+- lib/singed.rb
+- lib/singed/backtrace_cleaner_ext.rb
+- lib/singed/cli.rb
+- lib/singed/controller_ext.rb
+- lib/singed/flamegraph.rb
+- lib/singed/kernel_ext.rb
+- lib/singed/rack_middleware.rb
+- lib/singed/railtie.rb
+- lib/singed/report.rb
+- lib/singed/rspec.rb
+- singed.gemspec
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.4
+signing_key: 
+specification_version: 4
+summary: Quick and easy way to get flamegraphs from a specific part of your code base
+test_files: []