Class: Kitchen::Logger

Inherits:
Object
  • Object
show all
Includes:
Logger::Severity
Defined in:
lib/kitchen/logger.rb

Overview

Logging implementation for Kitchen. By default the console/stdout output will be displayed differently than the file log output. Therefore, this class wraps multiple loggers that conform to the stdlib Logger class behavior.

Author:

Defined Under Namespace

Classes: DeviceFactory, LineBuffer, LogdevLogger, SinkSet, StdoutLogger, StreamLineFormatter, StructuredLogdevLogger

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Logger

Constructs a new logger.

Parameters:

  • options (Hash) (defaults to: {}) —

    configuration for a new logger

Options Hash (options):

  • :color (Symbol) —

    color to use when outputting messages

  • :level (Integer) —

    the logging severity threshold (default: Kitchen::DEFAULT_LOG_LEVEL)

  • :log_overwrite (Boolean) —

    whether to overwrite the log when Test Kitchen runs. Only applies if the :logdev is a String. (default: Kitchen::DEFAULT_LOG_OVERWRITE)

  • :logdev (String, IO) —

    filepath String or IO object to be used for logging (default: nil)

  • :progname (String) —

    program name to include in log messages (default: "Kitchen")

  • :stdout (IO) —

    a standard out IO object to use (default: $stdout)

  • :colorize (Boolean) —

    whether to colorize output when Test Kitchen runs. (default: $stdout.tty?)



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/kitchen/logger.rb', line 68

def initialize(options = {})
  @base_metadata = options[:metadata] || {}
  @log_overwrite = if options[:log_overwrite].nil?
                     default_log_overwrite
                   else
                     options[:log_overwrite]
                   end

  @logdev = device_factory.logdev_logger(options[:logdev], log_overwrite) if options[:logdev]
  if options[:structured_logdev]
    @structured_logdev = device_factory.structured_logdev_logger(
      options[:structured_logdev],
      log_overwrite,
      -> { metadata }
    )
  end
  @logdev_path = expanded_log_path(options[:logdev])
  @structured_logdev_path = expanded_log_path(options[:structured_logdev])

  populate_loggers(options)

  # These setters cannot be called until @loggers are populated because
  # they are delegated
  self.progname = options[:progname] || "Kitchen"
  self.level = options[:level] || default_log_level
end

Instance Attribute Details

#log_overwrite ⇒ Boolean (readonly)

Returns whether logger is configured for overwriting.

Returns:

  • (Boolean) —

    whether logger is configured for overwriting



47
48
49
 
# File 'lib/kitchen/logger.rb', line 47

def log_overwrite
  @log_overwrite
end

#logdev ⇒ IO (readonly)

Returns the log device.

Returns:

  • (IO) —

    the log device



34
35
36
 
# File 'lib/kitchen/logger.rb', line 34

def logdev
  @logdev
end

#logdev_path ⇒ String? (readonly)

Returns the expanded text log path, if configured.

Returns:

  • (String, nil) —

    the expanded text log path, if configured



40
41
42
 
# File 'lib/kitchen/logger.rb', line 40

def logdev_path
  @logdev_path
end

#structured_logdev ⇒ IO (readonly)

Returns the structured log device.

Returns:

  • (IO) —

    the structured log device



37
38
39
 
# File 'lib/kitchen/logger.rb', line 37

def structured_logdev
  @structured_logdev
end

#structured_logdev_path ⇒ String? (readonly)

Returns the expanded structured log path, if configured.

Returns:

  • (String, nil) —

    the expanded structured log path, if configured



43
44
45
 
# File 'lib/kitchen/logger.rb', line 43

def structured_logdev_path
  @structured_logdev_path
end

Instance Method Details

#<<(message) ⇒ Object

Dump one or more messages to info.

