fiber-profiler 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a4ef2a5d3b1f833810953f991fbbe8aac342b9e757c5ebfadfd695d87036558
-  data.tar.gz: '012498a134f5b2c22fad0761090514d577d3ee36143ef568c5e0617b74a46d24'
+  metadata.gz: e3d1446f213526360f5368bfb8a08884033484f4ab868160340709652349c25c
+  data.tar.gz: 844c5319c20f8b0929342978790efe2d1aeb4dd37ae260cd073ff36c82c730fd
 SHA512:
-  metadata.gz: 04c655663d123aa94f15f83d7b6a70ab9d81074fe18fb1d870f358756d19a7e91b4eaac4b0b832ed6c649397bf10e4e41b2342abfec1e7bb8e0c652f98630334
-  data.tar.gz: 3529cf9a591bcfdd81dcf1a07d71401ab07322e475ec7a0b34b1d3d73080595cbc2b81419c1c7d9abe6341d163bcaaf1ac2017aed9e5d0d7af1847d15d704a88
+  metadata.gz: '08e564d3dc9c9abfba57056f3ff5a7e0fce516a5969ee014820ff2dac72b60fd51603c258c21cbee80c46d686f9ca9bbd2376a11b1202635371d0201b8a3b372'
+  data.tar.gz: 88d96fba98c5b9578683ad7f13cb898d70e8da83ce11a3b756b15d29b4cbc29649a61c7ec2d589cb9a1185e9646bee4ed018bbcbb1946defdd2e7163ae951aa8

data/context/capture-mode.md

@@ -0,0 +1,80 @@
+# Capture Mode
+
+This guide explains how to trace fiber execution and analyze call timings with the capture profiler.
+
+Use capture mode when you need to investigate the calls made during a stall. It records call timings for sampled fiber executions and reports after the fiber switches away. For sampled backtraces while a stall is still in progress, see [Watchdog Mode](../watchdog-mode/index).
+
+## Usage
+
+Add `fiber-profiler` to your application's bundle as described in [Getting Started](../getting-started/index), then select capture mode when starting Async or Falcon:
+
+```bash
+FIBER_PROFILER=capture bundle exec falcon serve
+```
+
+Async starts and stops capture automatically. The legacy `FIBER_PROFILER_CAPTURE=true` setting also enables capture when `FIBER_PROFILER` is unset. An explicit `FIBER_PROFILER` value takes precedence.
+
+### Manual Instrumentation
+
+To reproduce a stall without a scheduler, save this as `capture.rb`. It starts a {ruby Fiber::Profiler::Capture} and simulates a blocking operation inside a fiber:
+
+```ruby
+require "fiber/profiler"
+
+profiler = Fiber::Profiler::Capture.new
+
+begin
+	profiler.start
+	
+	# Simulate a blocking operation without a scheduler:
+	Fiber.new(blocking: false) do
+		sleep 0.1
+	end.resume
+ensure
+	profiler.stop
+end
+```
+
+```bash
+bundle exec ruby capture.rb
+```
+
+This example starts the profiler explicitly, so it does not need `FIBER_PROFILER=capture`. The report should include `Kernel#sleep` and its elapsed duration. Start and stop profiling on the same thread.
+
+## Configuration
+
+Set these environment variables before loading `fiber-profiler`; the native extension reads them when it loads:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FIBER_PROFILER_CAPTURE_STALL_THRESHOLD` | `0.01` | Minimum execution duration in seconds to exceed before reporting a stall. |
+| `FIBER_PROFILER_CAPTURE_FILTER_THRESHOLD` | 10% of the stall threshold | Filter calls shorter than this duration in seconds. |
+| `FIBER_PROFILER_CAPTURE_TRACK_CALLS` | `true` | Record call timings. Set to `false` to report stall durations without tracing calls. |
+| `FIBER_PROFILER_CAPTURE_SAMPLE_RATE` | `1.0` | Fraction of eligible fiber executions to sample: `1.0` samples all, `0.1` samples approximately 10%. |
+
+These settings apply to capture mode only. The sample rate controls selection at fiber switches; it is not a time interval between backtrace samples.
+
+For explicit instrumentation, override the defaults with `Fiber::Profiler::Capture.new(stall_threshold: 0.05, filter_threshold: 0.005, track_calls: true, sample_rate: 0.1)`. Pass `output:` to select a writable IO; the default is standard error.
+
+## Reading Reports
+
+When standard error is a terminal, capture prints a readable call log. Redirected output uses one JSON object per stall, including the execution `duration` and a `calls` array. Each retained call includes its source location, class, method, duration, and nesting information.
+
+To collect the example's reports and summarize call timings:
+
+```bash
+bundle exec ruby capture.rb 2> capture.ndjson
+bundle exec bake input --file capture.ndjson fiber:profiler:analyze output
+```
+
+The analyzer aggregates call durations by source location and sorts the summary by total duration. Feed it capture reports; unrelated application output on standard error must be separated from the JSON first. With `track_calls: false`, reports contain no call timings to aggregate.
+
+Call durations can include time spent in nested calls, so adding durations across different locations does not give total application runtime. Short or uninformative calls may be filtered from the report.
+
+## Interpretation and Limits
+
+Capture samples non-blocking fibers and excludes blocking fibers, including the event-loop fiber. It measures wall time between fiber switches, so an ordinary scheduler-aware wait that yields does not count its entire wait time as a stall. A blocking operation that keeps the same fiber executing can count toward a stall.
+
+Reports are emitted when the fiber switches away. An operation that never yields or returns can therefore prevent its capture report from appearing. Use [Watchdog Mode](../watchdog-mode/index) to investigate an ongoing stall when Ruby thread scheduling is still possible.
+
+Call tracing can substantially affect performance. Reduce the sample rate to trace fewer executions, or disable call tracking if you only need stall durations. Use the [Falcon overhead benchmark](https://github.com/socketry/fiber-profiler/tree/main/benchmark/falcon) to compare modes, and measure with your application's Ruby/JIT configuration and workload.

data/context/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide explains how to detect stalls using the fiber profiler.
+This guide explains how to install the fiber profiler and choose a mode for diagnosing event-loop stalls.
 
 ## Installation
 
@@ -10,63 +10,34 @@ Add the gem to your project:
 $ bundle add fiber-profiler
 ```
 
