Class: Lumberjack::Template

Inherits:
Object
  • Object
show all
Defined in:
lib/lumberjack/template.rb

Overview

A flexible template system for converting log entries into formatted strings. Templates use mustache style placeholders to create customizable log output formats.

The template system supports the following built-in placeholders:

  • {{time}} - The log entry timestamp
  • {{severity}} - The severity level (DEBUG, INFO, WARN, ERROR, FATAL). The severity can also be formatted in a variety of ways with an optional format specifier. Supported formats include:
    • {{severity(padded)}} - Right padded so that all values are five characters
    • {{severity(char)}} - Single character representation (D, I, W, E, F)
    • {{severity(emoji)}} - Emoji representation
    • {{severity(level)}} - Numeric level representation
  • {{progname}} - The program name that generated the entry
  • {{pid}} - The process ID
  • {{message}} - The main log message content
  • {{attributes}} - All custom attributes formatted as key:value pairs

Custom attribute placeholders can also be put in the double bracket placeholders. Any attributes explicitly added to the template in their own placeholder will be removed from the general list of attributes.

Examples:

Basic template usage

template = Lumberjack::Template.new("[{{time}} {{severity}}] {{message}}")
# Output: [2023-08-21T10:30:15.123 INFO] User logged in

Multi-line message formatting

template = Lumberjack::Template.new(
  "[{{time}} {{severity}}] {{message}}",
  additional_lines: "\n    | {{message}}"
)
# Output:
# [2023-08-21T10:30:15.123 INFO] First line
#     | Second line
#     | Third line

Custom attribute placeholders

# The user_id attribute will be put before the message instead of with the rest of the attributes.
template = Lumberjack::Template.new("[{{time}} {{severity}}] (usr:{{user_id}} {{message}} -- {{attributes}})")

Defined Under Namespace

Classes: StandardFormatterTemplate

Constant Summary collapse

DEFAULT_FIRST_LINE_TEMPLATE = 
"[{{time}} {{severity(padded)}} {{progname}}({{pid}})] {{message}} {{attributes}}"
STDLIB_FIRST_LINE_TEMPLATE = 
"{{severity(char)}}, [{{time}} {{pid}}] {{severity(padded)}} -- {{progname}}: {{message}} {{attributes}}"
DEFAULT_ADDITIONAL_LINES_TEMPLATE = 
"#{Lumberjack::LINE_SEPARATOR}> {{message}}"
DEFAULT_ATTRIBUTE_FORMAT = 
"[%s:%s]"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(first_line = nil, additional_lines: nil, time_format: nil, attribute_format: nil, colorize: false) ⇒ Template

Create a new template with customizable formatting options. The template supports different formatting for single-line and multi-line messages, custom time formatting, and configurable attribute display.

Parameters:

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

    Template for formatting the first line of messages. Defaults to [{{ time }} {{ severity(padded) }} {{ progname }}({{ pid }})] {{ message }} {{ attributes }}

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

    Template for formatting additional lines in multi-line messages. Defaults to \n> {{ message }}

  • time_format (String, Symbol, nil) (defaults to: nil) —

    Time formatting specification. Can be:

    • A strftime format string (e.g., "%Y-%m-%d %H:%M:%S")
    • :milliseconds for ISO format with millisecond precision (default)
    • :microseconds for ISO format with microsecond precision
  • attribute_format (String, nil) (defaults to: nil) —

    Printf-style format for individual attributes. Must contain exactly two %s placeholders for name and value. Defaults to "[%s:%s]"

  • colorize (Boolean) (defaults to: false) —

    Whether to colorize the log entry based on severity (default: false)

Raises:

  • (ArgumentError) —

    If attribute_format doesn't contain exactly two %s placeholders



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/lumberjack/template.rb', line 132

def initialize(first_line = nil, additional_lines: nil, time_format: nil, attribute_format: nil, colorize: false)
  first_line ||= DEFAULT_FIRST_LINE_TEMPLATE
  first_line = "#{first_line.chomp}#{Lumberjack::LINE_SEPARATOR}"
  @first_line_template, @first_line_attributes = compile(first_line)

  additional_lines ||= DEFAULT_ADDITIONAL_LINES_TEMPLATE
  @additional_line_template, @additional_line_attributes = compile(additional_lines)

  @attribute_template = attribute_format || DEFAULT_ATTRIBUTE_FORMAT
  unless @attribute_template.scan("%s").size == 2
    raise ArgumentError.new("attribute_format must be a printf template with exactly two '%s' placeholders")
  end

  # Formatting the time is relatively expensive, so only do it if it will be used
  @template_include_time = "#{@first_line_template} #{@additional_line_template}".include?("%1$s")
  self.datetime_format = (time_format || :milliseconds)

  @colorize = colorize
  @pid_cache = nil
