class Hatchet::HatchetLogger

Public: Class that handles logging calls and distributes them to all its appenders.

Each logger has 5 logging methods. Those are, in decreasing order of severity:

* fatal
* error
* warn
* info
* debug

All these methods have the same signature. You can either provide a message as a direct string, or as a block to the method is lazily evaluated (this is the recommended option).

Examples

log.info "Informational message"
log.info { "Informational message #{potentially_expensive}" }

It is also possible to pass an error to associate with a message. It is down to the appender what it will do with the error (such as including the stack trace) so it is recommended you still include basic information within the message you pass.

Examples

log.error "Something bad happened - #{error.message}", error

Log messages are sent to each appender where they will be filtered and invoked as configured.

Each logger also has 5 inspection methods. Those are, in decreasing order of severity:

* fatal?
* error?
* warn?
* info?
* debug?

All these methods take no arguments and return true if any of the loggers' appenders will log a message at that level for the current context, otherwise they will return false.

Constants

STANDARD_TO_SYMBOL

Internal: Map from standard library levels to Symbols.

Attributes

ndc[R]

Public: Gets the NestedDiagnosticContext for the logger.

Public Class Methods

new(host, configuration, ndc) click to toggle source

Internal: Creates a new logger.

host - The object the logger gains its context from. configuration - The configuration of Hatchet. ndc - The nested diagnostic context of the logger.

# File lib/hatchet/hatchet_logger.rb, line 74
def initialize(host, configuration, ndc)
  @context = host_name(host)
  @configuration = configuration
  @ndc = ndc
end

Public Instance Methods

<<(msg) click to toggle source

Public: No-op, exists for greater compatibility with things expecting a standard Logger.

# File lib/hatchet/hatchet_logger.rb, line 347
def <<(msg)
  nil
end
add(severity, message = nil, progname = nil, &block) click to toggle source

Public: Adds a message to each appender at the specified level.

level - The level of the message. One of, in decreasing order of

severity:

  * Logger::FATAL
  * Logger::ERROR
  * Logger::WARN
  * Logger::INFO
  * Logger::DEBUG
  * :fatal
  * :error
  * :warn
  * :info
  * :debug

message - The message that will be logged by an appender when it is

configured to log at the given level or lower.

block - An optional block which will provide a message when invoked.

Writes messages to STDOUT if any appender fails to complete the enabled check or log the message.

Also aliased as log.

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 337
def add(severity, message = nil, progname = nil, &block)
  level = STANDARD_TO_SYMBOL[severity] || severity
  add_to_appenders(level, message, nil, &block)
end
Also aliased as: log
debug(message = nil, error = nil, &block) click to toggle source

Public: Logs a message at debug level.

message - An already evaluated message, usually a String (default: nil). error - An error which is associated with the message (default: nil). block - An optional block which will provide a message when invoked.

One of message or block must be provided. If both are provided then the block is preferred as it is assumed to provide more detail.

In general, you should use the block style for any message not related to an error. This is because any unneccessary String interpolation is avoided making unwritten debug calls, for example, less expensive.

When logging errors it is advised that you include some details of the error within the regular message, perhaps the error's message, but leave the inclusion of the stack trace up to your appenders and their formatters.

Examples

debug { "A fine grained message" }
debug "A message relating to an exception", e

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 105
def debug(message = nil, error = nil, &block)
  add_to_appenders(:debug, message, error, &block)
end
debug?() click to toggle source

Public: Returns true if any of the appenders will log messages for the current context at debug level, otherwise returns false.

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 114
def debug?
  enabled? :debug
end
error(message = nil, error = nil, &block) click to toggle source

Public: Logs a message at error level.

message - An already evaluated message, usually a String (default: nil). error - An error which is associated with the message (default: nil). block - An optional block which will provide a message when invoked.

One of message or block must be provided. If both are provided then the block is preferred as it is assumed to provide more detail.

In general, you should use the block style for any message not related to an error. This is because any unneccessary String interpolation is avoided making unwritten error calls, for example, less expensive.

When logging errors it is advised that you include some details of the error within the regular message, perhaps the error's message, but leave the inclusion of the stack trace up to your appenders and their formatters.

Examples

error { "A fine grained message" }
error "A message relating to an exception", e

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 219
def error(message = nil, error = nil, &block)
  add_to_appenders(:error, message, error, &block)
end
error?() click to toggle source

Public: Returns true if any of the appenders will log messages for the current context at error level, otherwise returns false.

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 228
def error?
  enabled? :error
end
fatal(message = nil, error = nil, &block) click to toggle source

Public: Logs a message at fatal level.

message - An already evaluated message, usually a String (default: nil). error - An error which is associated with the message (default: nil). block - An optional block which will provide a message when invoked.

One of message or block must be provided. If both are provided then the block is preferred as it is assumed to provide more detail.

In general, you should use the block style for any message not related to an error. This is because any unneccessary String interpolation is avoided making unwritten fatal calls, for example, less expensive.

When logging errors it is advised that you include some details of the error within the regular message, perhaps the error's message, but leave the inclusion of the stack trace up to your appenders and their formatters.

Examples

fatal { "A fine grained message" }
fatal "A message relating to an exception", e

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 257
def fatal(message = nil, error = nil, &block)
  add_to_appenders(:fatal, message, error, &block)
end
fatal?() click to toggle source

Public: Returns true if any of the appenders will log messages for the current context at fatal level, otherwise returns false.

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 266
def fatal?
  enabled? :fatal
end
formatter() click to toggle source