Parameters:

  • message (#to_s) —

    the message to log

See Also:



177
 
# File 'lib/kitchen/logger.rb', line 177

delegate_to_all_loggers :<<

#add(severity, message = nil, progname = nil) { ... } ⇒ Object

Log a message if the given severity is high enough.

Parameters:

  • severity (Integer) —

    a stdlib Logger severity constant

  • message (#to_s, nil) (defaults to: nil) —

    the message to log; when nil the block's value is used, falling back to progname

  • progname (#to_s, nil) (defaults to: nil) —

    used as the message when both message and a block are absent

Yields:

  • evaluates to the message to log

See Also:



170
 
# File 'lib/kitchen/logger.rb', line 170

delegate_to_all_loggers :add

Log a message with severity of banner (high level).

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



191
 
# File 'lib/kitchen/logger.rb', line 191

delegate_to_all_loggers :banner

#close ⇒ Object

Close the logging devices.

See Also:



311
 
# File 'lib/kitchen/logger.rb', line 311

delegate_to_all_loggers :close

#datetime_format ⇒ String

Returns the date format being used.

Returns:

  • (String) —

    the date format being used

See Also:



151
 
# File 'lib/kitchen/logger.rb', line 151

delegate_to_first_logger :datetime_format

#datetime_format=(format) ⇒ Object

Sets the date format being used.

Parameters:

  • format (String) —

    the date format

See Also:



158
 
# File 'lib/kitchen/logger.rb', line 158

delegate_to_all_loggers :datetime_format=

#debug(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of debug.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



205
 
# File 'lib/kitchen/logger.rb', line 205

delegate_to_all_loggers :debug

#debug? ⇒ true, false

Returns whether or not the current severity level allows for the printing of debug messages.

Returns:

  • (true, false) —

    whether or not the current severity level allows for the printing of debug messages

See Also:



211
 
# File 'lib/kitchen/logger.rb', line 211

delegate_to_first_logger :debug?

#error(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of error.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



245
 
# File 'lib/kitchen/logger.rb', line 245

delegate_to_all_loggers :error

#error? ⇒ true, false

Returns whether or not the current severity level allows for the printing of error messages.

Returns:

  • (true, false) —

    whether or not the current severity level allows for the printing of error messages

See Also:



251
 
# File 'lib/kitchen/logger.rb', line 251

delegate_to_first_logger :error?

#fatal(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of fatal.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



285
 
# File 'lib/kitchen/logger.rb', line 285

delegate_to_all_loggers :fatal

#fatal? ⇒ true, false

Returns whether or not the current severity level allows for the printing of fatal messages.

Returns:

  • (true, false) —

    whether or not the current severity level allows for the printing of fatal messages

See Also:



291
 
# File 'lib/kitchen/logger.rb', line 291

delegate_to_first_logger :fatal?

#info(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of info.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



225
 
# File 'lib/kitchen/logger.rb', line 225

delegate_to_all_loggers :info

#info? ⇒ true, false

Returns whether or not the current severity level allows for the printing of info messages.

Returns:

  • (true, false) —

    whether or not the current severity level allows for the printing of info messages

See Also:



231
 
# File 'lib/kitchen/logger.rb', line 231

delegate_to_first_logger :info?

#level ⇒ Integer

Returns the logging severity threshold.

Returns:

  • (Integer) —

    the logging severity threshold

See Also:



127
 
# File 'lib/kitchen/logger.rb', line 127

delegate_to_first_logger :level

#level=(level) ⇒ Object

Sets the logging severity threshold.

Parameters:

  • level (Integer) —

    the logging severity threshold

See Also:



134
 
# File 'lib/kitchen/logger.rb', line 134

delegate_to_all_loggers :level=

#metadata ⇒ Hash

Returns metadata added to structured log events.

Returns:

  • (Hash) —

    metadata added to structured log events



314
315
316
317
318
 
# File 'lib/kitchen/logger.rb', line 314

def metadata
  metadata_stack.inject(@base_metadata.dup) do |result, values|
    result.merge(values)
  end
end

#progname ⇒ String

Returns program name to include in log messages.

Returns:

  • (String) —

    program name to include in log messages

See Also:



139
 
# File 'lib/kitchen/logger.rb', line 139

delegate_to_first_logger :progname

#progname=(progname) ⇒ Object

Sets the program name to include in log messages.

Parameters:

  • progname (String) —

    the program name to include in log messages

See Also:



146
 
# File 'lib/kitchen/logger.rb', line 146

delegate_to_all_loggers :progname=

#unknown(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of unknown.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



305
 
# File 'lib/kitchen/logger.rb', line 305

delegate_to_all_loggers :unknown

#warn(message_or_progname = nil) { ... } ⇒ nil, true

Log a message with severity of warn.

Parameters:

  • message_or_progname (#to_s) (defaults to: nil) —

    the message to log. In the block form, this is the progname to use in the log message.

Yields:

  • evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.

Returns:

  • (nil, true) —

    when the given severity is not high enough (for this particular logger), log no message, and return true

See Also:



265
 
# File 'lib/kitchen/logger.rb', line 265

delegate_to_all_loggers :warn

#warn? ⇒ true, false

Returns whether or not the current severity level allows for the printing of warn messages.

Returns:

  • (true, false) —

    whether or not the current severity level allows for the printing of warn messages

See Also:



271
 
# File 'lib/kitchen/logger.rb', line 271

delegate_to_first_logger :warn?

#with_metadata(values) ⇒ Object

Temporarily adds metadata to structured log events.

Parameters:

  • values (Hash) —

    metadata fields to add for the block duration



323
324
325
326
327
328
 
# File 'lib/kitchen/logger.rb', line 323

def with_metadata(values)
  metadata_stack.push(values.compact)
  yield
ensure
  metadata_stack.pop
end