-## Usage
+## Choose a Mode
 
-Instrument your code using the default profiler:
+A fiber that runs for too long without yielding prevents other work on the same event loop from progressing. The profiler offers two ways to investigate it:
 
-```ruby
-#!/usr/bin/env ruby
+| Mode | Use it to | Reports |
+| --- | --- | --- |
+| [Watchdog](../watchdog-mode/index) | Find where a fiber is spending time during an ongoing stall. | Periodically sampled backtraces while the fiber is still executing. |
+| [Capture](../capture-mode/index) | Investigate individual call timings during a fiber's execution. | Traced calls and their durations after the fiber switches away. |
 
-require "fiber/profiler"
+Watchdog avoids method-call tracing and is a useful starting point for observing sustained stalls. Capture provides more detail at a higher instrumentation cost. Both affect the application being measured; see the [Falcon overhead benchmark](https://github.com/socketry/fiber-profiler/tree/main/benchmark/falcon) and measure with your own workload.
 
-profiler = Fiber::Profiler.default
+## Integration with Async and Falcon
 
-profiler&.start
-
-# Your application code:
-Fiber.new do
-	sleep 0.1
-end.resume
-
-profiler&.stop
-```
-
-Running this program will output the following:
+Select the profiling mode when starting your application:
 
 ```bash
-$ FIBER_PROFILER_CAPTURE=true bundle exec ./test.rb
-Fiber stalled for 0.105 seconds
-/Users/samuel/Developer/socketry/fiber-profiler/test.rb:11 in c-call 'Kernel#sleep' (0.105s)
+FIBER_PROFILER=watchdog bundle exec falcon serve
 ```
 
-## Integration with Async
-
-The fiber profiler is optionally supported by `Async`. Simply enable the profiler using `FIBER_PROFILER_CAPTURE=true` to capture and report stalls.
-
-## Default Environment Variables
-
-### `FIBER_PROFILER_CAPTURE`
-
-Set to `true` to enable capturing of stalled fibers.
-
-### `FIBER_PROFILER_CAPTURE_STALL_THRESHOLD`
+With Async, including Falcon, the scheduler starts and stops the selected profiler automatically. Include `fiber-profiler` in your application's bundle; no initializer or per-request instrumentation is needed.
 
