DebugTrace-rb

Japanese

DebugTrace-rb is a library that outputs trace logs when debugging Ruby, and is available for Ruby 3.1.0 and later. By embedding DebugTrace.enter and DebugTrace.leave at the start and end of a method, you can output the execution status of a Ruby program you are developing.

1. Features

  • Automatically outputs the calling method name, source file name, and line number.
  • Automatically indents logs when nesting methods or objects.
  • Automatically inserts line breaks when outputting values.
  • Can output object contents using reflection.
  • Output contents can be customized by configuring the debugtrace.yml file.

2. Installation

Run the following command to install the gem and add it to your application's Gemfile:

$ bundle add debugtrace

If you are not using bundler to manage dependencies, run the following command to install the gem:

$ gem install debugtrace

3. Usage

Do the following for the debug target and related methods.

  1. Insert DebugTrace.enter at the beginning of the method.

  2. Insert DebugTrace.leave at the end of the method (or just before the return statement).

  3. Optionally, insert DebugTrace.print('foo', foo) to print arguments, local variables, and return values ​​to the log.

Below is an example of Ruby using DebugTrace-rb methods and the log when it is executed.

# frozen_string_literal: true
# readme-example.rb
require 'debugtrace'

class Contact
  attr_reader :id, :firstName, :lastName, :birthday

  def initialize(id, firstName, lastName, birthday)
    DebugTrace.enter
    @id = id
    @firstName = firstName
    @lastName = lastName
    @birthday = birthday
    DebugTrace.leave
  end
end

def func2
  DebugTrace.enter
  contacts = [
    Contact.new(1, 'Akane' , 'Apple', Date.new(1991, 2, 3)),
    Contact.new(2, 'Yukari', 'Apple', Date.new(1992, 3, 4))
  ]
  DebugTrace.leave(contacts)
end

def func1
  DebugTrace.enter
  DebugTrace.print('Hello, World!')
  contacts = func2
  DebugTrace.leave(contacts)
end

func1

2025-07-05 14:38:35.412+09:00 DebugTrace-rb 1.2.0 on Ruby 3.4.4
2025-07-05 14:38:35.412+09:00   config file: <No config file>
2025-07-05 14:38:35.412+09:00   logger: StdErrLogger
2025-07-05 14:38:35.412+09:00 
2025-07-05 14:38:35.412+09:00 ______________________________  #72 ______________________________
2025-07-05 14:38:35.412+09:00 
2025-07-05 14:38:35.412+09:00 Enter func1 (examples/readme-example.rb:29) <- <main> (examples/readme-example.rb:35)
2025-07-05 14:38:35.412+09:00 | Hello, World! (examples/readme-example.rb:30)
2025-07-05 14:38:35.412+09:00 | Enter func2 (examples/readme-example.rb:20) <- func1 (examples/readme-example.rb:31)
2025-07-05 14:38:35.412+09:00 | | Enter Contact#initialize (examples/readme-example.rb:10) <- Class#new (examples/readme-example.rb:22)
2025-07-05 14:38:35.412+09:00 | | Leave Contact#initialize (examples/readme-example.rb:15) duration: 0.012 ms
2025-07-05 14:38:35.412+09:00 | | 
2025-07-05 14:38:35.412+09:00 | | Enter Contact#initialize (examples/readme-example.rb:10) <- Class#new (examples/readme-example.rb:23)
2025-07-05 14:38:35.412+09:00 | | Leave Contact#initialize (examples/readme-example.rb:15) duration: 0.007 ms
2025-07-05 14:38:35.413+09:00 | Leave func2 (examples/readme-example.rb:25) duration: 0.234 ms
2025-07-05 14:38:35.413+09:00 Leave func1 (examples/readme-example.rb:32) duration: 0.379 ms
2025-07-05 14:38:35.413+09:00 
2025-07-05 14:38:35.413+09:00 contacts = [
2025-07-05 14:38:35.413+09:00   Contact{
2025-07-05 14:38:35.413+09:00     @id: 1, @firstName: 'Akane', @lastName: 'Apple', @birthday: 1991-02-03
2025-07-05 14:38:35.413+09:00   },
2025-07-05 14:38:35.413+09:00   Contact{
2025-07-05 14:38:35.413+09:00     @id: 2, @firstName: 'Yukari', @lastName: 'Apple',
2025-07-05 14:38:35.413+09:00     @birthday: 1992-03-04
2025-07-05 14:38:35.413+09:00   }
2025-07-05 14:38:35.413+09:00 ] (examples/readme-example.rb:36)

4. List of methods

DebugTrace module has the following methods.

Method List
Method name Arguments Return value Description
enter None None Outputs the start of the method to the log.
leave return_value: return value of this method(Optional) return_value (nil if return_value is omitted) Output the end of the method to the log.
print name: the value name
value: the value (Optional)
The following arguments are keyword arguments and optional
reflection: reflection is used aggressively if true, used passively if false(Default: false)
The following arguments can be specified in debugtrace.yml (argument specification takes precedence)
minimum_output_size: The minimum number of elements to print for Array, Hash and Set
minimum_output_length: The minimum length to print the length of the string
output_size_limit: The limit on the number of elements output for Map, Hash and Set
output_length_limit: The limit on the number of characters that can be output from a string
reflection_limit: The limit of reflection nesting
 the argument value if it is specified, otherwise nil If the value is specified, it will be output to the log in the format:
