Class: Lumberjack::Formatter

Inherits:
Object
  • Object
show all
Defined in:
lib/lumberjack/formatter.rb,
lib/lumberjack/formatter/id_formatter.rb,
lib/lumberjack/formatter/round_formatter.rb,
lib/lumberjack/formatter/strip_formatter.rb,
lib/lumberjack/formatter/object_formatter.rb,
lib/lumberjack/formatter/redact_formatter.rb,
lib/lumberjack/formatter/string_formatter.rb,
lib/lumberjack/formatter/inspect_formatter.rb,
lib/lumberjack/formatter/multiply_formatter.rb,
lib/lumberjack/formatter/truncate_formatter.rb,
lib/lumberjack/formatter/date_time_formatter.rb,
lib/lumberjack/formatter/exception_formatter.rb,
lib/lumberjack/formatter/structured_formatter.rb,
lib/lumberjack/formatter/pretty_print_formatter.rb

Overview

Formatter controls the conversion of log entry messages into a loggable format, allowing you to log any object type and have the logging system handle the string conversion automatically.

The formatter system works by associating formatting rules with specific classes using the #add method. When an object is logged, the formatter finds the most specific formatter for that object's class hierarchy and applies it to convert the object into a string representation.

Formatters can be:

  • Predefined formatters: Accessed by symbol (e.g., :pretty_print, :truncate)
  • Custom objects: Any object responding to #call(object)
  • Blocks: Inline formatting logic
  • Classes: Instantiated automatically with optional arguments

The formatter includes optimizations for common primitive types (String, Integer, Float, Boolean) to avoid unnecessary formatting overhead when custom formatters aren't defined for these types.

Examples:

Basic formatter usage

formatter = Lumberjack::Formatter.new
formatter.add(MyClass, :pretty_print)
formatter.add(Array) { |vals| vals.join(", ") }
result = formatter.format(my_object)

Building a custom formatter

formatter = Lumberjack::Formatter.build do |config|
  config.add(User, :id)  # Only log user IDs
  config.add(BigDecimal, :round, 2)  # Round decimals to 2 places
end

Defined Under Namespace

Classes: DateTimeFormatter, ExceptionFormatter, IdFormatter, InspectFormatter, MultiplyFormatter, ObjectFormatter, PrettyPrintFormatter, RedactFormatter, RoundFormatter, StringFormatter, StripFormatter, StructuredFormatter, TagsFormatter, TruncateFormatter

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Lumberjack::Formatter

Create a new formatter with default mappings for common Ruby types. The default configuration provides sensible formatting for most use cases:

  • Object: Uses inspect for debugging-friendly output
  • Exception: Formats with stack trace details
  • Enumerable: Recursively formats collections (Arrays, Hashes, etc.)


92
93
94
95
96
97
 
# File 'lib/lumberjack/formatter.rb', line 92

def initialize
  @class_formatters = {}
  @has_string_formatter = false
  @has_numeric_formatter = false
  @has_boolean_formatter = false
end

Class Method Details

.build {|formatter| ... } ⇒ Lumberjack::Formatter

Build a new formatter using a configuration block. The block receives the new formatter as a parameter, allowing you to configure it with methods like add, remove, etc.

Examples:

formatter = Lumberjack::Formatter.build do |config|
  config.add(User, :id)  # Only show user IDs
  config.add(SecretToken) { |token| "[REDACTED]" }
  config.remove(Exception)  # Don't format exceptions specially
end

Yields:

  • (formatter) —

    A block that configures the formatter.

Returns:



63
64
65
66
67
 
# File 'lib/lumberjack/formatter.rb', line 63

def build(&block)
  formatter = new
  block&.call(formatter)
  formatter
end

.default ⇒ Lumberjack::Formatter

Create a new formatter with default mappings.

Object: inspect formatter
Exception: exception formatter
Enumerable: structured formatter

Returns:



76
77
78
79
80
81
82
 
# File 'lib/lumberjack/formatter.rb', line 76

def default
  build do |config|
    config.add(Object, :inspect)
    config.add(Exception, :exception)
    config.add(Enumerable, :structured)
  end
end

Instance Method Details

#add(klass, formatter = nil, *args) {|obj| ... } ⇒ self

Add a formatter for a specific class or classes. The formatter determines how objects of that class will be converted to strings when logged.

The formatter can be specified in several ways:

  • Symbol: References a predefined formatter (see list below)
  • Class: Will be instantiated with optional arguments
  • Object: Must respond to #call(object) method
  • Block: Inline formatting logic

