Module: Lich::Common::ShutdownLog Private

Defined in:
documented/common/shutdown_log.rb

Overview

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

Centralizes shutdown-specific log formatting and diagnostic gating.

Default shutdown logs should answer "why did Lich exit?" without requiring debug mode. Diagnostic logs are reserved for timing/backtrace detail that is useful during investigation but too noisy for routine shutdowns.

Class Method Summary collapse

Class Method Details

.begin_user_exit_summary! ⇒ 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.

Starts buffering routine info logs for a possible clean user exit.

Warnings and errors still emit immediately and disqualify the compact summary, allowing the caller to flush buffered info lines later.



62
63
64
65
66
67
68
 
# File 'documented/common/shutdown_log.rb', line 62

def begin_user_exit_summary!
  mutex.synchronize do
    @user_exit_summary_active = true
    @user_exit_summary_disqualified = false
    @buffered_info = []
  end
end

.complete_user_exit_summary(message) ⇒ Boolean

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.

Emits a clean user-exit summary or flushes buffered info logs.

Parameters:

  • message (String) —

    compact clean-exit summary

Returns:

  • (Boolean) —

    whether the compact summary was emitted



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'documented/common/shutdown_log.rb', line 74

def complete_user_exit_summary(message)
  buffered_info = nil
  should_summarize = false

  mutex.synchronize do
    if @user_exit_summary_active && !@user_exit_summary_disqualified
      should_summarize = true
    else
      buffered_info = @buffered_info.dup
    end
    reset_user_exit_summary_state
  end

  if should_summarize
    write(:info, message)
    true
  else
    buffered_info&.each { |buffered_message| write(:info, buffered_message) }
    false
  end
end

.debug(message) ⇒ 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.

Logs diagnostic shutdown detail only when diagnostics are enabled.

Parameters:

  • message (String) —

    investigation detail



47
48
49
 
# File 'documented/common/shutdown_log.rb', line 47

def debug(message)
  write(:debug, message) if diagnostics_enabled?
end

.diagnostics_enabled? ⇒ Boolean

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.

Returns whether shutdown diagnostics should be verbose.

Returns:

  • (Boolean) —

    whether shutdown diagnostics should be verbose



52
53
54
 
# File 'documented/common/shutdown_log.rb', line 52

def diagnostics_enabled?
  defined?(ARGV) && ARGV.include?('--debug')
end

.error(message) ⇒ 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.

Parameters:

  • message (String) —

    human-readable shutdown error



38
39
40
41
 
# File 'documented/common/shutdown_log.rb', line 38

def error(message)
  flush_disqualified_user_exit_summary!
  write(:error, message)
end

.flush_user_exit_summary! ⇒ 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.

Flushes any buffered info logs and disables user-exit summarization.



99
100
101
102
103
104
105
106
 
# File 'documented/common/shutdown_log.rb', line 99

def flush_user_exit_summary!
  buffered_info = nil
  mutex.synchronize do
    buffered_info = @buffered_info.dup
    reset_user_exit_summary_state
  end
  buffered_info.each { |buffered_message| write(:info, buffered_message) }
end

.info(message) ⇒ 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.

Parameters:

  • message (String) —

    human-readable shutdown event



23
24
25
26
27
 
# File 'documented/common/shutdown_log.rb', line 23

def info(message)
  return if buffer_info(message)

  write(:info, message)
end

.warning(message) ⇒ 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.

Parameters:

  • message (String) —

    human-readable shutdown warning



31
32
33
34
 
# File 'documented/common/shutdown_log.rb', line 31

def warning(message)
  flush_disqualified_user_exit_summary!
  write(:warning, message)
end