Module: BrainzLab::Debug

Defined in:
lib/brainzlab/debug.rb

Overview

Debug module for SDK operation logging

Provides pretty-printed debug output for all SDK operations when debug mode is enabled. Includes timing information and request/response details.

Examples:

Enable debug mode

BrainzLab.configure do |config|
  config.debug = true
end

Use custom logger

BrainzLab.configure do |config|
  config.debug = true
  config.logger = Logger.new(STDOUT)
end

Manual debug logging

BrainzLab::Debug.log("Custom message", level: :info)

Constant Summary collapse

COLORS = 
{
  reset: "\e[0m",
  bold: "\e[1m",
  dim: "\e[2m",
  red: "\e[31m",
  green: "\e[32m",
  yellow: "\e[33m",
  blue: "\e[34m",
  magenta: "\e[35m",
  cyan: "\e[36m",
  white: "\e[37m",
  gray: "\e[90m"
}.freeze
LEVEL_COLORS = 
{
  debug: :gray,
  info: :cyan,
  warn: :yellow,
  error: :red,
  fatal: :red
}.freeze
LEVEL_LABELS = 
{
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARN',
  error: 'ERROR',
  fatal: 'FATAL'
}.freeze

Class Method Summary collapse

Class Method Details

.colorize? ⇒ Boolean

Check if colorized output should be used

Returns:

  • (Boolean) 


159
160
161
162
163
164
 
# File 'lib/brainzlab/debug.rb', line 159

def colorize?
  return false unless enabled?
  return @colorize if defined?(@colorize)

  @colorize = $stdout.tty?
end

.enabled? ⇒ Boolean

Check if debug mode is enabled

Returns:

  • (Boolean) 


152
153
154
 
# File 'lib/brainzlab/debug.rb', line 152

def enabled?
  BrainzLab.configuration.debug?
end

.log(message, level: :info, **data) ⇒ void

This method returns an undefined value.

Log a debug message if debug mode is enabled

Parameters:

  • message (String) —

    The message to log

  • level (Symbol) (defaults to: :info) —

    Log level (:debug, :info, :warn, :error, :fatal)

  • data (Hash) —

    Optional additional data to include



61
62
63
64
65
66
 
# File 'lib/brainzlab/debug.rb', line 61

def log(message, level: :info, **data)
  return unless enabled?

  output = format_message(message, level: level, **data)
  write_output(output, level: level)
end

.log_operation(service, operation, **data) ⇒ void

This method returns an undefined value.

Log an SDK operation with timing

Parameters:

  • service (String, Symbol) —

    The service name

  • operation (String) —

    Operation description

  • data (Hash) —

    Operation data



115
116
117
118
119
120
121
122
123
 
# File 'lib/brainzlab/debug.rb', line 115

def log_operation(service, operation, **data)
  return unless enabled?

  data_summary = data.empty? ? '' : " (#{format_data_inline(data)})"
  message = "#{operation}#{data_summary}"

  output = format_arrow_message(:out, service, message)
  write_output(output, level: :info)
end

.log_request(service, method, path, data: nil) ⇒ void

This method returns an undefined value.

Log an outgoing request

Parameters:

  • service (String, Symbol) —

    The service name (e.g., :recall, :reflex)

  • method (String) —

    HTTP method

  • path (String) —

    Request path

  • data (Hash) (defaults to: nil) —

    Request payload summary



75
76
77
78
79
80
81
82
83
 
# File 'lib/brainzlab/debug.rb', line 75

def log_request(service, method, path, data: nil)
  return unless enabled?

  data_summary = summarize_data(data) if data
  message = data_summary ? "#{method} #{path} #{data_summary}" : "#{method} #{path}"

  output = format_arrow_message(:out, service, message)
  write_output(output, level: :info)
end

.log_response(service, status, duration_ms, error: nil) ⇒ void

This method returns an undefined value.

Log an incoming response

Parameters:

  • service (String, Symbol) —

    The service name

  • status (Integer) —

    HTTP status code

  • duration_ms (Float) —

    Request duration in milliseconds

  • error (String, nil) (defaults to: nil) —

    Error message if request failed



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/brainzlab/debug.rb', line 92

def log_response(service, status, duration_ms, error: nil)
  return unless enabled?

  status_text = status_message(status)
  duration_text = format_duration(duration_ms)

  message = if error
              "#{status} #{status_text} (#{duration_text}) - #{error}"
            else
              "#{status} #{status_text} (#{duration_text})"
            end

  level = status >= 400 ? :error : :info
  output = format_arrow_message(:in, service, message, level: level)
  write_output(output, level: level)
end

.measure(service, operation) { ... } ⇒ Object

Measure and log execution time of a block

Parameters:

  • service (String, Symbol) —

    The service name

  • operation (String) —

    Operation description

Yields:

  • Block to measure

Returns:

  • (Object) —

    Result of the block



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/brainzlab/debug.rb', line 131

def measure(service, operation)
  return yield unless enabled?

  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  log_operation(service, operation)

  result = yield

  duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
  log("#{operation} completed", level: :debug, duration_ms: duration_ms, service: service.to_s)

  result
rescue StandardError => e
  duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
  log("#{operation} failed: #{e.message}", level: :error, duration_ms: duration_ms, service: service.to_s)
  raise
end

.reset_colorize! ⇒ Object

Reset colorize detection (useful for testing)



167
168
169
 
# File 'lib/brainzlab/debug.rb', line 167

def reset_colorize!
  remove_instance_variable(:@colorize) if defined?(@colorize)
end