Formatters can be referenced by name from the formatter registry. These formatters are available out of the box. Some of them require an argument to be provided as well.

  • :date_time - Formats time objects with a customizable format (takes the format string as an argument)
  • :exception - Formats exceptions with stack trace details
  • :id - Extracts object ID or specified ID field
  • :inspect - Uses Ruby's inspect method for debugging output
  • :multiply - Multiplies numeric values by a factor (requires the factor as an argument)
  • :object - Generic object formatter with custom methods
  • :pretty_print - Pretty-prints objects using PP library
  • :redact - Redacts sensitive information from objects
  • :round - Rounds numeric values to specified precision (takes the precision as an argument; defaults to 3 decimal places)
  • :string - Converts objects to strings using to_s
  • :strip - Strips whitespace from string representations
  • :structured - Recursively formats structured data (Arrays, Hashes)
  • :tags - Formats an array or hash of values in the format "[a] [b] [c=d]"
  • :truncate - Truncates long strings to specified length (takes the length as an argument)

Classes can be specified as:

  • Class objects: Direct class references
  • Arrays: Multiple classes at once
  • Strings: Class names to avoid loading dependencies

Examples:

Using predefined formatters

formatter.add(Float, :round, 2)  # Round floats to 2 decimal places
formatter.add(Time, :date_time, "%Y-%m-%d")  # Custom time format
formatter.add([User, Admin], :id)  # Show only IDs for user objects

Using custom formatters

formatter.add(MyClass, MyFormatter.new)  # Custom formatter object
formatter.add("BigDecimal", RoundFormatter, 4)  # Class with arguments

Method chaining

formatter.add(User, :id)
         .add(BigDecimal, :round, 2)

