singed 0.3.0 → 0.4.0

data/lib/singed/railtie.rb

@@ -1,9 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
 require "singed/backtrace_cleaner_ext"
 require "singed/controller_ext"
 
 module Singed
   class Railtie < Rails::Railtie
     initializer "singed.configure_rails_initialization" do |app|
+      # Rails instance_execs initializer blocks on the railtie instance.
+      #: self as Singed::Railtie
       self.class.init!
 
       app.middleware.use Singed::RackMiddleware
@@ -13,6 +18,7 @@ module Singed
       end
     end
 
+    #: () -> void
     def self.init!
       Singed.output_directory ||= Rails.root.join("tmp/speedscope")
       Singed.backtrace_cleaner = Rails.backtrace_cleaner

data/lib/singed/report.rb

@@ -1,5 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
 module Singed
   class Report < StackProf::Report
+    #: () -> void
     def filter!
       # copy and paste from StackProf::Report#print_graphviz that does filtering
       # mark_stack = []
@@ -27,11 +31,13 @@ module Singed
       # list.each{ |_addr, frame| frame[:edges]&.delete_if{ |k,v| list[k].nil? } }
       # end copy-pasted section
 
-      list.each do |_addr, frame|
+      list.each_value do |frame|
         frame[:file] = Singed.filter_line(frame[:file])
       end
 
-      @data[:frames] = list
+      # frames(true) above has already raised NoMethodError if @data were nil.
+      data = @data #: as !nil
+      data[:frames] = list
     end
   end
 end

data/lib/singed/rspec.rb

@@ -1,3 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
 require "singed"
 
 RSpec.configure do |config|

data/lib/singed/sidekiq.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Singed
+  module Sidekiq
+    class ServerMiddleware
+      include ::Sidekiq::ServerMiddleware
+
+      TRUTHY_STRINGS = %w(true 1 yes).freeze
+
+      #: [Result] (::Sidekiq::Job, Hash[String, untyped], String) { () -> Result } -> Result
+      def call(job_instance, job_payload, _queue, &block)
+        return block.call unless capture_flamegraph?(job_instance, job_payload)
+
+        flamegraph(flamegraph_label(job_instance, job_payload), &block)
+      end
+
+      private
+
+      # A job class's capture_flamegraph? hook may return any value; only its truthiness counts.
+      #: (::Sidekiq::Job, Hash[String, untyped]) -> top
+      def capture_flamegraph?(job_instance, job_payload)
+        return TRUTHY_STRINGS.include?(job_payload["x-singed"].to_s) if job_payload.key?("x-singed")
+
+        # The optional capture_flamegraph? hook is duck-typed, which Sorbet can't express.
+        job_class = job_class(job_instance, job_payload) #: as untyped
+        return false unless job_class
+        return job_class.capture_flamegraph?(job_payload) if job_class.respond_to?(:capture_flamegraph?)
+
+        TRUTHY_STRINGS.include?(ENV.fetch("SINGED_MIDDLEWARE_ALWAYS_CAPTURE", "false"))
+      end
+
+      #: (::Sidekiq::Job, Hash[String, untyped]) -> String
+      def flamegraph_label(job_instance, job_payload)
+        [job_class(job_instance, job_payload), job_payload["jid"]].compact.join("--")
+      end
+
+      #: (::Sidekiq::Job, Hash[String, untyped]) -> Class[top]?
+      def job_class(job_instance, job_payload)
+        job_class = job_payload.fetch("wrapped", job_instance) # ActiveJob
+        return job_class if job_class.is_a?(Class)
+        return job_class.class if job_class.is_a?(::Sidekiq::Job)
+        # Sidekiq payloads carry the job class as a string, so it can only be resolved at runtime.
+        # rubocop:disable Sorbet/ConstantsFromStrings
+        return job_class.constantize if job_class.respond_to?(:constantize)
+
+        Object.const_get(job_class.to_s)
+        # rubocop:enable Sorbet/ConstantsFromStrings
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/singed/speedscope.rb

