Parent

Logging::Layouts::Parseable

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.
  '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-17 16:15:42
  level: INFO
  logger: Foo::Bar
  message: this is a log message
  ---
  timestamp: 2009-04-17 16: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-17 16:15:42","level":"INFO","logger":"Foo::Bar","message":"this is a log message"}
  {"timestamp":"2009-04-17 16: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.

Attributes

items[R]

Public Class Methods

json( opts ) click to toggle source

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

     # File lib/logging/layouts/parseable.rb, line 156
156:     def self.json( opts = {} )
157:       opts[:style] = 'json'
158:       new(opts)
159:     end
new( opts ) click to toggle source

Creates a new Parseable layout using the following options:

   :style  => :json or :yaml
   :items  => %w[timestamp level logger message]
     # File lib/logging/layouts/parseable.rb, line 180
180:     def initialize( opts = {} )
181:       super
182:       @created_at = Time.now
183:       @style = opts.getopt(:style, 'json').to_s.intern
184:       self.items = opts.getopt(:items, ]timestamp level logger message])
185:     end
yaml( opts ) click to toggle source

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

     # File lib/logging/layouts/parseable.rb, line 167
167:     def self.yaml( opts = {} )
168:       opts[:style] = 'yaml'
169:       new(opts)
170:     end

Public Instance Methods

items = %w[timestamp level logger message] click to toggle source

Set the log event items that will be formatted by this layout. These items, and only these items, will appear in the log output.

     # File lib/logging/layouts/parseable.rb, line 195
195:     def items=( ary )
196:       @items = Array(ary).map {|name| name.to_s.downcase}
197:       valid = DIRECTIVE_TABLE.keys
198:       @items.each do |name|
199:         raise ArgumentError, "unknown item - #{name.inspect}" unless valid.include? name
200:       end
201:       create_format_method
202:     end

Private Instance Methods

create_format_method() click to toggle source

Call the appropriate class level create format method based on the style of this parseable layout.

     # File lib/logging/layouts/parseable.rb, line 219
219:     def create_format_method
220:       case @style
221:       when :json; Parseable.create_json_format_method(self)
222:       when :yaml; Parseable.create_yaml_format_method(self)
223:       else raise ArgumentError, "unknown format style '#@style'" end
224:     end
format_as_json( value ) click to toggle source

Take the given value and format it into a JSON compatible string.

     # File lib/logging/layouts/parseable.rb, line 208
208:     def format_as_json( value )
209:       case value
210:       when String, Integer, Float; value.inspect
211:       when nil; 'null'
212:       when Time; %{"#{iso8601_format(value)}"}
213:       else %{"#{value.inspect}"} end
214:     end
iso8601_format( value ) click to toggle source

Convert the given time value into an ISO8601 formatted time string.

     # File lib/logging/layouts/parseable.rb, line 228
228:     def iso8601_format( value )
229:       str = value.strftime('%Y-%m-%dT%H:%M:%S')
230:       str << ('.%06d' % value.usec)
231: 
232:       offset = value.gmt_offset.abs
233:       return str << 'Z' if offset == 0
234: 
235:       offset = sprintf('%02d:%02d', offset / 3600, offset % 3600 / 60)
236:       return str << (value.gmt_offset < 0 ? '-' : '+') << offset
237:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.