class Logger

Overview

The Logger class provides a simple but sophisticated logging utility that you can use to output messages.

The messages have associated levels, such as INFO or ERROR that indicate their importance. You can then give the Logger a level, and only messages at that level or higher will be printed.

For instance, in a production system, you may have your Logger set to INFO or even WARN. When you are developing the system, however, you probably want to know about the program’s internal state, and would set the Logger to DEBUG.

Example

require "logger"

log = Logger.new(STDOUT)
log.level = Logger::WARN

# or
log = Logger.new(STDOUT, level: Logger::WARN)

log.debug("Created logger")
log.info("Program started")
log.warn("Nothing to do!")

begin
  File.each_line("/foo/bar.log") do |line|
    unless line =~ /^(\w+) = (.*)$/
      log.error("Line in wrong format: #{line}")
    end
  end
rescue err
  log.fatal("Caught exception; exiting")
  log.fatal(err)
end

If logging to multiple locations is required, an IO::MultiWriter can be used.

file = File.new("production.log", "a")
writer = IO::MultiWriter.new(file, STDOUT)

log = Logger.new(writer)
log.level = Logger::DEBUG
log.debug("Created logger")

Defined in:

logger.cr

Constant Summary

DEBUG = Severity::DEBUG
ERROR = Severity::ERROR
FATAL = Severity::FATAL
INFO = Severity::INFO
UNKNOWN = Severity::UNKNOWN
WARN = Severity::WARN

Constructors

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil)
same?
, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash
hash(hasher)
hash
, inspect(io : IO) : Nil
inspect : String
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO)
to_json
to_json
, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ")
to_pretty_json
, to_s : String
to_s(io : IO) : Nil
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self
from_json
, from_yaml(string_or_io : String | IO) : self from_yaml

Constructor Detail

def self.new(io : IO?, level = Severity::INFO, formatter = DEFAULT_FORMATTER, progname = "") #

Creates a new logger that will log to the given io. If io is nil then all log calls will be silently ignored.


[View source]

Instance Method Detail

def close #

Calls the close method on the object passed to initialize.


[View source]
def debug(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to DEBUG. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def debug(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to DEBUG. progname overrides a default progname set in this logger.


[View source]
def debug? #

Returns true if the logger's current severity is lower or equal to DEBUG.


[View source]
def error(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to ERROR. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def error(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to ERROR. progname overrides a default progname set in this logger.


[View source]
def error? #

Returns true if the logger's current severity is lower or equal to ERROR.


[View source]
def fatal(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to FATAL. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def fatal(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to FATAL. progname overrides a default progname set in this logger.


[View source]
def fatal? #

Returns true if the logger's current severity is lower or equal to FATAL.


[View source]
def formatter : Logger::Severity, Time, String, String, IO -> Nil #

Customizable Proc (with a reasonable default) which the Logger uses to format and print its entries.

Use this setter to provide a custom formatter. The Logger will invoke it with the following arguments:

  • severity: a Logger::Severity
  • datetime: Time, the entry's timestamp
  • progname: String, the program name, if set when the logger was built
  • message: String, the body of a message
  • io: IO, the Logger's stream, to which you must write the final output

Example:

require "logger"

logger = Logger.new(STDOUT)
logger.progname = "YodaBot"

logger.formatter = Logger::Formatter.new do |severity, datetime, progname, message, io|
  label = severity.unknown? ? "ANY" : severity.to_s
  io << label[0] << ", [" << datetime << " #" << Process.pid << "] "
  io << label.rjust(5) << " -- " << progname << ": " << message
end

logger.warn("Fear leads to anger. Anger leads to hate. Hate leads to suffering.")

# Prints to the console:
# "W, [2017-05-06 18:00:41 -0300 #11927]  WARN --
#  YodaBot: Fear leads to anger. Anger leads to hate. Hate leads to suffering."

[View source]
def formatter=(formatter) #

Customizable Proc (with a reasonable default) which the Logger uses to format and print its entries.

Use this setter to provide a custom formatter. The Logger will invoke it with the following arguments:

  • severity: a Logger::Severity
  • datetime: Time, the entry's timestamp
  • progname: String, the program name, if set when the logger was built
  • message: String, the body of a message
  • io: IO, the Logger's stream, to which you must write the final output

Example:

require "logger"

logger = Logger.new(STDOUT)
logger.progname = "YodaBot"

logger.formatter = Logger::Formatter.new do |severity, datetime, progname, message, io|
  label = severity.unknown? ? "ANY" : severity.to_s
  io << label[0] << ", [" << datetime << " #" << Process.pid << "] "
  io << label.rjust(5) << " -- " << progname << ": " << message
end

logger.warn("Fear leads to anger. Anger leads to hate. Hate leads to suffering.")

# Prints to the console:
# "W, [2017-05-06 18:00:41 -0300 #11927]  WARN --
#  YodaBot: Fear leads to anger. Anger leads to hate. Hate leads to suffering."

[View source]
def info(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to INFO. progname overrides a default progname set in this logger.


[View source]
def info(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to INFO. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def info? #

Returns true if the logger's current severity is lower or equal to INFO.


[View source]
def level : Severity #

[View source]
def level=(level : Severity) #

[View source]
def log(severity, message, progname = nil) #

Logs message if severity is higher or equal with the logger's current severity. progname overrides a default progname set in this logger.


[View source]
def log(severity, progname = nil, &) #

Logs the message as returned from the given block if severity is higher or equal with the loggers current severity. The block is not run if severity is lower. progname overrides a default progname set in this logger.


[View source]
def progname : String #

[View source]
def progname=(progname : String) #

[View source]
def unknown(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to UNKNOWN. progname overrides a default progname set in this logger.


[View source]
def unknown(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to UNKNOWN. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def unknown? #

Returns true if the logger's current severity is lower or equal to UNKNOWN.


[View source]
def warn(progname = nil, &) #

Logs the message as returned from the given block if the logger's current severity is lower or equal to WARN. The block is not run if the severity is higher. progname overrides a default progname set in this logger.


[View source]
def warn(message, progname = nil) #

Logs message if the logger's current severity is lower or equal to WARN. progname overrides a default progname set in this logger.


[View source]
def warn? #

Returns true if the logger's current severity is lower or equal to WARN.


[View source]