Parameters:

  • klass (Class, Module, String, Array<Class, Module, String>) —

    The class(es) to format.

  • formatter (Symbol, Class, #call, nil) (defaults to: nil) —

    The formatter to use.

  • args (Array) —

    Arguments passed to formatter constructor (when formatter is a Class).

Yields:

  • (obj) —

    Block-based formatter that receives the object to format.

Yield Parameters:

  • obj (Object) —

    The object to format.

Yield Returns:

  • (String) —

    The formatted string representation.

Returns:

  • (self) —

    Returns self for method chaining.

Raises:

  • (ArgumentError) 


152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/lumberjack/formatter.rb', line 152

def add(klass, formatter = nil, *args, &block)
  formatter ||= block

  return remove(klass) if formatter.nil?

  if formatter.is_a?(Symbol)
    formatter = FormatterRegistry.formatter(formatter, *args)
  elsif formatter.is_a?(Class)
    formatter = formatter.new(*args)
  end

  raise ArgumentError.new("formatter must respond to call") unless formatter.respond_to?(:call)

  Array(klass).each do |k|
    @class_formatters[k.to_s] = formatter
  end

  set_optimized_flags!

  self
end

#call(severity, timestamp, progname, msg) ⇒ String

Compatibility method for Ruby's standard Logger::Formatter interface. This allows the Formatter to be used directly as a logger formatter, though it only uses the message parameter and ignores severity, timestamp, and progname.

Parameters:

  • severity (Integer, String, Symbol) —

    The log severity (ignored).

  • timestamp (Time) —

    The log timestamp (ignored).

  • progname (String) —

    The program name (ignored).

  • msg (Object) —

    The message object to format.

Returns:

  • (String) —

    The formatted message with line separator.



284
285
286
287
288
 
# File 'lib/lumberjack/formatter.rb', line 284

def call(severity, timestamp, progname, msg)
  formatted_message = format(msg)
  formatted_message = formatted_message.message if formatted_message.is_a?(MessageAttributes)
  "#{formatted_message}#{Lumberjack::LINE_SEPARATOR}"
end

#clear ⇒ self

Remove all formatter associations, including defaults. This creates a completely empty formatter where all objects will be passed through unchanged.

Returns:

  • (self) —

    Returns self for method chaining.



226
227
228
229
230
231
 
# File 'lib/lumberjack/formatter.rb', line 226

def clear
  @class_formatters.clear
  set_optimized_flags!

  self
end

#empty? ⇒ Boolean

Check if the formatter has any registered formatters.

Returns:

  • (Boolean) —

    true if no formatters are registered, false otherwise.



236
237
238
 
# File 'lib/lumberjack/formatter.rb', line 236

def empty?
  @class_formatters.empty?
end

#format(value) ⇒ Object

Format an object by applying the appropriate formatter based on its class hierarchy. The formatter searches up the class hierarchy to find the most specific formatter available.

Parameters:

  • value (Object) —

    The object to format.

Returns:

  • (Object) —

    The formatted representation (usually a String).



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/lumberjack/formatter.rb', line 245

def format(value)
  # These primitive types are the most common in logs and so are optimized here
  # for the normal case where a custom formatter has not been defined.
  case value
  when String
    return value unless @has_string_formatter
  when Integer, Float
    return value unless @has_numeric_formatter
  when Numeric
    if defined?(BigDecimal) && value.is_a?(BigDecimal)
      return value unless @has_numeric_formatter
    end
  when true, false
    return value unless @has_boolean_formatter
  end

  if value.respond_to?(:to_log_format) && !@class_formatters.include?(value.class.name)
    return value.to_log_format
  end

  formatter = formatter_for(value.class)
  value = formatter.call(value) if formatter&.respond_to?(:call)
  value
rescue SystemStackError, StandardError => e
  error_message = e.class.name
  error_message = "#{error_message} #{e.message}" if e.message && e.message != ""
  warn("<Error formatting #{value.class.name}: #{error_message}>")
  "<Error formatting #{value.class.name}: #{error_message}>"
end

#formatter_for(klass) ⇒ #call?

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.

Find the most appropriate formatter for a class by searching up the class hierarchy. Returns the first formatter found by walking through the class's ancestors.

Parameters:

  • klass (Class) —

    The class to find a formatter for.

Returns:

  • (#call, nil) —

    The formatter object, or nil if no formatter is found.



296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/lumberjack/formatter.rb', line 296

def formatter_for(klass)
  return nil if @class_formatters.empty?

  unless klass.is_a?(Module)
    begin
      klass = Object.const_get(klass.to_s)
    rescue NameError
      return @class_formatters[klass.to_s]
    end
  end

  formatter = nil
  has_to_log_format = klass.public_method_defined?(:to_log_format) if klass.is_a?(Module)
  klass.ancestors.detect do |ancestor|
    break if has_to_log_format && ancestor == Object

    formatter = @class_formatters[ancestor.name]
    break if formatter
  end
  formatter
end

#include(formatter) ⇒ self

Extend this formatter by merging the formats defined in the provided formatter into this one.

Parameters:

Returns:

  • (self) —

    Returns self for method chaining.



193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/lumberjack/formatter.rb', line 193

def include(formatter)
  unless formatter.is_a?(Lumberjack::Formatter)
    raise ArgumentError.new("formatter must be a Lumberjack::Formatter")
  end

  formatter.instance_variable_get(:@class_formatters).each do |class_name, fmttr|
    add(class_name, fmttr)
  end

  self
end

#include?(class_or_name) ⇒ Boolean

Check if a formatter exists for a specific class or class name.

Parameters:

  • class_or_name (Class, Module, String) —

    The class or class name to check.

Returns:

  • (Boolean) —

    true if a formatter exists, false otherwise.



322
323
324
 
# File 'lib/lumberjack/formatter.rb', line 322

def include?(class_or_name)
  @class_formatters.include?(class_or_name.to_s)
end

#prepend(formatter) ⇒ self

Extend this formatter by adding the formats defined in the provided formatter into this one. Formats defined in this formatter will take precedence and not be overridden.

Parameters:

Returns:

  • (self) —

    Returns self for method chaining.



210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/lumberjack/formatter.rb', line 210

def prepend(formatter)
  unless formatter.is_a?(Lumberjack::Formatter)
    raise ArgumentError.new("formatter must be a Lumberjack::Formatter")
  end

  formatter.instance_variable_get(:@class_formatters).each do |class_name, fmttr|
    add(class_name, fmttr) unless @class_formatters.include?(class_name)
  end

  self
end

#remove(klass) ⇒ self

Remove formatter associations for one or more classes. This reverts the classes to use the default Object formatter (inspect method) or no formatting if no default exists.

Parameters:

  • klass (Class, Module, String, Array<Class, Module, String>) —

    The class(es) to remove formatters for.

Returns:

  • (self) —

    Returns self for method chaining.



179
180
181
182
183
184
185
186
187
 
# File 'lib/lumberjack/formatter.rb', line 179

def remove(klass)
  Array(klass).each do |k|
    @class_formatters.delete(k.to_s)
  end

  set_optimized_flags!

  self
end