-Set the threshold in seconds for reporting a stalled fiber. Default is `0.01`.
+| Setting | Behaviour |
+| --- | --- |
+| `FIBER_PROFILER=watchdog` | Periodically sample stacks during sustained fiber execution. |
+| `FIBER_PROFILER=capture` | Trace calls and report fibers that exceed the capture threshold. |
+| `FIBER_PROFILER=false` | Disable the default profiler, even if the legacy capture flag is enabled. |
+| `FIBER_PROFILER` unset | Preserve the existing `FIBER_PROFILER_CAPTURE=true` behaviour. |
 
-### `FIBER_PROFILER_CAPTURE_TRACK_CALLS`
-
-Set to `true` to track calls within the fiber. Default is `true`. This can be disabled to reduce overhead.
-
-### `FIBER_PROFILER_CAPTURE_SAMPLE_RATE`
-
-Set the sample rate of the profiler as a percentage of all context switches. The default is 1.0 (100%).
-
-## Analyzing Logs
-
-If you collect your logs in a file (e.g. as `ndjson`) you can analyze them using the included `bake` commands:
-
-```bash
-$ bundle exec bake input --file samples.ndjson fiber:profiler:analyze output
-```
+Unknown modes raise `ArgumentError`. Set environment variables before loading the gem: the native capture settings are read when the extension loads. The new mode selector and watchdog settings are read when `Fiber::Profiler.default` is called.
 
-This will aggregate all the call logs and generate a short summary, ordered by duration.
+Each scheduler obtains its own profiler, so schedulers in separate worker processes or threads are monitored independently. After `fork`, inherited profiling is stopped in the child; a new scheduler starts a new profiler normally.

data/context/index.yaml

@@ -8,4 +8,13 @@ metadata:
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to detect stalls using the fiber profiler.
+  description: This guide explains how to install the fiber profiler and choose a
+    mode for diagnosing event-loop stalls.
+- path: watchdog-mode.md
+  title: Watchdog Mode
+  description: This guide explains how to sample ongoing fiber stalls with the watchdog
+    profiler.
+- path: capture-mode.md
+  title: Capture Mode
+  description: This guide explains how to trace fiber execution and analyze call timings
+    with the capture profiler.

data/context/watchdog-mode.md

