Module: Polyrun::Debug

Defined in:
lib/polyrun/debug.rb

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) ⇒ Object 



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) ⇒ 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) ⇒ Object

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



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) ⇒ 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) ⇒ Object

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 ⇒ Object 



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

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