Class: Logging::Layouts::Parseable

Inherits:
Logging::Layout show all
Defined in:
lib/logging/layouts/parseable.rb

Overview

This layout will produce parseable log output in either JSON or YAML format. This makes it much easier for machines to parse log files and perform analysis on those logs.

The information about the log event can be configured when the layout is created. Any or all of the following labels can be set as the items to log:

'logger'     Used to output the name of the logger that generated the
             log event.
'timestamp'  Used to output the timestamp of the log event.
'level'      Used to output the level of the log event.
'message'    Used to output the application supplied message
             associated with the log event.
'file'       Used to output the file name where the logging request
             was issued.
'line'       Used to output the line number where the logging request
             was issued.
'method'     Used to output the method name where the logging request
             was issued.
'hostname'   Used to output the hostname
'pid'        Used to output the process ID of the currently running
             program.
'millis'     Used to output the number of milliseconds elapsed from
             the construction of the Layout until creation of the log
             event.
'thread_id'  Used to output the object ID of the thread that generated
             the log event.
'thread'     Used to output the name of the thread that generated the
             log event. Name can be specified using Thread.current[:name]
             notation. Output empty string if name not specified. This
             option helps to create more human readable output for
             multithread application logs.

These items are supplied to the layout as an array of strings. The items ‘file’, ‘line’, and ‘method’ will only work if the Logger generating the events is configured to generate tracing information. If this is not the case these fields will always be empty.

When configured to output log events in YAML format, each log message will be formatted as a hash in it’s own YAML document. The hash keys are the name of the item, and the value is what you would expect it to be. Therefore, for the default set of times log message would appear as follows:

---
timestamp: 2009-04-17T16:15:42
level: INFO
logger: Foo::Bar
message: this is a log message
---
timestamp: 2009-04-17T16:15:43
level: ERROR
logger: Foo
message: <RuntimeError> Oooops!!

The output order of the fields is not guaranteed to be the same as the order specified in the items list. This is because Ruby hashes are not ordered by default (unless you’re running this in Ruby 1.9).

When configured to output log events in JSON format, each log message will be formatted as an object (in the JSON sense of the word) on it’s own line in the log output. Therefore, to parse the output you must read it line by line and parse the individual objects. Taking the same example above the JSON output would be:

{"timestamp":"2009-04-17T16:15:42","level":"INFO","logger":"Foo::Bar","message":"this is a log message"}
{"timestamp":"2009-04-17T16:15:43","level":"ERROR","logger":"Foo","message":"<RuntimeError> Oooops!!"}

The output order of the fields is guaranteed to be the same as the order specified in the items list.

Constant Summary collapse

DIRECTIVE_TABLE =

:stopdoc: Arguments to sprintf keyed to directive letters

{
  'logger'    => 'event.logger'.freeze,
  'timestamp' => 'iso8601_format(event.time)'.freeze,
  'level'     => '::Logging::LNAMES[event.level]'.freeze,
  'message'   => 'format_obj(event.data)'.freeze,
  'file'      => 'event.file'.freeze,
  'line'      => 'event.line'.freeze,
  'method'    => 'event.method_name'.freeze,
  'hostname'  => "'#{Socket.gethostname}'".freeze,
  'pid'       => 'Process.pid'.freeze,
  'millis'    => 'Integer((event.time-@created_at)*1000)'.freeze,
  'thread_id' => 'Thread.current.object_id'.freeze,
  'thread'    => 'Thread.current[:name]'.freeze,
  'mdc'       => 'Logging::MappedDiagnosticContext.context'.freeze,
  'ndc'       => 'Logging::NestedDiagnosticContext.context'.freeze
}

Instance Attribute Summary collapse

Attributes inherited from Logging::Layout

#backtrace, #cause_depth, #utc_offset

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Logging::Layout

#apply_utc_offset, #footer, #format, #format_cause_backtrace, #header, #try_json, #try_yaml

Constructor Details

#initialize(opts = {}) ⇒ Parseable

call-seq:

Parseable.new( opts )

Creates a new Parseable layout using the following options:

:style      => :json or :yaml
:items      => %w[timestamp level logger message]
:utc_offset =>  "-06:00" or -21600 or "UTC"