@@ -0,0 +1,100 @@
+# Watchdog Mode
+
+This guide explains how to sample ongoing fiber stalls with the watchdog profiler.
+
+Use watchdog mode to find where a fiber is spending time while it prevents other fibers from running. It reports during the stall, so you can investigate an operation that has not returned yet. For individual call timings, see [Capture Mode](../capture-mode/index).
+
+## Usage
+
+Add `fiber-profiler` to your application's bundle as described in [Getting Started](../getting-started/index), then select watchdog mode when starting Async or Falcon:
+
+```bash
+FIBER_PROFILER=watchdog bundle exec falcon serve
+```
+
+Async starts and stops the watchdog automatically. Each scheduler gets its own profiler, which binds to the thread when profiling starts.
+
+To reproduce a stall, save this as `stall.rb`:
+
+```ruby
+require "async"
+
+Sync do
+	deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
+	while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+	end
+end
+```
+
+```bash
+FIBER_PROFILER=watchdog bundle exec ruby stall.rb
+```
+
+The reports should point to the busy loop. Replacing the loop with `sleep(2)` allows Async to keep scheduling fibers and should produce no reports.
+
+## How Sampling Works
+
+Watchdog uses a thread-specific `:fiber_switch` tracepoint to track which fiber is executing. A separate Ruby thread periodically captures the monitored thread's backtrace. It does not install method-call tracing hooks or require a heartbeat task.
+
+By default, it samples every 100 ms, retains at most five recent stacks, and reports when the same fiber execution lasts at least 500 ms. A continued stall produces at most one report per additional threshold interval. Returning to the event loop or switching to another fiber resets the sample window. The measured duration covers one uninterrupted fiber execution.
+
+## Configuration
+
+Set these environment variables before starting your application. They are read when the default watchdog is constructed:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FIBER_PROFILER_WATCHDOG_STALL_THRESHOLD` | `0.5` | Minimum execution duration in seconds before reporting, and minimum interval between repeated reports. |
+| `FIBER_PROFILER_WATCHDOG_SAMPLE_INTERVAL` | `0.1` | Delay in seconds between stack samples. |
+
+Both values must be finite and positive. Actual sampling intervals depend on Ruby and operating-system scheduling. Capture-specific settings, including its sample rate, do not configure watchdog mode.
+
+### Manual Instrumentation
+
+When managing fibers directly, construct a {ruby Fiber::Profiler::Watchdog} and stop it in an `ensure` block:
+
+```ruby
+require "fiber/profiler/watchdog"
+
+watchdog = Fiber::Profiler::Watchdog.new(
+	stall_threshold: 0.5,
+	sample_interval: 0.1,
+	max_samples: 5,
+	output: $stderr
+)
+
+begin
+	watchdog.start
+	
+	# Simulate an application fiber blocked on an operation:
+	Fiber.new do
+		sleep 1
+	end.resume
+ensure
+	watchdog.stop
+end
+```
+
+This example starts the profiler explicitly, so it does not need `FIBER_PROFILER=watchdog`. Start and stop profiling on the monitored thread. `max_samples` must be a positive integer; there is no environment variable for it. The output must support writes from the watchdog thread. Stop the profiler before closing its output.
+
+When profiling starts on a blocking event-loop fiber, that fiber is excluded from monitoring, including its normal idle waits. Other fibers, including blocking application fibers, are monitored. When profiling starts inside a non-blocking application fiber, blocking fibers are excluded because the event-loop fiber is not known.
+
+If sampling or reporting raises a `StandardError`, the watchdog disables its tracepoint and stops sampling. It retains the exception in `watchdog.error` and attempts one warning to standard error. Failure to write that warning is also contained. These errors do not escape through `stop` or replace application errors. Call `stop` normally to finish cleanup; a subsequent `start` clears the error and resumes monitoring.
+
+## Reading Reports
+
+Terminal output contains readable stacks. Redirected output uses one JSON object per report:
+
+```bash
+FIBER_PROFILER=watchdog bundle exec ruby stall.rb 2> watchdog.ndjson
+```
+
+Each report contains `mode: "watchdog"`, process/thread/fiber identifiers, elapsed `duration`, and a bounded `samples` array. Each sample contains its elapsed time and `backtrace`. Duration is elapsed wall time since the fiber resumed, and a report is emitted while the fiber is still executing.
+
+Repeated frames identify code worth investigating: optimize expensive work, add cooperative yield points, or offload suitable work to a bounded thread pool. Watchdog reports contain sampled backtraces, so the capture-mode `fiber:profiler:analyze` command does not aggregate them.
+
+## Interpretation and Limits
+
+The watchdog requires Ruby thread scheduling. Native code that holds the GVL without allowing other threads to run can prevent sampling entirely. Short stalls can occur between samples, and normal scheduler/OS delays can extend measured execution time. A report is a diagnostic lead, not proof that every sampled frame is expensive.
+
+Sampling still has overhead. Use the [Falcon overhead benchmark](https://github.com/socketry/fiber-profiler/tree/main/benchmark/falcon) as a starting point for measuring your own application before enabling continuous monitoring.

data/ext/fiber/profiler/capture.c

@@ -184,7 +184,7 @@ static void Fiber_Profiler_Capture_free(void *ptr) {
 	Fiber_Profiler_Stream_free(&capture->stream);
 	Fiber_Profiler_Deque_free(&capture->calls);
 	
-	free(capture);
+	xfree(capture);
 }
 
 static size_t Fiber_Profiler_Capture_memsize(const void *ptr) {
@@ -271,7 +271,9 @@ VALUE Fiber_Profiler_Capture_initialize(int argc, VALUE *argv, VALUE self) {
 	
 	VALUE arguments[5] = {0};
 	VALUE options = Qnil;
-	rb_scan_args(argc, argv, ":", &options);
+	if (argc > 0) {
+		rb_scan_args(argc, argv, ":", &options);
+	}
 	rb_get_kwargs(options, Fiber_Profiler_Capture_initialize_options, 0, 5, arguments);
 	
 	if (arguments[0] != Qundef) {

data/lib/fiber/profiler/capture.rb

@@ -4,44 +4,11 @@
 # Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "native"
-require_relative "fork_handler"
+require_relative "thread_local"
 
 module Fiber::Profiler
-	# Thread-local storage for the active profiler capture.
-	::Thread.attr_accessor :fiber_profiler_capture
-	
-	# Hook into Process._fork to handle fork events automatically.
-	::Process.singleton_class.prepend(ForkHandler)
-	
-	# Private module that wraps start/stop to manage thread-local storage.
-	module ThreadLocalCapture
-		# Start profiling and store the capture in the current thread's thread-local storage.
-		def start
-			result = super
-			
-			if result
-				Thread.current.fiber_profiler_capture = self
-			end
-			
-			return result
-		end
-		
-		# Stop profiling and clear the capture from the current thread's thread-local storage.
-		def stop
-			result = super
-			
-			if result
-				Thread.current.fiber_profiler_capture = nil
-			end
-			
-			return result
-		end
-	end
-	
-	private_constant :ThreadLocalCapture
-	
 	# Represents a running profiler capture.
 	class Capture
-		prepend ThreadLocalCapture
+		prepend ThreadLocalProfiler
 	end
 end

data/lib/fiber/profiler/thread_local.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "fork_handler"
+
+module Fiber::Profiler
+	# Thread-local storage for the active profiler, shared by both implementations.
+	::Thread.attr_accessor :fiber_profiler_capture
+	
+	::Process.singleton_class.prepend(ForkHandler)
+	
+	# Manages the active profiler so it can be stopped after a fork.
+	module ThreadLocalProfiler
+		# Start profiling on the current thread.
+		def start
+			result = super
+			Thread.current.fiber_profiler_capture = self if result
+			result
+		end
+		
+		# Stop profiling and clear the current thread's reference.
+		def stop
+			super
+		ensure
+			if Thread.current.fiber_profiler_capture.equal?(self)
+				Thread.current.fiber_profiler_capture = nil
+			end
+		end
+	end
+	
+	private_constant :ThreadLocalProfiler
+end

data/lib/fiber/profiler/version.rb

@@ -7,6 +7,6 @@
 class Fiber
 	# @namespace
 	module Profiler
-		VERSION = "0.6.1"
+		VERSION = "0.7.1"
 	end
 end

data/lib/fiber/profiler/watchdog.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "version"
+require_relative "thread_local"
+require "json"
+
+module Fiber::Profiler
+	# Samples stacks while a fiber runs without switching back to the event loop.
+	class Watchdog
+		prepend ThreadLocalProfiler
+		
+		# Build a watchdog using environment configuration.
+		# @parameter env [Hash] The environment to read configuration from.
+		# @returns [Watchdog] The configured watchdog.
+		def self.default(env = ENV)
+			new(
+				stall_threshold: Float(env.fetch("FIBER_PROFILER_WATCHDOG_STALL_THRESHOLD", "0.5")),
+				sample_interval: Float(env.fetch("FIBER_PROFILER_WATCHDOG_SAMPLE_INTERVAL", "0.1"))
+			)
+		end
+		
+		# Initialize a watchdog. Monitoring begins when {start} is called.
+		# @parameter stall_threshold [Float] Seconds without a fiber switch before reporting, and the minimum interval between reports for the same execution.
+		# @parameter sample_interval [Float] Seconds between stack samples.
+		# @parameter max_samples [Integer] Maximum number of recent stacks retained per execution.
+		# @parameter output [IO] The destination for stall reports.
+		def initialize(stall_threshold: 0.5, sample_interval: 0.1, max_samples: 5, output: $stderr)
+			@stall_threshold = Float(stall_threshold)
+			@sample_interval = Float(sample_interval)
+			
+			unless @stall_threshold.finite? && @stall_threshold.positive? && @sample_interval.finite? && @sample_interval.positive?
+				raise ArgumentError, "Watchdog intervals must be finite and positive"
+			end
+			unless max_samples.is_a?(Integer) && max_samples.positive?
+				raise ArgumentError, "max_samples must be a positive integer"
+			end
+			
+			@max_samples = max_samples
+			@output = output
+			@running = false
+			@stalls = 0
+			@error = nil
+		end
+		
+		# @attribute [Float] The minimum execution duration before reporting a stall.
+		attr_reader :stall_threshold
+		
+		# @attribute [Float] The delay between samples.
+		attr_reader :sample_interval
+		
+		# @attribute [Integer] The number of reports written.
+		attr_reader :stalls
+		
+		# @attribute [StandardError | Nil] The sampling or reporting failure, retained until monitoring starts again.
+		attr_reader :error
+		
+		# Start monitoring application fibers on the calling thread.
+		# @returns [Watchdog | false] Self, or false if already running.
+		def start
+			return false if @running
+			
+			@thread = Thread.current
+			@pid = Process.pid
+			@mutex = Mutex.new
+			@condition = ConditionVariable.new
+			@running = true
+			@execution = nil
+			@error = nil
+			
+			# When started on the event loop, distinguish it from blocking application fibers:
+			@loop = Fiber.current if Fiber.current.blocking?
+			@tracepoint = TracePoint.new(:fiber_switch){record_execution}
+			@tracepoint.enable(target_thread: @thread)
+			record_execution
+			
+			@watchdog = Thread.new{watch}
+			self
+		rescue Exception
+			stop
+			raise
+		end
+		
+		# Stop monitoring and wait for the sampling thread to finish.
+		# @returns [Watchdog | false] Self, or false if already stopped.
+		def stop
+			return false unless @running
+			
+			@tracepoint&.disable
+			
+			if @pid == Process.pid
+				@mutex.synchronize do
+					@running = false
+					@condition.broadcast
+				end
+				@watchdog&.join
+			else
+				# The sampling thread does not survive fork; avoid inherited synchronization:
+				@running = false
+			end
+			
+			self
+		ensure
+			@watchdog = @thread = @execution = @loop = @tracepoint = nil
+		end
+		
+		private
+		
+		def now
+			Process.clock_gettime(Process::CLOCK_MONOTONIC)
+		end
+		
+		def record_execution
+			fiber = Fiber.current
+			idle = @loop ? fiber.equal?(@loop) : fiber.blocking?
+			
+			@mutex.synchronize do
+				@execution = idle ? nil : [fiber, now]
+			end
+		end
+		
+		def wait
+			@mutex.synchronize do
+				@condition.wait(@mutex, @sample_interval) if @running
+				@running
+			end
+		end
+		
+		def watch
+			execution = nil
+			samples = []
+			next_report = @stall_threshold
+			
+			while wait
+				current = @mutex.synchronize{@execution}
+				unless current.equal?(execution)
+					execution = current
+					samples.clear
+					next_report = @stall_threshold
+				end
+				next unless execution
+				
+				backtrace = @thread.backtrace
+				duration = now - execution[1]
+				
+				# Discard samples if the target switched fibers while capturing its stack:
+				next unless backtrace && @mutex.synchronize{@execution.equal?(execution)}
+				
+				samples << {elapsed: duration, backtrace: backtrace}
+				samples.shift if samples.size > @max_samples
+				
+				if duration >= next_report
+					report(execution[0], duration, samples)
+					@stalls += 1
+					next_report = duration + @stall_threshold
+				end
+			end
+		rescue StandardError => error
+			# A diagnostic failure must not escape into the monitored application:
+			@error = error
+			@tracepoint.disable
+			warn_failure(error)
+		end
+		
+		def warn_failure(error)
+			warn "Fiber::Profiler::Watchdog disabled: #{error.class}: #{error.message}"
+		rescue StandardError
+			# The diagnostic destination may also be unavailable; retain the original error:
+			nil
+		end
+		
+		def report(fiber, duration, samples)
+			if @output.respond_to?(:tty?) && @output.tty?
+				message = "## Fiber stalled for at least %.3f seconds (watchdog, pid=%d, thread=%d, fiber=%d)\n" % [duration, @pid, @thread.object_id, fiber.object_id]
+				message << samples.map{|sample| sample[:backtrace].join("\n")}.join("\n\n") << "\n"
+			else
+				message = JSON.generate(mode: "watchdog", pid: @pid, thread_id: @thread.object_id, fiber_id: fiber.object_id, duration: duration, samples: samples) << "\n"
+			end
+			
+			@output.write(message)
+		end
+	end
+end

data/lib/fiber/profiler.rb

@@ -9,11 +9,25 @@ require_relative "profiler/capture"
 module Fiber::Profiler
 	# The default profiler to use, if any.
 	#
-	# Use the `FIBER_PROFILER_CAPTURE=true` environment variable to enable profiling.
+	# Set `FIBER_PROFILER` to `watchdog`, `capture`, or `false`. When unset,
+	# the legacy `FIBER_PROFILER_CAPTURE=true` setting enables capture mode.
 	#
-	# @returns [Capture | Nil]
+	# @returns [Capture | Watchdog | Nil]
+	# @raises [ArgumentError] If the requested mode is unknown.
 	def self.default
-		Capture.default
+		case mode = ENV["FIBER_PROFILER"]
+		when nil
+			Capture.default
+		when "capture"
+			Capture.new
+		when "watchdog"
+			require_relative "profiler/watchdog"
+			Watchdog.default
+		when "false"
+			nil
+		else
+			raise ArgumentError, "Unknown FIBER_PROFILER mode: #{mode.inspect} (expected watchdog, capture, or false)"
+		end
 	end
 	
 	# Execute the given block with the {default} profiler, if any.

data/readme.md

@@ -12,12 +12,20 @@ Migrating existing applications to the event loop can be tricky. One of the most
 
 Please see the [project documentation](https://socketry.github.io/fiber-profiler/) for more details.
 
-  - [Getting Started](https://socketry.github.io/fiber-profiler/guides/getting-started/index) - This guide explains how to detect stalls using the fiber profiler.
+  - [Getting Started](https://socketry.github.io/fiber-profiler/guides/getting-started/index) - This guide explains how to install the fiber profiler and choose a mode for diagnosing event-loop stalls.
+
+  - [Watchdog Mode](https://socketry.github.io/fiber-profiler/guides/watchdog-mode/index) - This guide explains how to sample ongoing fiber stalls with the watchdog profiler.
+
+  - [Capture Mode](https://socketry.github.io/fiber-profiler/guides/capture-mode/index) - This guide explains how to trace fiber execution and analyze call timings with the capture profiler.
 
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/fiber-profiler/releases/index) for all releases.
 
+### v0.7.0
+
+  - Sign releases with the Socketry Ruby Gems certificate.
+
 ### v0.6.0
 
   - Fixed compatibility with `Process.fork`.
@@ -50,12 +58,14 @@ bundle exec sus
 
 ### Making Releases
 
-To make a new release:
+To prepare a release branch and open a pull request from an up-to-date `main`:
 
 ``` shell