=
, otherwise prints name as a message.

5. debugtrace.yml Properties

You can specify the path of debugtrace.yml with the environment variable DEBUGTRACE_CONFIG.
The default path is ./debugtrace.yml.
You can specify the following properties in debugtrace.yml.

debugtrace.yml
Property Name Description
logger Specifying the log output destination
Examples:
    logger: stdout - standard output
    logger: stderr - standard error output
    logger: rubylogger - use the Ruby Logger class
    logger: file - specified file
Default Value:
    stderr
log_path Path to log output destination when using rubylogger or file
If the first character is + and using logger: file, the log will be appended.
Example:
    logger: file
    log_path: +/var/log/debugtrace.log
Default Value:
    debugtrace.log
rubylogger_format The format string when using the Ruby Logger class
Example:
    rubylogger_format: "%2$s %1$s %3$s %4$s\n"
Parameters:
    %1: the log level (DEBUG)
    %2: the date
    %3: the program (DebugTrace)
    %4: the message
Default Value:
    rubylogger_format: "%2$s %1$s %4$s\n"
Reference:
log_datetime_format Log date and time format
Example:
    log_datetime_format: "%Y/%m/%d %H:%M:%S.%L%"
Default Value:
    log_datetime_format: "%Y-%m-%d %H:%M:%S.%L%:z"
Reference:
enabled Enables logging if true,disables logging if false
Example:
    enabled: false
Default Value:
    enabled: true
enter_format The log format to be output at the start of methods
Example:
    enter_format: "┌ %1$s (%2$s:%3$d)"
Parameters:
    %1: the method name
    %2: the file name
    %3: the line number
    %4: the method name of the calling method
    %5: the file name of the calling method
    %6: the line number of the calling method
Default Value:
    enter_format: "Enter %1$s (%2$s:%3$d) <- %4$s (%5$s:%6$d)"
leave_format The format of the log output at the end of the method
Example:
    leave_format: "└ %1$s (%2$s:%3$d) duration: %4$.2f ms"
Parameters:
    %1: the method name
    %2: the file name
    %3: the line number
    %4: the time (in milliseconds) since the corresponding enter method was called
Default Value:
    leave_format: "Leave %1$s (%2$s:%3$d) duration: %4$.3f ms"
thread_boundary_format The format string printed at thread boundaries
Example:
    thread_boundary_format: "─────────────────────────────── %1$s #%2$d ──────────────────────────────"
Parameters:
    %1: the thread name
    %2: the object ID of the thread
Default Value:
    thread_boundary_format: "______________________________ %1$s #%2$d ______________________________"
maximum_indents Maximum indentation
Example:
    maximum_indents: 16
Default Value:
    maximum_indents: 32
indent_string The code indent string
Example:
    indent_string: "│ "
Default Value:
    indent_string: "| "
data_indent_string The data indent string
Example:
    data_indent_string: "⧙ "
Default Value:
    data_indent_string: " "
limit_string The string to output if limit is exceeded
Example:
    limit_string: "‥‥"
Default Value:
    limit_string: "..."
circular_reference_string The string to output if there is a circular reference
Example:
    circular_reference_string: "⤴ "
Default Value:
    circular_reference_string: "*** Circular Reference ***"
varname_value_separator The separator string between variable name and value
Example:
    varname_value_separator: " == "
Default Value:
    varname_value_separator: " = "
key_value_separator The separator string for Hash key and value, and object variable name and value
Example:
    key_value_separato: " => "
Default Value:
    key_value_separato: ": "
print_suffix_format The format string added by the print method
Example:
    print_suffix_format: " (%2$s/%1$s:%3$d)"

Parameters:
    %1: the method name
    %2: the file name
    %3: the line number
Default Value:
    print_suffix_format: " (%2$s:%3$d)"
size_format Output format for number of elements in Array, Hash, and Set
Example:
    size_format: "(size=%d)"
Parameters:
    %1: number of elements
Default Value:
    size_format: "(size:%d)"
minimum_output_size The minimum number to print the number of elements in an Array, Hash, or Set
Example:
    minimum_output_size: 2
Default Value:
    minimum_output_size: 256
length_format The format of string length
Example:
    length_format: "(length=%d)"
Parameters:
    %1: the string length
Default Value:
    length_format: "(length:%d)"
minimum_output_length The minimum length to print the length of the string
Example:
    minimum_output_length: 6
Default Value:
    minimum_output_length: 256
data_output_width Data output width
Example:
    data_output_width = 100
Default Value:
    data_output_width: 70
bytes_count_in_line Number of lines to output when outputting a string as a byte array
Example:
    bytes_count_in_line: 32
Default Value:
    bytes_count_in_line: 16
output_size_limit The limit on the number of elements output for Array, Hash, and Set
Example:
    output_size_limit: 64
Default Value:
    output_size_limit: 128
output_length_limit The limit on the number of characters that can be output from a string
Example:
    output_length_limit: 64
Default Value:
    output_length_limit: 256
reflection_limit The limit of reflection nesting
Example:
    reflection_limit: 3
Default Value:
    reflection_limit: 4

6. CHANGELOG

CHANGELOG

7. License

MIT License(MIT)

© 2025 Masato Kokubo