@@ -0,0 +1,88 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "rbconfig"
+require "tmpdir"
+
+module Singed
+  module Speedscope
+    # Take latest version from https://github.com/jlfwong/speedscope/releases
+    # that have ZIP archive with self-contained version published
+    VERSION = "1.24.0"
+
+    class << self
+      #: () -> String
+      def bundled_index_html
+        File.join(File.expand_path("../..", __dir__), "vendor", "speedscope", "index.html")
+      end
+
+      #: (String | Pathname) -> String
+      def open_command(profile_path)
+        if File.exist?(bundled_index_html)
+          "#{os_open_command} file://#{bundled_index_html}#localProfilePath=#{profile_path}"
+        else
+          "npx speedscope #{profile_path}"
+        end
+      end
+
+      #: (String | Pathname) -> bool?
+      def open(profile_path)
+        profile_path = profile_path.to_s
+
+        if File.exist?(bundled_index_html)
+          open_with_bundled_speedscope(profile_path)
+        else
+          open_with_npx(profile_path)
+        end
+      end
+
+      private
+
+      #: (String) -> bool?
+      def open_with_npx(profile_path)
+        system("npx", "speedscope", profile_path)
+      end
+
+      # Based on speedscope CLI code (MIT license)
+      # See https://github.com/jlfwong/speedscope/blob/3613918de0dd55a263d0d04f85b0c8c2039c7bee/bin/cli.mjs
+      #: (String) -> bool?
+      def open_with_bundled_speedscope(profile_path)
+        source_buffer = File.binread(profile_path)
+        filename = File.basename(profile_path)
+
+        source_base64 = [source_buffer].pack("m0")
+        js_source = "speedscope.loadFileFromBase64(#{filename.inspect}, #{source_base64.inspect})"
+
+        file_prefix = "speedscope-#{Time.now.to_i}-#{Process.pid}"
+        js_path = File.join(Dir.tmpdir, "#{file_prefix}.js")
+        File.write(js_path, js_source)
+
+        url_to_open = "file://#{File.expand_path(bundled_index_html)}#localProfilePath=#{js_path}"
+
+        # See https://github.com/jlfwong/speedscope/blob/3613918de0dd55a263d0d04f85b0c8c2039c7bee/bin/cli.mjs#L96-L105
+        host_os = RbConfig::CONFIG["host_os"]
+        if host_os =~ /mswin|mingw|cygwin/ || host_os =~ /darwin/
+          html_path = File.join(Dir.tmpdir, "#{file_prefix}.html")
+          File.write(html_path, "<script>window.location=#{url_to_open.inspect}</script>")
+          url_to_open = "file://#{html_path}"
+        end
+
+        system os_open_command, url_to_open
+      end
+
+      #: () -> String
+      def os_open_command
+        case host_os = RbConfig::CONFIG["host_os"]
+        when /mswin|mingw|cygwin/
+          "start"
+        when /darwin/
+          "open"
+        when /linux|bsd/
+          "xdg-open"
+        else
+          raise "Unsupported OS to open browser: #{host_os}"
+        end
+      end
+    end
+  end
+end

data/lib/singed/vernier_report.rb

