Module: Polyrun::Debug

Defined in:
lib/polyrun/debug.rb,
sig/polyrun/debug.rbs

Overview

Opt-in tracing: set DEBUG=1 or POLYRUN_DEBUG=1 (or true). Logs to stderr with wall-clock timestamps; use .time for monotonic durations.

Class Method Summary collapse

Class Method Details

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


7
8
9
 
# File 'lib/polyrun/debug.rb', line 7

def enabled?
  truthy?(ENV["DEBUG"]) || truthy?(ENV["POLYRUN_DEBUG"])
end

.log(message) ⇒ void

This method returns an undefined value.

Parameters:

  • message (String) 


11
12
13
14
15
 
# File 'lib/polyrun/debug.rb', line 11

def log(message)
  return unless enabled?

  Polyrun::Log.warn "[polyrun debug #{wall_clock}] #{message}"
end

.log_kv(pairs) ⇒ void

This method returns an undefined value.

Parameters:

  • pairs (Object) 


17
18
19
20
21
 
# File 'lib/polyrun/debug.rb', line 17

def log_kv(pairs)
  return unless enabled?

  log(pairs.map { |k, v| "#{k}=#{v.inspect}" }.join(" "))
end

.log_worker(message) ⇒ void

This method returns an undefined value.

Same as log, but tags lines from parallel RSpec workers so they are not confused with the parent polyrun process (stderr interleaves arbitrarily).

Parameters:

  • message (String) 


24
25
26
27
28
29
30
31
32
 
# File 'lib/polyrun/debug.rb', line 24

def log_worker(message)
  return unless enabled?

  if parallel_worker_process?
    Polyrun::Log.warn "[polyrun debug #{wall_clock}] [worker pid=#{$$} shard=#{ENV.fetch("POLYRUN_SHARD_INDEX", "?")}] #{message}"
  else
    Polyrun::Log.warn "[polyrun debug #{wall_clock}] #{message}"
  end
end

.log_worker_kv(pairs) ⇒ void

This method returns an undefined value.

Parameters:

  • pairs (Object) 


34
35
36
37
38
39
40
41
42
 
# File 'lib/polyrun/debug.rb', line 34

def log_worker_kv(pairs)
  return unless enabled?

  if parallel_worker_process?
    log_kv({role: "worker", pid: $$, shard: ENV["POLYRUN_SHARD_INDEX"]}.merge(pairs))
  else
    log_kv(pairs)
  end
end

.parallel_worker_process? ⇒ Boolean

Returns:

  • (Boolean) 


44
45
46
 
# File 'lib/polyrun/debug.rb', line 44

def parallel_worker_process?
  ENV["POLYRUN_SHARD_TOTAL"].to_i > 1
end

.time(label) ⇒ void

This method returns an undefined value.

Yields and logs monotonic duration; re-raises after logging failures.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/polyrun/debug.rb', line 49

def time(label)
  t0 = nil
  return yield unless enabled?

  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  log("#{label} … start")
  result = yield
  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
  elapsed_s = format("%0.3f", elapsed)
  log("#{label} … done in #{elapsed_s}s")
  result
rescue => e
  if t0
    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
    elapsed_s = format("%0.3f", elapsed)
    log("#{label} … failed after #{elapsed_s}s: #{e.class}: #{e.message}")
  end
  raise
end

.wall_clock ⇒ String

Returns:

  • (String) 


69
70
71
 
# File 'lib/polyrun/debug.rb', line 69

def wall_clock
  Time.now.getlocal.strftime("%H:%M:%S.%6N")
end