Module: Phronomy::Diagnostics

Defined in:
lib/phronomy/diagnostics.rb

Overview

Developer-facing diagnostics for blocking operation detection (Issue #279).

Provides debug dump utilities that can be called from an IRB / Rails console or in test helpers to inspect the current state of the Runtime.

Examples:

Enable diagnostics and print a dump

Phronomy.configure { |c| c.scheduler_debug = true }
Phronomy::Diagnostics.dump

Class Method Summary collapse

Class Method Details

.assert_not_in_event_loop! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Raises an error if +invoke+ (blocking) is called from inside an EventLoop action, preventing accidental scheduler stalls.

Called by Agent::Base#invoke and Workflow#invoke before executing.

Raises:



54
55
56
57
58
59
60
 
# File 'lib/phronomy/diagnostics.rb', line 54

def self.assert_not_in_event_loop!
  return unless Phronomy::EventLoop.current?

  raise Phronomy::SchedulerReentrancyError,
    "Blocking invoke called from inside an EventLoop action. " \
    "Use invoke_async instead."
end

.dump(out: $stderr) ⇒ void

This method returns an undefined value.

Prints a formatted summary of the current Runtime state to +$stderr+ (or the supplied IO).

Includes:

  • BlockingAdapterPool: active workers, queue depth, abandoned count
  • EventLoop: last / max / average lag in milliseconds

Parameters:

  • out (IO) (defaults to: $stderr) —

    output destination (default: $stderr)



23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/phronomy/diagnostics.rb', line 23

def self.dump(out: $stderr)
  snap = Phronomy::Metrics.snapshot

  out.puts "[Phronomy::Diagnostics] Runtime state dump"
  out.puts "  BlockingAdapterPool:"
  out.puts "    pool_size       : #{snap[:blocking_pool_size]}"
  out.puts "    active_count    : #{snap[:blocking_pool_active]}"
  out.puts "    queue_depth     : #{snap[:blocking_pool_queue_length]}"
  out.puts "    abandoned_total : #{snap[:blocking_pool_abandoned_total]}"
  out.puts "  EventLoop:"
  out.puts "    last_lag_ms     : #{snap[:event_loop_lag_last_ms]}"
  out.puts "    max_lag_ms      : #{snap[:event_loop_lag_max_ms]}"
  out.puts "    average_lag_ms  : #{snap[:event_loop_lag_average_ms]}"
end

.snapshot ⇒ Hash

Returns the diagnostics state as a plain Hash (useful for JSON export).

Returns:

  • (Hash) 


42
43
44
 
# File 'lib/phronomy/diagnostics.rb', line 42

def self.snapshot
  Phronomy::Metrics.snapshot
end