@@ -0,0 +1,122 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Singed
+  # Converts a Vernier::Result to speedscope's file format, with a profile for each thread:
+  # https://github.com/jlfwong/speedscope/blob/v1.24.0/src/lib/file-format-spec.ts
+  class VernierReport
+    # Vernier keeps sampling threads that are waiting, and categorizes those samples. Topping their
+    # stacks with one of these frames keeps waiting from reading as time spent running Ruby code.
+    CATEGORY_FRAMES = {
+      1 => { name: "(idle)" }, # sleeping, or waiting on I/O or a lock
+      2 => { name: "(waiting for GVL)" }, # ready to run, but another thread holds the GVL
+    }.freeze #: Hash[Integer, Hash[Symbol, String]]
+
+    # Not Vernier::Result: apps' Tapioca evaluates these sigs even when Vernier isn't loaded.
+    #: (untyped) -> void
+    def initialize(result)
+      @result = result
+      @frames = [] #: Array[Hash[Symbol, untyped]]
+      @func_frame_indexes = {} #: Hash[Integer, Integer]
+      @category_frame_indexes = {} #: Hash[Integer, Integer]
+      @stacks = {} #: Hash[[Integer, Integer], Array[Integer]]
+    end
+
+    #: (IO | StringIO) -> void
+    def print_json(io)
+      io.write(JSON.generate(to_h))
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      interval = @result.meta.fetch(:interval)
+      # Threads that never ran while profiling have no samples, so would only add empty profiles.
+      threads = @result.threads.values.select { |thread| thread[:is_start] || thread[:samples].any? }
+      profiles = threads.map { |thread| profile(thread, interval) }
+
+      {
+        "$schema": "https://www.speedscope.app/file-format-schema.json",
+        shared: { frames: @frames },
+        profiles:,
+        # The thread that started profiling is the one that ran the profiled code.
+        activeProfileIndex: threads.index { |thread| thread[:is_start] },
+      }
+    end
+
+    private
+
+    #: (Hash[Symbol, untyped], Integer) -> Hash[Symbol, untyped]
+    def profile(thread, interval)
+      samples = thread[:samples].zip(thread[:sample_categories]).map do |stack_idx, category|
+        stack(stack_idx, category)
+      end
+      # Vernier merges consecutive samples of the same stack into one, counting them in its weight.
+      weights = thread[:weights].map { |weight| weight * interval }
+
+      {
+        type: "sampled",
+        name: utf8(thread[:name]),
+        unit: "microseconds",
+        startValue: 0,
+        endValue: weights.sum,
+        samples:,
+        weights:,
+      }
+    end
+
+    # Vernier links each stack to its parent, but speedscope lists a stack's frames from the root.
+    #: (Integer, Integer) -> Array[Integer]
+    def stack(stack_idx, category)
+      @stacks[[stack_idx, category]] ||= begin
+        frames = [] #: Array[Integer]
+        idx = stack_idx #: Integer?
+        while idx
+          frames << func_frame_index(stack_table.frame_func_idx(stack_table.stack_frame_idx(idx)))
+          idx = stack_table.stack_parent_idx(idx)
+        end
+        frames.reverse!
+        frames << category_frame_index(category) if CATEGORY_FRAMES.key?(category)
+        frames
+      end
+    end
+
+    # One frame per method rather than per line, so each method is a single box in the flamegraph.
+    #: (Integer) -> Integer
+    def func_frame_index(func_idx)
+      @func_frame_indexes[func_idx] ||= begin
+        frame = {
+          name: utf8(stack_table.func_name(func_idx)),
+          file: Singed.filter_line(utf8(stack_table.func_filename(func_idx))),
+        } #: Hash[Symbol, untyped]
+        line = stack_table.func_first_lineno(func_idx)
+        frame[:line] = line if line.positive? # C functions have no line
+        add_frame(frame)
+      end
+    end
+
+    #: (Integer) -> Integer
+    def category_frame_index(category)
+      @category_frame_indexes[category] ||= add_frame(CATEGORY_FRAMES.fetch(category))
+    end
+
+    #: (Hash[Symbol, untyped]) -> Integer
+    def add_frame(frame)
+      @frames << frame
+      @frames.size - 1
+    end
+
+    # JSON needs valid UTF-8. Vernier guesses its stack table's strings are UTF-8, so they may need scrubbing:
+    # https://github.com/jhawthorn/vernier/blob/v1.11.0/ext/vernier/stack_table.cc#L179-L191
+    # It names threads that have no name after Thread#inspect, which is binary.
+    #: (String) -> String
+    def utf8(string)
+      string = string.dup.force_encoding(Encoding::UTF_8) if string.encoding == Encoding::BINARY
+      string.scrub
+    end
+
+    #: () -> untyped
+    def stack_table
+      @result.stack_table
+    end
+  end
+end

data/lib/singed.rb

@@ -1,53 +1,108 @@
+# typed: strict
 # frozen_string_literal: true
 
 require "json"
 require "stackprof"
 
 module Singed
-  extend self
+  # Methods defined with plain `def` below are both module methods (Singed.start) and public
+  # instance methods of Singed, which is how the gem has shipped since its first release.
+  # `class << self` would remove those instance methods for anyone who includes or extends Singed.
+  extend self # rubocop:disable Style/ModuleFunction
 
   # Where should flamegraphs be saved?
+  #: (String | Pathname | nil) -> void
   def output_directory=(directory)
-    @output_directory = Pathname.new(directory)
+    @output_directory = directory && Pathname.new(directory) #: Pathname?
   end
 
+  #: () -> Pathname?
   def self.output_directory
     @output_directory
   end
 
+  #: (bool?) -> void
   def enabled=(enabled)
-    @enabled = enabled
+    @enabled = enabled #: bool?
   end
 
+  #: () -> bool?
   def enabled?
     return @enabled if defined?(@enabled)
 
     @enabled = true
   end
 
+  # Which profiler records flamegraphs that aren't given one: :stackprof or :vernier.
+  #: (Symbol) -> void
+  def profiler=(profiler)
+    Flamegraph.load_profiler(profiler)
+    @profiler = profiler #: Symbol?
+  end
+
+  #: () -> Symbol
+  def profiler
+    @profiler || :stackprof
+  end
+
+  # Not ActiveSupport::BacktraceCleaner: apps' Tapioca evaluates these sigs even when ActiveSupport isn't loaded.
+  #: (untyped) -> void
   def backtrace_cleaner=(backtrace_cleaner)
