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. -
#with_level(severity, &block) ⇒ Object
Adjust the log level during the block execution for the current Fiber only.
Methods included from Severity
coerce, 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.
460 461 462 |
# File 'lib/lumberjack/logger.rb', line 460 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.
417 418 419 |
# File 'lib/lumberjack/logger.rb', line 417 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.
229 230 231 232 233 234 235 236 237 238 239 |
# File 'lib/lumberjack/logger.rb', line 229 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.
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 218 219 220 221 |
# File 'lib/lumberjack/logger.rb', line 188 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.
255 256 257 258 259 |
# File 'lib/lumberjack/logger.rb', line 255 def close flush device.close if device.respond_to?(:close) @closed = true end |
#closed? ⇒ Boolean
Returns true
if the logging device is closed.
264 265 266 |
# File 'lib/lumberjack/logger.rb', line 264 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.
383 384 385 |
# File 'lib/lumberjack/logger.rb', line 383 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.
397 398 399 |
# File 'lib/lumberjack/logger.rb', line 397 def debug! self.level = DEBUG end |
#debug? ⇒ Boolean
Return true
if DEBUG
messages are being logged.
390 391 392 |
# File 'lib/lumberjack/logger.rb', line 390 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.
308 309 310 |
# File 'lib/lumberjack/logger.rb', line 308 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.
322 323 324 |
# File 'lib/lumberjack/logger.rb', line 322 def error! self.level = ERROR end |
#error? ⇒ Boolean
Return true
if ERROR
messages are being logged.
315 316 317 |
# File 'lib/lumberjack/logger.rb', line 315 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.
283 284 285 |
# File 'lib/lumberjack/logger.rb', line 283 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.
297 298 299 |
# File 'lib/lumberjack/logger.rb', line 297 def fatal! self.level = FATAL end |
#fatal? ⇒ Boolean
Return true
if FATAL
messages are being logged.
290 291 292 |
# File 'lib/lumberjack/logger.rb', line 290 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.
246 247 248 249 250 |
# File 'lib/lumberjack/logger.rb', line 246 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.
145 146 147 148 149 150 151 152 |
# File 'lib/lumberjack/logger.rb', line 145 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.
138 139 140 |
# File 'lib/lumberjack/logger.rb', line 138 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.
358 359 360 |
# File 'lib/lumberjack/logger.rb', line 358 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.
372 373 374 |
# File 'lib/lumberjack/logger.rb', line 372 def info! self.level = INFO end |
#info? ⇒ Boolean
Return true
if INFO
messages are being logged.
365 366 367 |
# File 'lib/lumberjack/logger.rb', line 365 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 |
# File 'lib/lumberjack/logger.rb', line 120 def level=(value) @level = Severity.coerce(value) 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.
493 494 495 496 497 498 499 500 |
# File 'lib/lumberjack/logger.rb', line 493 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.
271 272 273 274 |
# File 'lib/lumberjack/logger.rb', line 271 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.
449 450 451 452 453 454 455 |
# File 'lib/lumberjack/logger.rb', line 449 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.
433 434 435 436 437 438 439 440 441 442 |
# File 'lib/lumberjack/logger.rb', line 433 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.
472 473 474 475 476 477 478 479 480 481 482 483 484 485 |
# File 'lib/lumberjack/logger.rb', line 472 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”]`.
163 164 165 166 |
# File 'lib/lumberjack/logger.rb', line 163 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.
506 507 508 509 510 511 512 513 514 |
# File 'lib/lumberjack/logger.rb', line 506 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.
409 410 411 |
# File 'lib/lumberjack/logger.rb', line 409 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.
521 522 523 524 525 526 527 528 529 530 531 532 533 534 |
# File 'lib/lumberjack/logger.rb', line 521 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.
333 334 335 |
# File 'lib/lumberjack/logger.rb', line 333 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.
347 348 349 |
# File 'lib/lumberjack/logger.rb', line 347 def warn! self.level = WARN end |
#warn? ⇒ Boolean
Return true
if WARN
messages are being logged.
340 341 342 |
# File 'lib/lumberjack/logger.rb', line 340 def warn? level <= WARN end |