Class: OptionalLogger::Logger

Inherits:
Object
  • Object
show all
Defined in:
lib/optional_logger/logger.rb

Overview

Proxy logger to handle making the proxied logger optional

The original intent for this optional proxy logger was specifically to be used inside of gems. This would enable them to receive a logger from the parenting application/gem and log within their gem without having to worry about spreading conditionals all over their gem.

Instance Method Summary collapse

Constructor Details

#initialize(logger) ⇒ Object

Construct an instance of the proxy logger

Parameters:



16
17
18
 
# File 'lib/optional_logger/logger.rb', line 16

def initialize(logger)
  @logger = logger
end

Instance Method Details

#add(severity, message = nil, progname_or_message = nil, &block) ⇒ Object Also known as: log

Log a message at the given level if the logger is present

This isn’t generally a recommended method to use while logging in your libraries. Instead see #debug, #info, #warn, #error, #fatal, and #unknown as they simplify messaging considerably.

If you don’t want to use the recommended methods and want more control for some reason. There are a few ways to log a message depending on your usecase.

The first is probably the most generally useful, which is logging messages that aren’t costly to build. This is accomplished as follows:

add(::Logger::INFO, 'some message', nil)

The second is for use cases in which it is costly to build the log message as it avoids executing the block until the logger knows that the message level will be displayed. If the message level would not be displayed then the block is not executed, saving the performance cost of building the message.

add(::Logger::INFO) { 'some expensive message' }

The third gives you the benefits of preventing uneeded expensive messages but also allows you to override the program name that will be prefixed on that log message. This is accomplished as follows.

add(::Logger::INFO, nil, 'overridden progname') { 'some expensive message' }

It is important to realize that if the wrapped logger is nil then this method will simply do nothing.

Parameters:

  • severity —

    ::Logger::DEBUG, ::Logger::INFO, ::Logger::WARN, ::Logger::ERROR, ::Logger::FATAL, ::Logger::UNKNOWN

  • message (defaults to: nil) —

    the optional message to log

  • progname_or_message (defaults to: nil) —

    the optional program name or message, if message is nil, and a block is NOT provided, then progname_or_message is treated as a message rather than progname

  • block —

    the block to evaluate and yield a message, generally useful preventing building of expensive messages when message of that level aren’t allowed



67
68
69
 
# File 'lib/optional_logger/logger.rb', line 67

def add(severity, message = nil, progname_or_message = nil, &block)
  @logger.add(severity, message, progname_or_message, &block) if @logger
end

#debug(progname_or_message = nil, &block) ⇒ Object

Log a message at the debug level if the logger is present

See #info for details on specifics around various scenarios



114
115
116
 
# File 'lib/optional_logger/logger.rb', line 114

def debug(progname_or_message = nil, &block)
  add(::Logger::DEBUG, nil, progname_or_message, &block)
end

#debug? ⇒ Boolean

Check if debug level messages are allowed by loggers current configuration

Returns:

  • (Boolean) —

    true if the current severity level allows for the printing of debug messages and false otherwise. It will also return false if there is no logger present.



164
165
166
167
 
# File 'lib/optional_logger/logger.rb', line 164

def debug?
  return @logger.debug? if @logger
  false
end

#error(progname_or_message = nil, &block) ⇒ Object

Log a message at the error level if the logger is present

See #info for details on specifics around various scenarios



121
122
123
 
# File 'lib/optional_logger/logger.rb', line 121

def error(progname_or_message = nil, &block)
  add(::Logger::ERROR, nil, progname_or_message, &block)
end

#error? ⇒ Boolean

Check if error level messages are allowed by loggers current configuration

Returns:

  • (Boolean) —

    true if the current severity level allows for the printing of error messages and false otherwise. It will also return false if there is no logger present.



184
185
186
187
 
# File 'lib/optional_logger/logger.rb', line 184

def error?
  return @logger.error? if @logger
  false
end

#fatal(progname_or_message = nil, &block) ⇒ Object

Log a message at the fatal level if the logger is present

See #info for details on specifics around various scenarios



128
129
130
 
# File 'lib/optional_logger/logger.rb', line 128

def fatal(progname_or_message = nil, &block)
  add(::Logger::FATAL, nil, progname_or_message, &block)
end

#fatal? ⇒ Boolean

Check if fatal level messages are allowed by loggers current configuration

Returns:

  • (Boolean) —

    true if the current severity level allows for the printing of fatal messages and false otherwise. It will also return false if there is no logger present.



174
175
176
177
 
# File 'lib/optional_logger/logger.rb', line 174

def fatal?
  return @logger.fatal? if @logger
  false
end

#info(progname_or_message = nil, &block) ⇒ Object

Log a message at the info level if the logger is present

There are a few ways to log a message depending on your usecase.

The first is probably the most generally useful, which is logging messages that aren’t costly to build. This is accomplished as follows:

info('some message')

The second is for use cases in which it is costly to build the log message as it avoids executing the block until the logger knows that the message level will be displayed. If the message level would not be displayed then the block is not executed, saving the performance cost of building the message.

info { 'some expensive message' }

The third gives you the benefits of preventing uneeded expensive messages but also allows you to override the program name that will be prefixed on that log message. This is accomplished as follows.

info('overridden progname') { 'some expensive message' }

It is important to realize that if the wrapped logger is nil then this method will simply do nothing.

Parameters:

  • progname_or_message (defaults to: nil) —

    the progname or message depending on scenario

  • block —

    the optional block depending on scenario



100
101
102
 
# File 'lib/optional_logger/logger.rb', line 100

def info(progname_or_message = nil, &block)
  add(::Logger::INFO, nil, progname_or_message, &block)
end

#info? ⇒ Boolean

Check if info level messages are allowed by loggers current configuration

Returns:

  • (Boolean) —

    true if the current severity level allows for the printing of info messages and false otherwise. It will also return false if there is no logger present.



144
145
146
147
 
# File 'lib/optional_logger/logger.rb', line 144

def info?
  return @logger.info? if @logger
  false
end

#unknown(progname_or_message = nil, &block) ⇒ Object

Log a message at the unknown level if the logger is present

See #info for details on specifics around various scenarios



135
136
137
 
# File 'lib/optional_logger/logger.rb', line 135

def unknown(progname_or_message = nil, &block)
  add(::Logger::UNKNOWN, nil, progname_or_message, &block)
end

#warn(progname_or_message = nil, &block) ⇒ Object

Log a message at the warn level if the logger is present

See #info for details on specifics around various scenarios



107
108
109
 
# File 'lib/optional_logger/logger.rb', line 107

def warn(progname_or_message = nil, &block)
  add(::Logger::WARN, nil, progname_or_message, &block)
end

#warn? ⇒ Boolean

Check if warn level messages are allowed by loggers current configuration

Returns:

  • (Boolean) —

    true if the current severity level allows for the printing of warn messages and false otherwise. It will also return false if there is no logger present.



154
155
156
157
 
# File 'lib/optional_logger/logger.rb', line 154

def warn?
  return @logger.warn? if @logger
  false
end

#wrapped_logger ⇒ Object

Get the ruby logger instance this proxy logger wraps

Returns:

  • the wrapped ruby logger



23
24
25
 
# File 'lib/optional_logger/logger.rb', line 23

def wrapped_logger
  @logger
end