singed 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ae5015ceb06bdcb4a4ee0149083fa5449bd6db4c508ab552a77f07a24c540aa
-  data.tar.gz: 533ff18bba4acbc7b19ee0c7875d5ae1beb97623eddab13c64b7eae5fae267c9
+  metadata.gz: edd7e0459f79298b925de483b4b6a1363f2fa2a071b93d6a954ae939ff65ea3c
+  data.tar.gz: 99c4141ad809f9a54dfd477ab8097c87fdb41531e1b3db24b658c1759ca0ca3d
 SHA512:
-  metadata.gz: 61e8d7689b0a1e23cc81b75a892910b53641bf3bdc8ace5d8956a62962941ec8ede1bf6dd30b2f1bd3d56d4faa5b37d9b9855dafa006e864cba36e07af9f9c52
-  data.tar.gz: 3b482b7351174cfd923be2df3fe8d04678cd2140a99141b4c0fb0c0d72cd5ad3736ce5b98b696d192b4575b7c7744df52a09981020542967f90783e11324e8cd
+  metadata.gz: 36cd5b1b55aab972df638d1490c88f01df41aad90759cde60a54beb3ab4f164d0dbc13f7441d9a920027af6870dcc6af4493fa7ecc0374b2b8c26709dc78c04d
+  data.tar.gz: 2a65c9be211f547d0c0da221bb9e523f15c1d9530bb60dd3dc190993d7438962d3c9bd2fe783673c8d3eac39816bcddfc9a8ac975d16712b83219b989ca4ab41

data/README.md

@@ -1,6 +1,6 @@
 # Singed
 