-    @backtrace_cleaner = backtrace_cleaner
+    @backtrace_cleaner = backtrace_cleaner #: untyped
   end
 
+  #: () -> untyped
   def backtrace_cleaner
     @backtrace_cleaner
   end
 
+  #: (String) -> bool
   def silence_line?(line)
-    return backtrace_cleaner.silence_line?(line) if backtrace_cleaner
+    cleaner = backtrace_cleaner
+    return cleaner.silence_line?(line) if cleaner
 
     false
   end
 
+  #: (String) -> String
   def filter_line(line)
-    return backtrace_cleaner.filter_line(line) if backtrace_cleaner
+    cleaner = backtrace_cleaner
+    return cleaner.filter_line(line) if cleaner
 
     line
   end
 
+  #: (?String?, ?ignore_gc: bool, ?interval: Integer, ?profiler: Symbol?) -> Flamegraph?
+  def start(label = nil, ignore_gc: false, interval: 1000, profiler: nil)
+    return unless enabled?
+    return if profiling?
+
+    @current_flamegraph = Flamegraph.new(label:, ignore_gc:, interval:, profiler:)
+    @current_flamegraph.tap(&:start)
+  end
+
+  #: () -> Flamegraph?
+  def stop
+    return nil unless profiling?
+
+    # profiling? is only true while @current_flamegraph is set.
+    flamegraph = @current_flamegraph #: as !nil
+    @current_flamegraph = nil #: Flamegraph?
+    flamegraph.stop
+    flamegraph.save
+    flamegraph
+  end
+
+  #: () -> bool
+  def profiling?
+    @current_flamegraph&.started? || false
+  end
+
   autoload :Flamegraph, "singed/flamegraph"
   autoload :Report, "singed/report"
   autoload :RackMiddleware, "singed/rack_middleware"
+  autoload :Speedscope, "singed/speedscope"
+  autoload :VernierReport, "singed/vernier_report"
 end
 
 require "singed/kernel_ext"

data/singed.gemspec

@@ -3,26 +3,23 @@
 Gem::Specification.new do |spec|
   spec.name = "singed"
 
-  spec.version = "0.3.0"
+  spec.version = "0.4.0"
   spec.license = "MIT"
-  spec.authors = ["Josh Nichols"]
-  spec.email = ["josh.nichols@gusto.com"]
+  spec.authors = ['Gusto Engineers']
+  spec.email = ['dev@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.required_ruby_version = ">= 3.3"
   spec.homepage = "https://github.com/rubyatscale/singed"
   spec.metadata = {
     "source_code_uri" => "https://github.com/rubyatscale/singed",
     "bug_tracker_uri" => "https://github.com/rubyatscale/singed/issues",
-    "homepage_uri" => "https://github.com/rubyatscale/singed"
+    "homepage_uri" => "https://github.com/rubyatscale/singed",
   }
 
-  spec.files = Dir["README.md", "*.gemspec", "lib/**/*", "exe/**/*"]
+  spec.files = Dir["README.md", "*.gemspec", "lib/**/*", "exe/**/*", "vendor/speedscope/**/*"]
   spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.executables = spec.files.grep(%r(\Aexe/)) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_dependency "stackprof", ">= 0.2.13"
-
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec"
 end

data/vendor/speedscope/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Jamie Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/vendor/speedscope/README

@@ -0,0 +1,2 @@
+This is a self-contained release of https://github.com/jlfwong/speedscope.
+To use it, open index.html in Chrome or Firefox.

data/vendor/speedscope/favicon-16x16-V2DMIAZS.js

@@ -0,0 +1,2 @@
+(()=>{var D="./favicon-16x16-VSI62OPJ.png";})();
+//# sourceMappingURL=favicon-16x16-V2DMIAZS.js.map

data/vendor/speedscope/favicon-32x32-THY3JDJL.js

@@ -0,0 +1,2 @@
+(()=>{var T="./favicon-32x32-3EB2YCUY.png";})();
+//# sourceMappingURL=favicon-32x32-THY3JDJL.js.map

data/vendor/speedscope/favicon-M34RF7BI.js

@@ -0,0 +1,2 @@
+(()=>{var m="./favicon-FOKUP5Y5.ico";})();
+//# sourceMappingURL=favicon-M34RF7BI.js.map