DebugTracer

A Ruby gem for debug logging that outputs variable values with execution context to assist AI-powered bug detection.

• Automatic Context Capture: Automatically captures execution context using caller_locations
• Flexible Configuration: Customize output destination and display options via YAML configuration
• Simple API: Output variable values instantly with dt(binding, :var)
• Thread-Safe: Safe operation in multi-threaded environments

Add to your Gemfile:

gem 'debug-tracer'

Then execute:

$ bundle install

Or install directly:

$ gem install debug-tracer

For Rails applications, run the install generator:

$ bundle exec rails generate debug_tracer:install

This will create:

• config/initializers/debug_tracer.rb - Initializer with default configuration
• config/debug-tracer.yml - YAML configuration file

require 'debug-tracer'

class Order
  include DebugTracer

  def apply_coupon(price, coupon)
    dt(binding, :price, :coupon)
    # Output:
    # /path/to/order.rb:7 in `apply_coupon`
    # => price = 1000
    # => coupon = #<Coupon id: 1, discount_rate: 20>

    discount = price * (coupon.discount_rate / 100.0)
    dt(binding, :discount)
    # => discount = 200.0

    final_price = price - discount
    dt(binding, :final_price)
    # => final_price = 800.0

    final_price
  end
end

DebugTracer.configure do |config|
  config.enabled = true
  config.output_target = :stdout  # or :file
  config.output_file_path = 'log/debug_trace.log'
  config.display_file_path = true
  config.display_line_number = true
  config.display_method_name = true
end

config/debug-tracer.yml:

enabled: true
output:
  target: stdout  # stdout or file
  file_path: log/debug_trace.log
display:
  file_path: true
  line_number: true
  method_name: true

Load configuration file:

DebugTracer.load_config_file('config/debug-tracer.yml')

After running rails generate debug_tracer:install, the initializer is automatically configured:

config/initializers/debug_tracer.rb:

DebugTracer.configure do |config|
  config.enabled = Rails.env.development?
  config.output_target = :file
  config.output_file_path = Rails.root.join('log', 'debug_trace.log')
  config.display_file_path = true
  config.display_line_number = true
  config.display_method_name = true
end

DebugTracer's output is optimized for AI-powered bug analysis:

1. Execution Context: Identify problem locations with file path, line number, and method name
2. Variable State: Track variable values at each point in time
3. Structured Output: Consistent format that's easy for AI to parse

• Check the spelling of variable names
• Ensure dt is called within the scope of local variables

• Check write permissions for the output directory
• Verify the file path is correctly configured

Bug reports and pull requests are welcome on GitHub.

This gem is available as open source under the terms of the MIT License.