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
The device being written to.
-
#last_flushed_at ⇒ Object
readonly
The time that the device was last flushed.
-
#progname ⇒ String
Get the program name associated with log messages.
-
#silencer ⇒ Object
Set
silencer
to false to disable silencing the log. -
#tag_formatter ⇒ Object
The TagFormatter used for formatting tags for output.
Instance Method Summary collapse
-
#<<(msg) ⇒ void
Add a message when the severity is not known.
-
#add(severity, message = nil, progname = nil, &block) ⇒ void
(also: #log)
::Logger compatible method to add a log entry.
-
#add_entry(severity, message, progname = nil, tags = nil) ⇒ void
Add a message to the log with a given severity.
-
#close ⇒ void
Close the logging device.
-
#closed? ⇒ Boolean
Returns
true
if the logging device is closed. -
#datetime_format ⇒ String?
Get the timestamp format on the device if it has one.
-
#datetime_format=(format) ⇒ void
Set the timestamp format on the device if it is supported.
-
#debug(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log a
DEBUG
message. -
#debug! ⇒ void
Set the log level to debug.
-
#debug? ⇒ Boolean
Return
true
ifDEBUG
messages are being logged. -
#error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log an
ERROR
message. -
#error! ⇒ void
Set the log level to error.
-
#error? ⇒ Boolean
Return
true
ifERROR
messages are being logged. -
#fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log a
FATAL
message. -
#fatal! ⇒ void
Set the log level to fatal.
-
#fatal? ⇒ Boolean
Return
true
ifFATAL
messages are being logged. -
#flush ⇒ void
Flush the logging device.
-
#formatter ⇒ Lumberjack::Formatter
Get the Lumberjack::Formatter used to format objects for logging as messages.
-
#formatter=(value) ⇒ void
Set the Lumberjack::Formatter used to format objects for logging as messages.
-
#info(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log an
INFO
message. -
#info! ⇒ void
Set the log level to info.
-
#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 ⇒ Integer
(also: #sev_threshold)
Get the level of severity of entries that are logged.
-
#level=(value) ⇒ void
(also: #sev_threshold=)
Set the log level using either an integer level like Logger::INFO or a label like :info or “info”.
-
#remove_tag(*tag_names) ⇒ void
Remove a tag from the current tag context.
-
#reopen(logdev = nil) ⇒ Object
Reopen the logging device.
-
#set_progname(value, &block) ⇒ void
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.
-
#tag(tags, &block) ⇒ void
Set a hash of tags on logger.
-
#tagged_logger! ⇒ Lumberjack::Logger
Enable this logger to function like an ActiveSupport::TaggedLogger.
-
#tags ⇒ Hash
Return all tags in scope on the logger including global tags set on the Lumberjack context, tags set on the logger, and tags set on the current block for the logger.
-
#unknown(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log a message when the severity is not known.
-
#untagged(&block) ⇒ void
Remove all tags on the current logger and logging context within a block.
-
#warn(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
Log a
WARN
message. -
#warn! ⇒ void
Set the log level to warn.
-
#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.
-
:formatter - The formatter to use for outputting messages to the log.
-
:datetime_format - The format to use for log timestamps.
-
:tag_formatter - The TagFormatter to use for formatting tags.
-
: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.
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# File 'lib/lumberjack/logger.rb', line 69 def initialize(device = $stdout, = {}) = .dup self.level = .delete(:level) || INFO self.progname = .delete(:progname) max_flush_seconds = .delete(:flush_seconds).to_f @device = open_device(device, ) if device self.formatter = ([:formatter] || Formatter.new) @tag_formatter = ([:tag_formatter] || TagFormatter.new) time_format = ([:datetime_format] || [:time_format]) self.datetime_format = time_format if time_format @last_flushed_at = Time.now @silencer = true @tags = {} @closed = false create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0 end |
Instance Attribute Details
#device ⇒ Object
The device being written to
40 41 42 |
# File 'lib/lumberjack/logger.rb', line 40 def device @device end |
#last_flushed_at ⇒ Object (readonly)
The time that the device was last flushed.
31 32 33 |
# File 'lib/lumberjack/logger.rb', line 31 def last_flushed_at @last_flushed_at end |
#progname ⇒ String
Get the program name associated with log messages.
456 457 458 |
# File 'lib/lumberjack/logger.rb', line 456 def progname thread_local_value(:lumberjack_logger_progname) || @progname end |
#silencer ⇒ Object
Set silencer
to false to disable silencing the log.
34 35 36 |
# File 'lib/lumberjack/logger.rb', line 34 def silencer @silencer end |
#tag_formatter ⇒ Object
The TagFormatter used for formatting tags for output
43 44 45 |
# File 'lib/lumberjack/logger.rb', line 43 def tag_formatter @tag_formatter end |
Instance Method Details
#<<(msg) ⇒ void
This method returns an undefined value.
Add a message when the severity is not known.
413 414 415 |
# File 'lib/lumberjack/logger.rb', line 413 def <<(msg) add_entry(UNKNOWN, msg) end |
#add(severity, message = nil, progname = nil, &block) ⇒ void Also known as: log
This method returns an undefined value.
::Logger compatible method to add a log entry.
225 226 227 228 229 230 231 232 233 234 235 |
# File 'lib/lumberjack/logger.rb', line 225 def add(severity, = nil, progname = nil, &block) if .nil? if block = block else = progname progname = nil end end add_entry(severity, , progname) end |
#add_entry(severity, message, progname = nil, tags = nil) ⇒ void
This method returns an undefined value.
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.
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 |
# File 'lib/lumberjack/logger.rb', line 184 def add_entry(severity, , progname = nil, = nil) begin severity = Severity.label_to_level(severity) unless severity.is_a?(Integer) return true unless device && severity && severity >= level return true if Thread.current[:lumberjack_logging] Thread.current[:lumberjack_logging] = true time = Time.now = .call if .is_a?(Proc) = formatter.format() progname ||= self.progname = self. = nil unless .is_a?(Hash) if .empty? = Tags.stringify_keys() unless .nil? else = if .nil? .dup else .merge(Tags.stringify_keys()) end end = Tags.() = tag_formatter.format() if tag_formatter entry = LogEntry.new(time, severity, , progname, $$, ) write_to_device(entry) ensure Thread.current[:lumberjack_logging] = nil end true end |
#close ⇒ void
This method returns an undefined value.
Close the logging device.
251 252 253 254 255 |
# File 'lib/lumberjack/logger.rb', line 251 def close flush device.close if device.respond_to?(:close) @closed = true end |
#closed? ⇒ Boolean
Returns true
if the logging device is closed.
260 261 262 |
# File 'lib/lumberjack/logger.rb', line 260 def closed? @closed end |
#datetime_format ⇒ String?
Get the timestamp format on the device if it has one.
91 92 93 |
# File 'lib/lumberjack/logger.rb', line 91 def datetime_format device.datetime_format if device.respond_to?(:datetime_format) end |
#datetime_format=(format) ⇒ void
This method returns an undefined value.
Set the timestamp format on the device if it is supported.
99 100 101 102 103 |
# File 'lib/lumberjack/logger.rb', line 99 def datetime_format=(format) if device.respond_to?(:datetime_format=) device.datetime_format = format end end |
#debug(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
Log a DEBUG
message. The message can be passed in either the message
argument or in a block.
379 380 381 |
# File 'lib/lumberjack/logger.rb', line 379 def debug( = nil, = nil, &block) call_add_entry(DEBUG, , , &block) end |
#debug! ⇒ void
This method returns an undefined value.
Set the log level to debug.
393 394 395 |
# File 'lib/lumberjack/logger.rb', line 393 def debug! self.level = DEBUG end |
#debug? ⇒ Boolean
Return true
if DEBUG
messages are being logged.
386 387 388 |
# File 'lib/lumberjack/logger.rb', line 386 def debug? level <= DEBUG end |
#error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
Log an ERROR
message. The message can be passed in either the message
argument or in a block.
304 305 306 |
# File 'lib/lumberjack/logger.rb', line 304 def error( = nil, = nil, &block) call_add_entry(ERROR, , , &block) end |
#error! ⇒ void
This method returns an undefined value.
Set the log level to error.
318 319 320 |
# File 'lib/lumberjack/logger.rb', line 318 def error! self.level = ERROR end |
#error? ⇒ Boolean
Return true
if ERROR
messages are being logged.
311 312 313 |
# File 'lib/lumberjack/logger.rb', line 311 def error? level <= ERROR end |
#fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
Log a FATAL
message. The message can be passed in either the message
argument or in a block.
279 280 281 |
# File 'lib/lumberjack/logger.rb', line 279 def fatal( = nil, = nil, &block) call_add_entry(FATAL, , , &block) end |
#fatal! ⇒ void
This method returns an undefined value.
Set the log level to fatal.
293 294 295 |
# File 'lib/lumberjack/logger.rb', line 293 def fatal! self.level = FATAL end |
#fatal? ⇒ Boolean
Return true
if FATAL
messages are being logged.
286 287 288 |
# File 'lib/lumberjack/logger.rb', line 286 def fatal? level <= FATAL end |
#flush ⇒ void
This method returns an undefined value.
Flush the logging device. Messages are not guaranteed to be written until this method is called.
242 243 244 245 246 |
# File 'lib/lumberjack/logger.rb', line 242 def flush device.flush @last_flushed_at = Time.now nil end |
#formatter ⇒ Lumberjack::Formatter
Get the Lumberjack::Formatter used to format objects for logging as messages.
141 142 143 144 145 146 147 148 |
# File 'lib/lumberjack/logger.rb', line 141 def formatter if respond_to?(:tagged) # Wrap in an object that supports ActiveSupport::TaggedLogger API TaggedLoggerSupport::Formatter.new(logger: self, formatter: @_formatter) else @_formatter end end |
#formatter=(value) ⇒ void
This method returns an undefined value.
Set the Lumberjack::Formatter used to format objects for logging as messages.
134 135 136 |
# File 'lib/lumberjack/logger.rb', line 134 def formatter=(value) @_formatter = (value.is_a?(TaggedLoggerSupport::Formatter) ? value.__formatter : value) end |
#info(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
Log an INFO
message. The message can be passed in either the message
argument or in a block.
354 355 356 |
# File 'lib/lumberjack/logger.rb', line 354 def info( = nil, = nil, &block) call_add_entry(INFO, , , &block) end |
#info! ⇒ void
This method returns an undefined value.
Set the log level to info.
368 369 370 |
# File 'lib/lumberjack/logger.rb', line 368 def info! self.level = INFO end |
#info? ⇒ Boolean
Return true
if INFO
messages are being logged.
361 362 363 |
# File 'lib/lumberjack/logger.rb', line 361 def info? level <= INFO end |
#level ⇒ Integer Also known as: sev_threshold
Get the level of severity of entries that are logged. Entries with a lower severity level will be ignored.
109 110 111 |
# File 'lib/lumberjack/logger.rb', line 109 def level thread_local_value(:lumberjack_logger_level) || @level end |
#level=(value) ⇒ void Also known as: sev_threshold=
This method returns an undefined value.
Set the log level using either an integer level like Logger::INFO or a label like :info or “info”
120 121 122 123 124 125 126 |
# File 'lib/lumberjack/logger.rb', line 120 def level=(value) @level = if value.is_a?(Integer) value else Severity.label_to_level(value) end end |
#remove_tag(*tag_names) ⇒ void
This method returns an undefined value.
Remove a tag from the current tag context. If this is called inside a block to a call to ‘tag`, the tags will only be removed for the duration of that block. Otherwise they will be removed from the global tags.
489 490 491 492 493 494 495 496 |
# File 'lib/lumberjack/logger.rb', line 489 def remove_tag(*tag_names) = thread_local_value(:lumberjack_logger_tags) if tag_names.each { |name| .delete(name.to_s) } else tag_names.each { |name| @tags.delete(name.to_s) } end end |
#reopen(logdev = nil) ⇒ Object
Reopen the logging device.
267 268 269 270 |
# File 'lib/lumberjack/logger.rb', line 267 def reopen(logdev = nil) @closed = false device.reopen(logdev) if device.respond_to?(:reopen) end |
#set_progname(value, &block) ⇒ void
This method returns an undefined value.
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.
445 446 447 448 449 450 451 |
# File 'lib/lumberjack/logger.rb', line 445 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.
429 430 431 432 433 434 435 436 437 438 |
# File 'lib/lumberjack/logger.rb', line 429 def silence(temporary_level = ERROR, &block) if silencer unless temporary_level.is_a?(Integer) temporary_level = Severity.label_to_level(temporary_level) end push_thread_local_value(:lumberjack_logger_level, temporary_level, &block) else yield end end |
#tag(tags, &block) ⇒ void
This method returns an undefined value.
Set a hash of tags on logger. If a block is given, the tags will only be set for the duration of the block. If this method is called inside such a block, the tags will only be defined on the tags in that block. When the parent block exits, all the tags will be reverted. If there is no block, then the tags will be defined as global and apply to all log statements.
468 469 470 471 472 473 474 475 476 477 478 479 480 481 |
# File 'lib/lumberjack/logger.rb', line 468 def tag(, &block) = Tags.stringify_keys() = thread_local_value(:lumberjack_logger_tags) if block = ( ? .merge() : .dup) push_thread_local_value(:lumberjack_logger_tags, , &block) elsif .merge!() nil else @tags.merge!() nil end end |
#tagged_logger! ⇒ Lumberjack::Logger
Enable this logger to function like an ActiveSupport::TaggedLogger. This will make the logger API compatible with ActiveSupport::TaggedLogger and is provided as a means of compatibility with other libraries that assume they can call the ‘tagged` method on a logger to add tags.
The tags added with this method are just strings so they are stored in the logger tags in an array under the “tagged” tag. So calling ‘logger.tagged(“foo”, “bar”)` will result in tags `=> [“foo”, “bar”]`.
159 160 161 162 |
# File 'lib/lumberjack/logger.rb', line 159 def tagged_logger! extend(TaggedLoggerSupport) self end |
#tags ⇒ Hash
Return all tags in scope on the logger including global tags set on the Lumberjack context, tags set on the logger, and tags set on the current block for the logger.
502 503 504 505 506 507 508 509 510 |
# File 'lib/lumberjack/logger.rb', line 502 def = {} = Lumberjack. .merge!() if && !.empty? .merge!(@tags) if !@tags.empty? && !thread_local_value(:lumberjack_logger_untagged) = thread_local_value(:lumberjack_logger_tags) .merge!() if && !.empty? end |
#unknown(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
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.
405 406 407 |
# File 'lib/lumberjack/logger.rb', line 405 def unknown( = nil, = nil, &block) call_add_entry(UNKNOWN, , , &block) end |
#untagged(&block) ⇒ void
This method returns an undefined value.
Remove all tags on the current logger and logging context within a block. You can still set new block scoped tags within theuntagged block and provide tags on individual log methods.
517 518 519 520 521 522 523 524 525 526 527 528 529 530 |
# File 'lib/lumberjack/logger.rb', line 517 def untagged(&block) Lumberjack.use_context(nil) do = thread_local_value(:lumberjack_logger_tags) untagged = thread_local_value(:lumberjack_logger_untagged) begin set_thread_local_value(:lumberjack_logger_untagged, true) set_thread_local_value(:lumberjack_logger_tags, nil) tag({}, &block) ensure set_thread_local_value(:lumberjack_logger_untagged, untagged) set_thread_local_value(:lumberjack_logger_tags, ) end end end |
#warn(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ void
This method returns an undefined value.
Log a WARN
message. The message can be passed in either the message
argument or in a block.
329 330 331 |
# File 'lib/lumberjack/logger.rb', line 329 def warn( = nil, = nil, &block) call_add_entry(WARN, , , &block) end |
#warn! ⇒ void
This method returns an undefined value.
Set the log level to warn.
343 344 345 |
# File 'lib/lumberjack/logger.rb', line 343 def warn! self.level = WARN end |
#warn? ⇒ Boolean
Return true
if WARN
messages are being logged.
336 337 338 |
# File 'lib/lumberjack/logger.rb', line 336 def warn? level <= WARN end |