Class: Lumberjack::Logger
- Inherits:
-
Object
- Object
- Lumberjack::Logger
- Includes:
- Severity
- Defined in:
- lib/lumberjack/logger.rb
Overview
Logger is a thread safe logging object. It has a compatible API with the Ruby standard library Logger class, the Log4r gem, and ActiveSupport::BufferedLogger.
Example
logger = Lumberjack::Logger.new
logger.info("Starting processing")
logger.debug("Processing options #{.inspect}")
logger.fatal("OMG the application is on fire!")
Log entries are written to a logging Device if their severity meets or exceeds the log level.
Devices may use buffers internally and the log entries are not guaranteed to be written until you call the flush
method. Sometimes this can result in problems when trying to track down extraordinarily long running sections of code since it is likely that none of the messages logged before the long running code will appear in the log until the entire process finishes. You can set the :flush_seconds
option on the constructor to force the device to be flushed periodically. This will create a new monitoring thread, but its use is highly recommended.
Each log entry records the log message and severity along with the time it was logged, the program name, process id, and unit of work id. The message will be converted to a string, but otherwise, it is up to the device how these values are recorded. Messages are converted to strings using a Formatter associated with the logger.
Constant Summary
Constants included from Severity
Severity::DEBUG, Severity::ERROR, Severity::FATAL, Severity::INFO, Severity::SEVERITY_LABELS, Severity::UNKNOWN, Severity::WARN
Instance Attribute Summary collapse
-
#device ⇒ Object
readonly
The device being written to.
-
#formatter ⇒ Object
readonly
The Formatter object used to convert messages into strings.
-
#last_flushed_at ⇒ Object
readonly
The time that the device was last flushed.
-
#progname ⇒ Object
Get the program name associated with log messages.
-
#silencer ⇒ Object
Set
silencer
to false to disable silencing the log.
Instance Method Summary collapse
-
#add(severity, message = nil, progname = nil) ⇒ Object
(also: #log)
Add a message to the log with a given severity.
-
#close ⇒ Object
Close the logging device.
-
#debug(message = nil, progname = nil, &block) ⇒ Object
Log a
DEBUG
message. -
#debug? ⇒ Boolean
Return
true
ifDEBUG
messages are being logged. -
#error(message = nil, progname = nil, &block) ⇒ Object
Log an
ERROR
message. -
#error? ⇒ Boolean
Return
true
ifERROR
messages are being logged. -
#fatal(message = nil, progname = nil, &block) ⇒ Object
Log a
FATAL
message. -
#fatal? ⇒ Boolean
Return
true
ifFATAL
messages are being logged. -
#flush ⇒ Object
Flush the logging device.
-
#info(message = nil, progname = nil, &block) ⇒ Object
Log an
INFO
message. -
#info? ⇒ Boolean
Return
true
ifINFO
messages are being logged. -
#initialize(device = STDOUT, options = {}) ⇒ Logger
constructor
Create a new logger to log to a Device.
-
#level ⇒ Object
Get the level of severity of entries that are logged.
-
#level=(severity) ⇒ Object
Set the minimum level of severity of messages to log.
-
#set_progname(value, &block) ⇒ Object
Set the program name that is associated with log messages.
-
#silence(temporary_level = ERROR, &block) ⇒ Object
Silence the logger by setting a new log level inside a block.
-
#unknown(message = nil, progname = nil, &block) ⇒ Object
(also: #<<)
Log a message when the severity is not known.
-
#warn(message = nil, progname = nil, &block) ⇒ Object
Log a
WARN
message. -
#warn? ⇒ Boolean
Return
true
ifWARN
messages are being logged.
Methods included from Severity
label_to_level, level_to_label
Constructor Details
#initialize(device = STDOUT, options = {}) ⇒ Logger
Create a new logger to log to a Device.
The device
argument can be in any one of several formats.
If it is a Device object, that object will be used. If it has a write
method, it will be wrapped in a Device::Writer class. If it is :null
, it will be a Null device that won’t record any output. Otherwise, it will be assumed to be file path and wrapped in a Device::LogFile class.
This method can take the following options:
-
:level
- The logging level below which messages will be ignored. -
:progname
- The name of the program that will be recorded with each log entry. -
:flush_seconds
- The maximum number of seconds between flush calls. -
:roll
- If the log device is a file path, it will be a Device::DateRollingLogFile if this is set. -
:max_size
- If the log device is a file path, it will be a Device::SizeRollingLogFile if this is set.
All other options are passed to the device constuctor.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 |
# File 'lib/lumberjack/logger.rb', line 61 def initialize(device = STDOUT, = {}) @thread_settings = {} = .dup self.level = .delete(:level) || INFO self.progname = .delete(:progname) max_flush_seconds = .delete(:flush_seconds).to_f @device = open_device(device, ) @_formatter = Formatter.new @lock = Mutex.new @last_flushed_at = Time.now @silencer = true create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0 end |
Instance Attribute Details
#device ⇒ Object (readonly)
The device being written to.
38 39 40 |
# File 'lib/lumberjack/logger.rb', line 38 def device @device end |
#formatter ⇒ Object (readonly)
The Formatter object used to convert messages into strings.
29 30 31 |
# File 'lib/lumberjack/logger.rb', line 29 def formatter @formatter end |
#last_flushed_at ⇒ Object (readonly)
The time that the device was last flushed.
32 33 34 |
# File 'lib/lumberjack/logger.rb', line 32 def last_flushed_at @last_flushed_at end |
#progname ⇒ Object
Get the program name associated with log messages.
236 237 238 |
# File 'lib/lumberjack/logger.rb', line 236 def progname thread_local_value(:lumberjack_logger_progname) || @progname end |
#silencer ⇒ Object
Set silencer
to false to disable silencing the log.
41 42 43 |
# File 'lib/lumberjack/logger.rb', line 41 def silencer @silencer end |
Instance Method Details
#add(severity, message = nil, progname = nil) ⇒ Object Also known as: log
Add a message to the log with a given severity. The message can be either passed in the message
argument or supplied with a block. This method is not normally called. Instead call one of the helper functions fatal
, error
, warn
, info
, or debug
.
The severity can be passed in either as one of the Severity constants, or as a Severity label.
Example
logger.add(Lumberjack::Severity::ERROR, exception)
logger.add(Lumberjack::Severity::INFO, "Request completed")
logger.add(:warn, "Request took a long time")
logger.add(Lumberjack::Severity::DEBUG){"Start processing with options #{.inspect}"}
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 |
# File 'lib/lumberjack/logger.rb', line 98 def add(severity, = nil, progname = nil) severity = Severity.label_to_level(severity) if severity.is_a?(String) || severity.is_a?(Symbol) return unless severity && severity >= level time = Time.now if .nil? if block_given? = yield else = progname progname = nil end end = @_formatter.format() progname ||= self.progname entry = LogEntry.new(time, severity, , progname, $$, Lumberjack.unit_of_work_id) begin device.write(entry) rescue => e $stderr.puts("#{e.class.name}: #{e.}#{' at ' + e.backtrace.first if e.backtrace}") $stderr.puts(entry.to_s) end nil end |
#close ⇒ Object
Close the logging device.
136 137 138 139 |
# File 'lib/lumberjack/logger.rb', line 136 def close flush @device.close if @device.respond_to?(:close) end |
#debug(message = nil, progname = nil, &block) ⇒ Object
Log a DEBUG
message. The message can be passed in either the message
argument or in a block.
182 183 184 |
# File 'lib/lumberjack/logger.rb', line 182 def debug( = nil, progname = nil, &block) add(DEBUG, , progname, &block) end |
#debug? ⇒ Boolean
Return true
if DEBUG
messages are being logged.
187 188 189 |
# File 'lib/lumberjack/logger.rb', line 187 def debug? level <= DEBUG end |
#error(message = nil, progname = nil, &block) ⇒ Object
Log an ERROR
message. The message can be passed in either the message
argument or in a block.
152 153 154 |
# File 'lib/lumberjack/logger.rb', line 152 def error( = nil, progname = nil, &block) add(ERROR, , progname, &block) end |
#error? ⇒ Boolean
Return true
if ERROR
messages are being logged.
157 158 159 |
# File 'lib/lumberjack/logger.rb', line 157 def error? level <= ERROR end |
#fatal(message = nil, progname = nil, &block) ⇒ Object
Log a FATAL
message. The message can be passed in either the message
argument or in a block.
142 143 144 |
# File 'lib/lumberjack/logger.rb', line 142 def fatal( = nil, progname = nil, &block) add(FATAL, , progname, &block) end |
#fatal? ⇒ Boolean
Return true
if FATAL
messages are being logged.
147 148 149 |
# File 'lib/lumberjack/logger.rb', line 147 def fatal? level <= FATAL end |
#flush ⇒ Object
Flush the logging device. Messages are not guaranteed to be written until this method is called.
129 130 131 132 133 |
# File 'lib/lumberjack/logger.rb', line 129 def flush device.flush @last_flushed_at = Time.now nil end |
#info(message = nil, progname = nil, &block) ⇒ Object
Log an INFO
message. The message can be passed in either the message
argument or in a block.
172 173 174 |
# File 'lib/lumberjack/logger.rb', line 172 def info( = nil, progname = nil, &block) add(INFO, , progname, &block) end |
#info? ⇒ Boolean
Return true
if INFO
messages are being logged.
177 178 179 |
# File 'lib/lumberjack/logger.rb', line 177 def info? level <= INFO end |
#level ⇒ Object
Get the level of severity of entries that are logged. Entries with a lower severity level will be ignored.
80 81 82 |
# File 'lib/lumberjack/logger.rb', line 80 def level thread_local_value(:lumberjack_logger_level) || @level end |
#level=(severity) ⇒ Object
Set the minimum level of severity of messages to log.
200 201 202 203 204 205 206 |
# File 'lib/lumberjack/logger.rb', line 200 def level=(severity) if severity.is_a?(Fixnum) @level = severity else @level = Severity.label_to_level(severity) end end |
#set_progname(value, &block) ⇒ Object
Set the program name that is associated with log messages. If a block is given, the program name will be valid only within the block.
227 228 229 230 231 232 233 |
# File 'lib/lumberjack/logger.rb', line 227 def set_progname(value, &block) if block push_thread_local_value(:lumberjack_logger_progname, value, &block) else self.progname = value end end |
#silence(temporary_level = ERROR, &block) ⇒ Object
Silence the logger by setting a new log level inside a block. By default, only ERROR
or FATAL
messages will be logged.
Example
logger.level = Lumberjack::Severity::INFO
logger.silence do
do_something # Log level inside the block is +ERROR+
end
217 218 219 220 221 222 223 |
# File 'lib/lumberjack/logger.rb', line 217 def silence(temporary_level = ERROR, &block) if silencer push_thread_local_value(:lumberjack_logger_level, temporary_level, &block) else yield end end |
#unknown(message = nil, progname = nil, &block) ⇒ Object Also known as: <<
Log a message when the severity is not known. Unknown messages will always appear in the log. The message can be passed in either the message
argument or in a block.
193 194 195 |
# File 'lib/lumberjack/logger.rb', line 193 def unknown( = nil, progname = nil, &block) add(UNKNOWN, , progname, &block) end |
#warn(message = nil, progname = nil, &block) ⇒ Object
Log a WARN
message. The message can be passed in either the message
argument or in a block.
162 163 164 |
# File 'lib/lumberjack/logger.rb', line 162 def warn( = nil, progname = nil, &block) add(WARN, , progname, &block) end |
#warn? ⇒ Boolean
Return true
if WARN
messages are being logged.
167 168 169 |
# File 'lib/lumberjack/logger.rb', line 167 def warn? level <= WARN end |