-Singed makes it easy to get a flamegraph anywhere in your code base. It wraps profiling your code with [stackprof](https://github.com/tmm1/stackprof) or [rbspy](https://github.com/rbspy/rbspy), and then launching [speedscope](https://github.com/jlfwong/speedscope) to view it.
+Singed makes it easy to get a flamegraph anywhere in your code base. It wraps profiling your code with [stackprof](https://github.com/tmm1/stackprof), [vernier](https://github.com/jhawthorn/vernier) or [rbspy](https://github.com/rbspy/rbspy), and then launching [speedscope](https://github.com/jlfwong/speedscope) to view it.
 
 ## Installation
 
@@ -47,6 +47,59 @@ flamegraph(open: false) {
 }
 ```
 
+### Explicit start and stop
+
+You can also start and stop the flamegraph explicitly:
+
+```ruby
+# config/boot.rb
+require "singed"
+Singed.output_directory ||= Dir.pwd + "/tmp/speedscope"
+Singed.start
+# Let some code to run here...
+# and then stop the flamegraph with e.g. rails runner 'Singed.stop'
+flamegraph = Singed.stop
+# The flamegraph is saved to the output directory
+# Open it with your browser:
+flamegraph.open
+```
+
+Note that `Singed.start` can't be run multiple times in parallel, instantiate multiple `Singed::Flamegraph` objects instead and call `start` on them.
+
+### Vernier
+
+Singed profiles with stackprof by default. [Vernier](https://github.com/jhawthorn/vernier) profiles each thread separately instead, so a flamegraph from a multi-threaded app like Puma or Sidekiq isn't a mix of what all its threads were doing. Singed doesn't depend on vernier, so add it (1.5 or newer) to your Gemfile:
+
+```ruby
+gem "vernier"
+```
+
+Then ask for it when capturing a flamegraph. `Singed.start` and controllers' `flamegraph` take `profiler:` too:
+
+```ruby
+flamegraph(profiler: :vernier) {
+  # your code here
+}
+```
+
+Or make it the default, which the RSpec, controller, Rack and Sidekiq integrations below then use as well:
+
+```ruby
+Singed.profiler = :vernier
+```
+
+That loads vernier straight away, so a missing or outdated gem fails at boot. If vernier is only in some of your Gemfile's groups, set this only in the environments that load them, e.g. in `config/environments/development.rb`.
+
+speedscope then gets a profile per thread, and opens on the thread that ran your code. Pick another thread from its title bar, or step through them with `n` and `p`. Vernier keeps sampling threads that are waiting, so their stacks end in `(idle)` while sleeping or waiting on I/O or a lock, and in `(waiting for GVL)` while another thread holds the GVL.
+
+Vernier doesn't sample a thread while it's running garbage collection, so `ignore_gc` makes no difference with it. The `singed` command line always uses rbspy.
+
+The flamegraph's `profile` is Vernier's own result, which you can also save for [vernier.prof](https://vernier.prof) to show GVL and GC activity alongside the flamegraph:
+
+```ruby
+Singed.stop.profile.write(out: "tmp/profile.vernier.json.gz")
+```
+
 ### RSpec
 
 If you are using RSpec, you can use the `flamegraph` metadata to capture it for you.
@@ -78,6 +131,16 @@ end
 
 This won't catch the entire request though, just once it's been routed to controller and a response has been served (ie no middleware).
 
+If Sorbet checks the controller (`# typed: true` or stricter), also include `Singed::ControllerExt` in it. The Railtie already includes it into `ActionController::Base` at runtime, but Sorbet can't see that, so it would check `flamegraph :show` against the block form of `flamegraph` instead:
+
+```ruby
+class EmployeesController < ApplicationController
+  include Singed::ControllerExt
+
+  flamegraph :show
+end
+```
+
 ### 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:
@@ -90,6 +153,38 @@ PROTIP: use Chrome Developer Tools to record network activity, and copy requests
 
 This can also be enabled to always run by setting `SINGED_MIDDLEWARE_ALWAYS_CAPTURE=1`  in the environment.
 
+### Sidekiq
+
+If you are using Sidekiq, you can use the `Singed::Sidekiq::ServerMiddleware` to capture flamegraphs for you.
+
+```ruby
+require "singed/sidekiq"
+
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add Singed::Sidekiq::ServerMiddleware
+  end
+end
+```
+
+To capture flamegraphs for all jobs, you can set the `SINGED_MIDDLEWARE_ALWAYS_CAPTURE` environment variable to `true` the same way as the Rack middleware.
+
+To capture flamegraphs for a specific job, you can set the `x-singed` key in the job payload to `true`.
+
+```ruby
+MyJob.set("x-singed" => true).perform_async
+```
+
+Or define a `capture_flamegraph?` method on the job class:
+
+```ruby
+class MyJob
+  def self.capture_flamegraph?(payload)
+    payload["flamegraph"]
+  end
+end
+```
+
 ### Command Line
 
 There is a `singed` command line you can use that will record a flamegraph from the entirety of a command run:
@@ -101,14 +196,19 @@ $ bundle exec singed -- bin/rails runner 'Model.all.to_a'
 
 The flamegraph is opened afterwards.
 
+To profile a command that runs until it's stopped, like a server, stop it with Ctrl-C. Or, when `singed` runs in the background, such as from a script, stop it with `kill`'s default SIGTERM. Either way, rbspy stops the command and writes the flamegraph, which `singed` then opens. `singed` ignores a SIGINT sent to it alone, such as by `kill -INT`, because Ctrl-C's reaches rbspy directly.
+
+Send SIGTERM to `singed` alone, though, not to its whole process group as `kill -- -<pgid>` and `timeout` without `--foreground` do: sudo passes a SIGTERM straight on to rbspy, which then exits without writing the flamegraph. And rbspy kills only the command itself, so processes the command started may be left running.
+
 
 ## 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.
+The `open` command is expected to be available.
 
 ## Alternatives
 
 - using [rbspy](https://rbspy.github.io/) directly
 - using [stackprof](https://github.com/tmm1/stackprof) (a dependency of singed) directly
+- using [vernier](https://github.com/jhawthorn/vernier) directly

data/exe/singed

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "singed/cli"
 if Singed::CLI.chdir_rails_root

data/lib/singed/backtrace_cleaner_ext.rb

@@ -1,5 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
 module ActiveSupport
   class BacktraceCleaner
+    #: (String) -> String
     def filter_line(line)
       filtered_line = line
       @filters.each do |f|
@@ -9,6 +13,7 @@ module ActiveSupport
       filtered_line
     end
 
+    #: (String) -> bool
     def silence_line?(line)
       @silencers.any? { |s| s.call(line) }
     end

data/lib/singed/cli.rb

@@ -1,30 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
 require "shellwords"
 require "tmpdir"
 require "optionparser"
-require "pathname"
 
 # 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
+    #: Array[String]
+    attr_accessor :argv
+
+    #: Pathname?
+    attr_accessor :filename
 
+    #: OptionParser
+    attr_accessor :opts
+
+    #: (Array[String]) -> void
     def initialize(argv)
       @argv = argv
-      @opts = OptionParser.new
+      @opts = OptionParser.new #: OptionParser
+      @interrupted = false #: bool
 
       parse_argv!
     end
 
+    #: () -> void
     def parse_argv!
       opts.banner = "Usage: singed [options] <command>"
 
       opts.on("-h", "--help", "Show this message") do
-        @show_help = true
+        @show_help = true #: bool?
       end
 
       opts.on("-o", "--output-directory DIRECTORY", "Directory to write flamegraph to") do |directory|
-        @output_directory = directory
+        @output_directory = directory #: String?
+      end
+
+      opts.on("-r", "--rate RATE", Integer, "Sample rate for rbspy") do |rate|
+        @rate = rate #: Integer?
       end
 
       opts.order(@argv) do |arg|
@@ -34,7 +50,7 @@ module Singed
 
       if @argv.empty?
         @show_help = true
-        @error_message = "missing command to profile"
+        @error_message = "missing command to profile" #: (String | OptionParser::InvalidOption)?
         return
       end
 
@@ -48,6 +64,7 @@ module Singed
       end
     end
 
+    #: () -> void
     def run
       require "singed"
 
@@ -65,20 +82,25 @@ module Singed
 
       Singed.output_directory = @output_directory if @output_directory
       Singed.output_directory ||= Dir.tmpdir
-      FileUtils.mkdir_p Singed.output_directory
+      # The ||= above has just set output_directory if it was unset.
+      FileUtils.mkdir_p(
+        Singed.output_directory #: as !nil
+      )
       @filename = Singed::Flamegraph.generate_filename(label: "cli")
 
+      # nil values are for flags. rbspy uses its default rate unless one was given.
       options = {
         format: "speedscope",
         file: filename.to_s,
-        silent: nil
+        silent: nil,
       }
+      options[:rate] = @rate if @rate
 
       rbspy_args = [
         "record",
         *options.map { |k, v| ["--#{k}", v].compact }.flatten,
         "--",
-        *argv
+        *argv,
       ]
 
       loop do
@@ -88,9 +110,9 @@ module Singed
         prompt_password
       end
 
-      rbspy = lambda do
+      rbspy = -> 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"}
+        sudo ["rbspy", *rbspy_args], reason: "Singed needs to run as root, but will drop permissions back to your user.", env: { "DISABLE_SPRING" => "1" }
       end
 
       if defined?(Bundler)
@@ -101,7 +123,8 @@ module Singed
         rbspy.call
       end
 
-      unless filename.exist?
+      # @filename rather than the nilable filename reader: Sorbet knows it holds a Pathname by now.
+      unless @filename.exist?
         puts "#{filename} doesn't exist. Maybe rbspy had a failure capturing it? Check the scrollback."
         exit 1
       end
@@ -112,32 +135,38 @@ module Singed
       end
 
       # clean the report, similar to how Singed::Report does
-      json = JSON.parse(filename.read)
+      json = JSON.parse(@filename.read)
       json["shared"]["frames"].each do |frame|
         frame["file"] = Singed.filter_line(frame["file"])
       end
-      filename.write(JSON.dump(json))
+      @filename.write(JSON.dump(json))
 
-      flamegraph = Singed::Flamegraph.new(filename: filename)
+      flamegraph = Singed::Flamegraph.new(filename:)
       flamegraph.open
     end
 
+    #: () -> bool
     def password_needed?
       !system("sudo --non-interactive true >/dev/null 2>&1")
     end
 
+    #: () -> bool?
     def prompt_password
       system("sudo true")
     end
 
+    #: () -> bool
     def adjust_ownership!
       sudo ["chown", ENV["USER"], filename], reason: "Adjusting ownership of #{filename}, but need root."
     end
 
+    #: () -> bool?
     def show_help?
       @show_help
     end
 
+    # Never nil or false: a command that fails raises instead.
+    #: (Array[String | Integer | Pathname | nil], reason: String, ?env: Hash[String, String]) -> bool
     def sudo(system_args, reason:, env: {})
       loop do
         break unless password_needed?
@@ -149,14 +178,54 @@ module Singed
       sudo_args = [
         "sudo",
         "--preserve-env",
-        *system_args.map(&:to_s)
+        *system_args.map(&:to_s),
       ]
 
       puts "$ #{Shellwords.join(sudo_args)}"
 
-      system(env, *sudo_args, exception: true)
+      # Sorbet can't check a splat of an array of unknown length: https://srb.help/7019
+      process = Process #: as untyped
+      pid = process.spawn(env, *sudo_args) #: as Integer
+      status = wait_passing_on_signals(pid)
+      raise "#{Shellwords.join(sudo_args)} failed (#{status})" unless status.success?
+
+      true
+    end
+
+    # Kernel#system would leave the command running when singed is killed. Instead, the first SIGTERM is
+    # passed on as SIGINT, which sudo relays and is the only signal rbspy stops cleanly on, killing the
+    # command and writing the flamegraph. Nothing more is passed on, because rbspy exits without writing
+    # anything when interrupted twice, and Ctrl-C at a terminal already reaches it directly. Later SIGTERMs
+    # are ignored until singed exits, so they can't stop it opening the flamegraph either.
+    # https://github.com/rbspy/rbspy/blob/v0.53.0/src/main.rs#L164-L211
+    #: (Integer) -> Process::Status
+    def wait_passing_on_signals(pid)
+      previous_int = trap("INT", "IGNORE")
+      previous_term = trap("TERM") do
+        @interrupted ||= interrupt(pid)
+      end
+
+      # Process.wait2 only returns nil when told not to block.
+      waited = Process.wait2(pid) #: as !nil
+      waited.last
+    ensure
+      # trap returns nil for a handler installed outside Ruby, and restoring nil would ignore the signal.
+      trap("INT", previous_int || "DEFAULT")
+      trap("TERM", previous_term || "DEFAULT") unless @interrupted
+    end
+
+    # sudo before 1.9.13 doesn't relay a signal sent from its own process group, which singed shares to keep
+    # sudo in the terminal's foreground, so a kill in a group of its own sends it. kill fails while sudo
+    # briefly runs entirely as root, as it does starting up, and then a later SIGTERM tries again.
+    # https://github.com/sudo-project/sudo/commit/36742deec3041413af9b293706a64530321b96b5
+    #: (Integer) -> bool
+    def interrupt(pid)
+      kill = Process.spawn("kill", "-INT", pid.to_s, pgroup: true, err: File::NULL)
+      waited = Process.wait2(kill) #: as !nil
+      !!waited.last.success?
     end
 
+    #: () -> String?
     def self.chdir_rails_root
       original_cwd = Dir.pwd
 

data/lib/singed/controller_ext.rb

@@ -1,14 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support/concern"
+
 module Singed
   module ControllerExt
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
+    extend ActiveSupport::Concern
 
+    # Concern extends the including controller class with this module; controllers define around_action.
+    # @requires_ancestor: AbstractController::Callbacks::ClassMethods
     module ClassMethods
       # Define an around_action to generate flamegraph for a controller action.
-      def flamegraph(target_action, ignore_gc: false, interval: 1000)
+      #: (Symbol | String | Array[Symbol | String], ?ignore_gc: bool, ?interval: Integer, ?profiler: Symbol?) -> void
+      def flamegraph(target_action, ignore_gc: false, interval: 1000, profiler: nil)
         around_action(only: target_action) do |controller, action|
-          controller.flamegraph(ignore_gc: ignore_gc, interval: interval, &action)
+          controller.flamegraph(ignore_gc:, interval:, profiler:, &action)
         end
       end
     end

data/lib/singed/flamegraph.rb

@@ -1,8 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
 module Singed
   class Flamegraph
-    attr_accessor :profile, :filename
+    PROFILERS = [:stackprof, :vernier].freeze
+    # The first with Vernier::Result#stack_table.
+    MINIMUM_VERNIER_VERSION = "1.5"
+
+    # The StackProf.results hash, whose values vary by key, or a Vernier::Result when profiling with Vernier.
+    # Not typed as Vernier::Result: apps' Tapioca evaluates this sig even when Vernier isn't loaded.
+    #: untyped
+    attr_accessor :profile
+
+    #: Pathname
+    attr_accessor :filename
+
+    # nil when wrapping an existing file.
+    #: Symbol?
+    attr_reader :profiler
 
-    def initialize(label: nil, ignore_gc: false, interval: 1000, filename: nil)
+    #: (?label: String?, ?ignore_gc: bool, ?interval: Integer, ?profiler: Symbol?, ?filename: Pathname?) -> void
+    def initialize(label: nil, ignore_gc: false, interval: 1000, profiler: nil, filename: nil)
       # it's been created elsewhere, ie rbspy
       if filename
         if ignore_gc
@@ -13,54 +31,134 @@ module Singed
           raise ArgumentError, "label not supported when given an existing file"
         end
 
-        @filename = filename
+        if profiler
+          raise ArgumentError, "profiler not supported when given an existing file"
+        end
+
+        @filename = filename #: Pathname
       else
-        @ignore_gc = ignore_gc
-        @interval = interval
-        @time = Time.now # rubocop:disable Rails/TimeZone
-        @filename = self.class.generate_filename(label: label, time: @time)
+        profiler ||= Singed.profiler
+        self.class.load_profiler(profiler)
+
+        # Nilable because they stay unset when wrapping an existing file, and #start still reads them.
+        @profiler = profiler #: Symbol?
+        @ignore_gc = ignore_gc #: bool?
+        @interval = interval #: Integer?
+        @time = Time.now #: Time
+        @filename = self.class.generate_filename(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] () { () -> Result } -> Result
+    def record(&_block)
+      start
+      yield
+    ensure
+      stop
+    end
 
-      result = nil
-      @profile = StackProf.run(mode: :wall, raw: true, ignore_gc: @ignore_gc, interval: @interval) do
-        result = yield
+    #: () -> bool
+    def start
+      return false unless Singed.enabled?
+      return false if filename.exist? # file existing means its been captured already
+      return false if started?
+
+      if vernier?
+        # A collector per flamegraph, rather than Vernier.start_profile, which raises if a profile is already running.
+        # There's no ignore_gc to pass: Vernier doesn't sample a thread while it's running GC.
+        @collector = Vernier::Collector.new(:wall, interval: @interval) #: untyped
+        @collector.start
+      else
+        StackProf.start(mode: :wall, raw: true, ignore_gc: @ignore_gc, interval: @interval)
+      end
+      @started = true
+    end
+
+    #: () -> untyped
+    def stop
+      return nil unless started?
+
+      @started = false #: bool?
+      if vernier?
+        @profile = @collector.stop
+      else
+        StackProf.stop
+        @profile = StackProf.results
       end
-      result
     end
 
+    #: () -> bool
+    def started?
+      !!@started
+    end
+
+    #: () -> void
     def save
       if filename.exist?
         raise ArgumentError, "File #{filename} already exists"
       end
 
-      report = Singed::Report.new(@profile)
-      report.filter!
+      if vernier?
+        report = Singed::VernierReport.new(@profile)
+      else
+        report = Singed::Report.new(@profile)
+        report.filter!
+      end
       filename.dirname.mkpath
       filename.open("w") { |f| report.print_json(f) }
     end
 
+    #: () -> bool?
     def open
-      system open_command
+      Singed::Speedscope.open(@filename)
     end
 
+    #: () -> String
     def open_command
-      @open_command ||= "npx speedscope #{@filename}"
+      Singed::Speedscope.open_command(@filename)
     end
 
-    def self.generate_filename(label: nil, time: Time.now) # rubocop:disable Rails/TimeZone
+    #: (?label: String?, ?time: Time) -> Pathname
+    def self.generate_filename(label: nil, time: Time.now)
       formatted_time = time.strftime("%Y%m%d%H%M%S-%6N")
       basename_parts = ["speedscope", label, formatted_time].compact
 
-      file = Singed.output_directory.join("#{basename_parts.join("-")}.json")
+      # Callers must set output_directory first (the Railtie and CLI do); unset, this raises NoMethodError.
+      file = Singed.output_directory #: as !nil
+        .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
+
+    # Raises unless Singed supports the profiler. Requires vernier, which Singed doesn't depend on, when it's the one asked for.
+    #: (Symbol) -> void
+    def self.load_profiler(profiler)
+      unless PROFILERS.include?(profiler)
+        raise ArgumentError, "Unsupported profiler #{profiler.inspect}, expected one of #{PROFILERS.inspect}"
+      end
+      return unless profiler == :vernier
+
+      begin
+        require "vernier"
+      rescue LoadError => e
+        # Other paths mean vernier is installed but broken, e.g. its native extension didn't load.
+        raise unless e.path == "vernier"
+
+        raise LoadError, "Profiling with vernier needs the vernier gem in your bundle (#{e.message})"
+      end
+
+      if Gem::Version.new(Vernier::VERSION) < Gem::Version.new(MINIMUM_VERNIER_VERSION)
+        raise LoadError, "Profiling with vernier needs vernier #{MINIMUM_VERNIER_VERSION} or newer, not #{Vernier::VERSION}"
+      end
+    end
+
+    private
+
+    #: () -> bool
+    def vernier?
+      @profiler == :vernier
+    end
   end
 end

data/lib/singed/kernel_ext.rb

@@ -1,14 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
 module Kernel
-  def flamegraph(label = nil, open: true, ignore_gc: false, interval: 1000, io: $stdout, &)
-    fg = Singed::Flamegraph.new(label: label, ignore_gc: ignore_gc, interval: interval)
-    result = fg.record(&)
+  #: [Result] (
+  #|   ?String?,
+  #|   ?open: bool,
+  #|   ?ignore_gc: bool,
+  #|   ?interval: Integer,
+  #|   ?profiler: Symbol?,
+  #|   ?io: IO | StringIO
+  #| ) { () -> Result } -> Result
+  def flamegraph(label = nil, open: true, ignore_gc: false, interval: 1000, profiler: nil, io: $stdout, &block) # rubocop:disable Metrics/ParameterLists -- all optional keywords
+    fg = Singed::Flamegraph.new(label:, ignore_gc:, interval:, profiler:)
+    result = fg.record(&block)
     fg.save
 
     # avoid a dep on a colorizing gem by doing this ourselves
     bright_red = "\e[91m"
     none = "\e[0m"
     if open
-      # use npx, so we don't have to add it as a dependency
       io.puts "🔥📈 #{bright_red}Captured flamegraph, opening with#{none}: #{fg.open_command}"
       fg.open
     else

data/lib/singed/rack_middleware.rb

@@ -1,35 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
 # Rack Middleware
 
 require "rack"
 
 module Singed
   class RackMiddleware
+    # Rack apps are duck-typed: any object that responds to call(env).
+    #: (untyped) -> void
     def initialize(app)
       @app = app
     end
 
+    # Returns the wrapped app's Rack response unchanged, so it is as untyped as the app.
+    #: (Hash[String, untyped]) -> untyped
     def call(env)
-      status, headers, body = if capture_flamegraph?(env)
-        flamegraph do
-          @app.call(env)
-        end
+      if capture_flamegraph?(env)
+        flamegraph { @app.call(env) }
       else
         @app.call(env)
       end
-
-      [status, headers, body]
     end
 
+    #: (Hash[String, untyped]) -> bool
     def capture_flamegraph?(env)
       self.class.always_capture? || env["HTTP_X_SINGED"] == "true"
     end
 
     TRUTHY_STRINGS = ["true", "1", "yes"].freeze
 
+    # bool?, not bool: Sorbet can't tell that defined?(@always_capture) means it holds a bool.
+    #: () -> bool?
     def self.always_capture?
       return @always_capture if defined?(@always_capture)
 
-      @always_capture = TRUTHY_STRINGS.include?(ENV.fetch("SINGED_MIDDLEWARE_ALWAYS_CAPTURE", "false"))
+      @always_capture = TRUTHY_STRINGS.include?(ENV.fetch("SINGED_MIDDLEWARE_ALWAYS_CAPTURE", "false")) #: bool?
     end
   end
 end