Methods for explicit start and stop flamegraph recording (#52)

* Methods for explicit start and stop

* add some tests

* Code review fixes

Author: Envek

README.md

@@ -47,6 +47,25 @@ 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.
+
 ### RSpec
 
 If you are using RSpec, you can use the `flamegraph` metadata to capture it for you.

lib/singed.rb

@@ -9,7 +9,7 @@ module Singed
 
   # Where should flamegraphs be saved?
   def output_directory=(directory)
-    @output_directory = Pathname.new(directory)
+    @output_directory = directory && Pathname.new(directory)
   end
 
   def self.output_directory
@@ -46,6 +46,28 @@ def filter_line(line)
     line
   end
 
+  def start(label = nil, ignore_gc: false, interval: 1000)
+    return unless enabled?
+    return if profiling?
+
+    @current_flamegraph = Flamegraph.new(label: label, ignore_gc: ignore_gc, interval: interval)
+    @current_flamegraph.tap(&:start)
+  end
+
+  def stop
+    return nil unless profiling?
+
+    flamegraph = @current_flamegraph
+    @current_flamegraph = nil
+    flamegraph.stop
+    flamegraph.save
+    flamegraph
+  end
+
+  def profiling?
+    @current_flamegraph&.started? || false
+  end
+
   autoload :Flamegraph, "singed/flamegraph"
   autoload :Report, "singed/report"
   autoload :RackMiddleware, "singed/rack_middleware"

lib/singed/flamegraph.rb

@@ -23,14 +23,31 @@ def initialize(label: nil, ignore_gc: false, interval: 1000, filename: nil)
     end
 
     def record
-      return yield unless Singed.enabled?
-      return yield if filename.exist? # file existing means its been captured already
+      start
+      yield
+    ensure
+      stop
+    end
 
-      result = nil
-      @profile = StackProf.run(mode: :wall, raw: true, ignore_gc: @ignore_gc, interval: @interval) do
-        result = yield
-      end
-      result
+    def start
+      return false unless Singed.enabled?
+      return false if filename.exist? # file existing means its been captured already
+      return false if started?
+
+      StackProf.start(mode: :wall, raw: true, ignore_gc: @ignore_gc, interval: @interval)
+      @started = true
+    end
+
+    def stop
+      return nil unless started?
+
+      @started = false
+      StackProf.stop
+      @profile = StackProf.results
+    end
+
+    def started?
+      !!@started
     end
 
     def save

spec/singed_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "pathname"
+
+RSpec.describe Singed do
+  around do |example|
+    original_output_directory = Singed.output_directory
+    Singed.output_directory = Dir.mktmpdir("singed-spec")
+    original_enabled = Singed.enabled?
+    begin
+      example.run
+    ensure
+      Singed.output_directory = original_output_directory
+      Singed.enabled = original_enabled
+      Singed.instance_variable_set(:@current_flamegraph, nil)
+    end
+  end
+
+  describe ".start" do
+    before { Singed.enabled = true }
+
+    it "creates a current flamegraph and starts profiling" do
+      current_flamegraph = Singed.start
+
+      expect(current_flamegraph).to be_a(Singed::Flamegraph)
+      expect(Singed.profiling?).to be true
+      expect(current_flamegraph.started?).to be true
+    end
+
+    it "does nothing when already profiling" do
+      Singed.start
+      expect(Singed.start).to be_nil
+    end
+
+    it "does nothing when disabled" do
+      Singed.enabled = false
+      expect(Singed.start).to be_nil
+      expect(Singed.profiling?).to be_falsey
+    end
+  end
+
+  describe ".stop" do
+    before do
+      Singed.enabled = true
+      Singed.output_directory = Dir.mktmpdir("singed-spec")
+    end
+
+    it "returns nil when not profiling" do
+      expect(Singed.stop).to be_nil
+    end
+
+    it "stops profiling, saves the result file, and returns the flamegraph with profile data" do
+      Singed.start
+      # Run some code to generate profile samples
+      100.times { 2**10 }
+      flamegraph = Singed.stop
+
+      expect(flamegraph).to be_a(Singed::Flamegraph)
+      expect(Singed.profiling?).to be false
+
+      # Profile data is returned (StackProf results hash)
+      expect(flamegraph.profile).to be_a(Hash)
+      expect(flamegraph.profile).to include(:mode, :version, :interval)
+      expect(flamegraph.profile[:mode]).to eq(:wall)
+      expect(flamegraph.profile[:samples]).to be >= 0
+    end
+
+    it "creates the result file on disk" do
+      Singed.start
+      100.times { 2**10 }
+      flamegraph = Singed.stop
+
+      expect(Pathname(flamegraph.filename)).to exist
+    end
+  end
+end