Public: Returns nil, exists for greater compatibility with things expecting a standard Logger.

# File lib/hatchet/hatchet_logger.rb, line 299
def formatter
  nil
end
formatter=(formatter) click to toggle source

Public: No-op, exists for greater compatibility with things expecting a standard Logger.

# File lib/hatchet/hatchet_logger.rb, line 306
def formatter=(formatter)
  # no-op for Logger protocol compatibility
end
info(message = nil, error = nil, &block) click to toggle source

Public: Logs a message at info level.

message - An already evaluated message, usually a String (default: nil). error - An error which is associated with the message (default: nil). block - An optional block which will provide a message when invoked.

One of message or block must be provided. If both are provided then the block is preferred as it is assumed to provide more detail.

In general, you should use the block style for any message not related to an error. This is because any unneccessary String interpolation is avoided making unwritten info calls, for example, less expensive.

When logging errors it is advised that you include some details of the error within the regular message, perhaps the error's message, but leave the inclusion of the stack trace up to your appenders and their formatters.

Examples

info { "A fine grained message" }
info "A message relating to an exception", e

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 143
def info(message = nil, error = nil, &block)
  add_to_appenders(:info, message, error, &block)
end
info?() click to toggle source

Public: Returns true if any of the appenders will log messages for the current context at info level, otherwise returns false.

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 152
def info?
  enabled? :info
end
level() click to toggle source

Public: Returns the default level of the logger's configuration.

# File lib/hatchet/hatchet_logger.rb, line 272
def level
  @configuration.default_level
end
level=(level) click to toggle source

Public: Set the lowest level of message to log by default.

level - The lowest level of message to log by default.

The use of this method is not recommended as it affects the performance of the logging. It is only provided for compatibility.

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 285
def level=(level)
  level = case level
          when Symbol
            level
          else
            STANDARD_TO_SYMBOL[level] || :info
          end

  @configuration.level level
end
log(severity, message = nil, progname = nil, &block)
Alias for: add
to_yaml_properties() click to toggle source

Internal: Specifies the instance variables to be serialized when converting the logger to YAML.

# File lib/hatchet/hatchet_logger.rb, line 354
def to_yaml_properties
  [:@context]
end
warn(message = nil, error = nil, &block) click to toggle source

Public: Logs a message at warn level.

message - An already evaluated message, usually a String (default: nil). error - An error which is associated with the message (default: nil). block - An optional block which will provide a message when invoked.

One of message or block must be provided. If both are provided then the block is preferred as it is assumed to provide more detail.

In general, you should use the block style for any message not related to an error. This is because any unneccessary String interpolation is avoided making unwritten warn calls, for example, less expensive.

When logging errors it is advised that you include some details of the error within the regular message, perhaps the error's message, but leave the inclusion of the stack trace up to your appenders and their formatters.

Examples

warn { "A fine grained message" }
warn "A message relating to an exception", e

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 181
def warn(message = nil, error = nil, &block)
  add_to_appenders(:warn, message, error, &block)
end
warn?() click to toggle source

Public: Returns true if any of the appenders will log messages for the current context at warn level, otherwise returns false.

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 190
def warn?
  enabled? :warn
end

Private Instance Methods

add_to_appenders(level, message, error, &block) click to toggle source

Private: Adds a message to each appender at the specified level.

level - The level of the message. One of, in decreasing order of

severity:

  * fatal
  * error
  * warn
  * info
  * debug

message - The message that will be logged by an appender when it is

configured to log at the given level or lower.

error - An error which is associated with the message. block - An optional block which will provide a message when invoked.

Writes messages to STDOUT if any appender fails to complete the enabled check or log the message.

Returns nothing.

# File lib/hatchet/hatchet_logger.rb, line 382
def add_to_appenders(level, message, error, &block)
  return unless message or block

  # Ensure configuration and context set - can be lost by marshalling and
  # unmarshalling the logger.
  @configuration ||= Hatchet.configuration
  @ndc ||= Hatchet::NestedDiagnosticContext.current

  msg = Message.new(ndc: @ndc.context.clone, message: message, error: error, backtrace_filters: @configuration.backtrace_filters, &block)

  @configuration.appenders.each do |appender|
    if appender.enabled?(level, @context)
      begin
        appender.add(level, @context, msg)
      rescue => e
        STDERR.puts "Failed to log message for #{@context} with appender #{appender} - #{level} - #{msg}\n"
        STDERR.puts "#{e}\n"
      end
    end
  end
  nil
end
enabled?(level) click to toggle source

Private: Returns true if any of the appenders will log messages for the current context at the given level, otherwise returns false.

level - The level of the message. One of, in decreasing order of

severity:

  * fatal
  * error
  * warn
  * info
  * debug

Writes messages to STDOUT if any appender fails to complete the check.

# File lib/hatchet/hatchet_logger.rb, line 419
def enabled?(level)
  @configuration.appenders.any? do |appender|
    begin
      appender.enabled? level, @context
    rescue
      puts "Failed to check if level #{level} enabled for #{context} with appender #{appender}\n"
      false
    end
  end
end
host_name(host) click to toggle source

Private: Determines the contextual name of the host object.

host - The object hosting this logger.

Returns the String 'main' if this is the initial execution context of Ruby, the host itself when the host is a module, otherwise the object's class.

# File lib/hatchet/hatchet_logger.rb, line 438
def host_name(host)
  if host.inspect == 'main'
    'main'
  elsif [Module, Class].include? host.class
    host
  else
    host.class
  end
end