-bundle exec bake gem:release:patch # or minor or major
+bundle exec bake gem:github:release:patch # or minor or major
 ```
 
+After the release PR is merged, GitHub Actions automatically publishes the verified gem through the `rubygems` environment. See [bake-gem-github](https://github.com/socketry/bake-gem-github) for setup, remote releases, and recovery.
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/release.cert

@@ -0,0 +1,24 @@
+-----BEGIN CERTIFICATE-----
+MIIEFDCCAnygAwIBAgIBATANBgkqhkiG9w0BAQsFADAwMREwDwYDVQQKDAhTb2Nr
+ZXRyeTEbMBkGA1UEAwwSU29ja2V0cnkgUnVieSBHZW1zMB4XDTI2MDkyMTA3NTgx
+NFoXDTI3MDkyMTA3NTgxNFowMDERMA8GA1UECgwIU29ja2V0cnkxGzAZBgNVBAMM
+ElNvY2tldHJ5IFJ1YnkgR2VtczCCAaIwDQYJKoZIhvcNAQEBBQADggGPADCCAYoC
+ggGBAM/QgjVgDzDo/xJEQoFvAzcVFP7msnswkhPJB2UDsbxXCZmers5jV512TM5s
+NwLHfzJiC4DcI5ax9ZYKM9Q+dS21YYagNqjtg3YPyDqR6phoibEA0VoMuInUQW68
+i5OkCJzYKGD2pYYVZnuFNqyM2ECUvXh/fBmvPoHbncAHhWPaCBH8mQJ8sRNc6+RV
+SoZZu1Yo/aW1zQ+SpZwad7s1ZmigfDNHKhJ22KwZHk+/5Zw1QXVfcajjswV0Mm2P
+irgjKN3fyNVkwlly63EBlR4VydT+g9QtJtqh7ee0ThhI+v4wYovf4dbLNcEBTHu1
+x1pGbXGx/2fBAST5eVwaXIx1V8VU22AJcBk1H2o5/1F0HfbD2HQjmFOA112KUwBW
+9TtspZD3g6rCQFX53XvL9h6j2y1ukl7s5AdEzOe/x6r1MO8tSDtgcYoF89wgF/88
+Q/Eski0FckQ+znfESZcFcpzs2sPDoYW6SNVX4tZcNty85Y6WBHfHKio14x63PeyC
+CG1gMwIDAQABozkwNzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQU
+SuMc0x24Xshtaa8SQVkBr2Z5WzIwDQYJKoZIhvcNAQELBQADggGBABI62ey5lDWm
+j8jsTQaNBMBb7LbKS3XkBwyL1UNGEwlicp399rJDeuNgVSHqBCZ/nE4yleNjgW9Y
+N6DKdxXCvXmFUoHvUINeAvThHxmlEGhSfXl1x55xHEig0rEP4jgdjnYdQI4fqeOM
+zIDN0F3ruArke4Y62SQgWVN7vspdAA41hBIRl1vsvs0KWG8DIVQ8cmR+TG6zjOmK
+iUiUZGNPnStV1O1xW83c+Ba4Am0krP6/forxDPhRvTehqkVYvMdPfYcICNb5IM58
+5vaYvuj5AtfZuZWN0F/0KtSphhNC17rh6h8QmuYdMJ1clvlrkiEaO1UjPVwjgtxC
+x/ARh5X6q0/YTXl4r7EfSJEeqW7qhgu9EUj3mGIPHYdX0Dqih/NgK20F3GvQtTfB
+7sse0duKBHXONYVwKAsceUVvqtCfyF608bCilCkbhw3QaInRj+BkRQKJ5Tuj2PZR
+76a/hwaV2wWn5RtAFBaUQzQdo/xTqJ7IkwaFjOZe/QyvyoRjCK9Rdg==
+-----END CERTIFICATE-----

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.7.0
+
+  - Sign releases with the Socketry Ruby Gems certificate.
+
 ## v0.6.0
 
   - Fixed compatibility with `Process.fork`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber-profiler
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -9,43 +9,55 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
-  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
-  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
-  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
-  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
-  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
-  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
-  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
-  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
-  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
-  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
-  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
-  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
-  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
-  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
-  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
-  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
-  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
-  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
+  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
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  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'
 executables: []
 extensions:
 - ext/extconf.rb
 extra_rdoc_files: []
 files:
 - bake/fiber/profiler/analyze.rb
+- context/capture-mode.md
 - context/getting-started.md
 - context/index.yaml
+- context/watchdog-mode.md
 - ext/extconf.rb
 - ext/fiber/profiler/capture.c
 - ext/fiber/profiler/capture.h
@@ -60,9 +72,12 @@ files:
 - lib/fiber/profiler/capture.rb
 - lib/fiber/profiler/fork_handler.rb
 - lib/fiber/profiler/native.rb
+- lib/fiber/profiler/thread_local.rb
 - lib/fiber/profiler/version.rb
+- lib/fiber/profiler/watchdog.rb
 - license.md
 - readme.md
+- release.cert
 - releases.md
 homepage: https://github.com/socketry/fiber-profiler
 licenses:
@@ -84,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.21
 specification_version: 4
 summary: A fiber stall profiler.
 test_files: []

metadata.gz.sig

@@ -1 +1,3 @@
-�<dW�}	��{��~�IL3)�P�G��H(
�s0��ly����z��[�8ɧ4ރ���Ŵ�L��c���y%8�mL���o����F2�*���m��!�O�i��AS�=?@�|���J�Է�R	bmJ�}�_�a�P{��e5������8���q/�W�&5ym�����9j`�*=��>��>m����λ�@�:�P�~�ֱ{1u�>l2ɔM��4�m����ױR��ٚK�Úg�u%�0 S�C�~��|n�O���g�����<��%��K�ڬnݐ�]իI���$��9
+�I(-r[���-�������������/Bkh�ѻ��.��Ԗx�Y�h�3�+,T.B����`*VK�:�$Y�Z� F6�B�3��&9�{���5ҏ��8��Ϲ�!xוE���/h�҂&h�u�I�H�."�D�j�T���߫~X͠��c�.����L��x�ݲ�U_�KS*�x��hF�M�Q����"v�iC~���`GW
+5�t���P@8�G�Z
���J�FC�w��L2��}C]���7��U1Fv.u��1_@�e���V��*|	:��~Ͻ3�d��å�̎�p�=]]Jx#�n�@���5PT���̾
+|�2���io5EB#��K�[	H&\��G�Œ��PQ������s�?/��<u����mမ