end

Class Method Details

.colorize_entry(formatted_string, entry) ⇒ Object 



108
109
110
111
112
113
 
# File 'lib/lumberjack/template.rb', line 108

def colorize_entry(formatted_string, entry)
  color_start = entry.severity_data.terminal_color
  formatted_string.split(Lumberjack::LINE_SEPARATOR).collect do |line|
    "\e7#{color_start}#{line}\e8"
  end.join(Lumberjack::LINE_SEPARATOR)
end

Instance Method Details

#call(entry) ⇒ String

Convert a log entry into a formatted string using the template. This method handles both single-line and multi-line messages, applying the appropriate templates and performing placeholder substitution.

Parameters:

Returns:

  • (String) —

    The formatted log entry string



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/lumberjack/template.rb', line 192

def call(entry)
  return entry unless entry.is_a?(LogEntry)

  first_line = entry.message.to_s
  additional_lines = nil
  if first_line.include?(Lumberjack::LINE_SEPARATOR)
    additional_lines = first_line.split(Lumberjack::LINE_SEPARATOR)
    first_line = additional_lines.shift
  end

  formatted_time = cached_formatted_time(entry.time) if @template_include_time
  severity = entry.severity_data
  format_args = [
    formatted_time,
    severity.label,
    severity.padded_label,
    severity.char,
    severity.emoji,
    severity.level,
    entry.progname,
    cached_pid_string(entry.pid),
    first_line
  ]
  append_attribute_args!(format_args, entry.attributes, @first_line_attributes)
  message = (@first_line_template % format_args)

  if additional_lines && !additional_lines.empty?
    format_args.slice!(9, format_args.size)
    append_attribute_args!(format_args, entry.attributes, @additional_line_attributes)

    message_length = message.length
    message.chomp!(Lumberjack::LINE_SEPARATOR)
    chomped = message.length != message_length

    additional_lines.each do |line|
      format_args[8] = line
      line_message = @additional_line_template % format_args
      message << line_message
    end

    message << Lumberjack::LINE_SEPARATOR if chomped
  end

  message = Template.colorize_entry(message, entry) if @colorize

  # Normalize the output to end with exactly one line separator and no trailing
  # whitespace so the writer can send it to the stream without any further processing.
  message.rstrip!
  message << Lumberjack::LINE_SEPARATOR

  message
end

#datetime_format ⇒ String

Get the current datetime format string used for timestamp formatting.

Returns:

  • (String) —

    The strftime format string currently in use



182
183
184
 
# File 'lib/lumberjack/template.rb', line 182

def datetime_format
  @time_formatter.format
end

#datetime_format=(format) ⇒ void

This method returns an undefined value.

Set the datetime format used for timestamp formatting in the template. This method accepts both strftime format strings and symbolic shortcuts.

Parameters:

  • format (String, Symbol) —

    The datetime format specification:

    • String: A strftime format pattern (e.g., "%Y-%m-%d %H:%M:%S")
    • :milliseconds: ISO format with millisecond precision (YYYY-MM-DDTHH:MM:SS.sss)
    • :microseconds: ISO format with microsecond precision (YYYY-MM-DDTHH:MM:SS.ssssss)


161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/lumberjack/template.rb', line 161

def datetime_format=(format)
  if format == :milliseconds
    format = MILLISECOND_TIME_FORMAT
  elsif format == :microseconds
    format = MICROSECOND_TIME_FORMAT
  end
  @time_formatter = Formatter::DateTimeFormatter.new(format)

  # Formatted timestamps can only be cached for the built-in formats where the
  # subsecond precision is known.
  @time_cache_units, @time_cache_divisor = if format == MILLISECOND_TIME_FORMAT
    [1_000, 1_000_000]
  elsif format == MICROSECOND_TIME_FORMAT
    [1_000_000, 1_000]
  end
  @time_cache = nil
end