184
185
186
187
188
189
 
# File 'lib/logging/layouts/parseable.rb', line 184

def initialize( opts = {} )
  super
  @created_at = Time.now
  @style = opts.fetch(:style, 'json').to_s.intern
  self.items = opts.fetch(:items, %w[timestamp level logger message])
end

Instance Attribute Details

#items ⇒ Object

Returns the value of attribute items.



191
192
193
 
# File 'lib/logging/layouts/parseable.rb', line 191

def items
  @items
end

Class Method Details

.create_json_format_method(layout) ⇒ Object

call-seq:

Pattern.create_json_format_methods( layout )

This method will create the format method in the given Parseable layout based on the configured items for the layout instance.



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/logging/layouts/parseable.rb', line 140

def self.create_json_format_method( layout )
  code = "undef :format if method_defined? :format\n"
  code << "def format( event )\nh = {\n"

  code << layout.items.map {|name|
    "'#{name}' => #{Parseable::DIRECTIVE_TABLE[name]}"
  }.join(",\n")
  code << "\n}\nMultiJson.encode(h) << \"\\n\"\nend\n"

  (class << layout; self end).class_eval(code, __FILE__, __LINE__)
end

.create_yaml_format_method(layout) ⇒ Object

call-seq:

Pattern.create_yaml_format_methods( layout )

This method will create the format method in the given Parseable layout based on the configured items for the layout instance.



122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/logging/layouts/parseable.rb', line 122

def self.create_yaml_format_method( layout )
  code = "undef :format if method_defined? :format\n"
  code << "def format( event )\nstr = {\n"

  code << layout.items.map {|name|
    "'#{name}' => #{Parseable::DIRECTIVE_TABLE[name]}"
  }.join(",\n")
  code << "\n}.to_yaml\nreturn str\nend\n"

  (class << layout; self end).class_eval(code, __FILE__, __LINE__)
end

.json(opts = {}) ⇒ Object

call-seq:

Parseable.json( opts )

Create a new Parseable layout that outputs log events using JSON style formatting. See the initializer documentation for available options.



159
160
161
162
 
# File 'lib/logging/layouts/parseable.rb', line 159

def self.json( opts = {} )
  opts[:style] = 'json'
  new(opts)
end

.yaml(opts = {}) ⇒ Object

call-seq:

Parseable.yaml( opts )

Create a new Parseable layout that outputs log events using YAML style formatting. See the initializer documentation for available options.



170
171
172
173
 
# File 'lib/logging/layouts/parseable.rb', line 170

def self.yaml( opts = {} )
  opts[:style] = 'yaml'
  new(opts)
end

Instance Method Details

#format_cause(e) ⇒ Object

Internal: Format any nested exceptions found in the given exception ‘e` while respecting the maximum `cause_depth`.

e - Exception to format

Returns the cause formatted as a Hash



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/logging/layouts/parseable.rb', line 244

def format_cause(e)
  rv = curr = {}
  prev = nil

  cause_depth.times do
    break unless e.respond_to?(:cause) && e.cause

    cause = e.cause
    curr[:class]     = cause.class.name
    curr[:message]   = cause.message
    curr[:backtrace] = format_cause_backtrace(e, cause) if backtrace? && cause.backtrace

    prev[:cause] = curr unless prev.nil?
    prev, curr = curr, {}

    e = cause
  end

  if e.respond_to?(:cause) && e.cause
    prev[:cause] = {message: "Further #cause backtraces were omitted"}
  end

  rv
end

#format_obj(obj) ⇒ Object

Public: Take a given object and convert it into a format suitable for inclusion as a log message. The conversion allows the object to be more easily expressed in YAML or JSON form.

If the object is an Exception, then this method will return a Hash containing the exception class name, message, and backtrace (if any).

obj - The Object to format

Returns the formatted Object.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/logging/layouts/parseable.rb', line 219

def format_obj( obj )
  case obj
  when Exception
    hash = {
      :class   => obj.class.name,
      :message => obj.message
    }
    hash[:backtrace] = obj.backtrace if backtrace? && obj.backtrace

    cause = format_cause(obj)
    hash[:cause] = cause unless cause.empty?
    hash
  when Time
    iso8601_format(obj)
  else
    obj
  end
end