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.
-
#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
- #<<(msg) ⇒ Object
-
#add(severity, message = nil, progname = nil, &block) ⇒ Object
(also: #log)
::Logger compatible method to add a log entry.
-
#add_entry(severity, message, progname = nil, tags = nil) ⇒ Object
Add a message to the log with a given severity.
-
#close ⇒ Object
Close the logging device.
-
#datetime_format ⇒ Object
Get the timestamp format on the device if it has one.
-
#datetime_format=(format) ⇒ Object
Set the timestamp format on the device if it is supported.
-
#debug(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log a
DEBUG
message. -
#debug? ⇒ Boolean
Return
true
ifDEBUG
messages are being logged. -
#error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log an
ERROR
message. -
#error? ⇒ Boolean
Return
true
ifERROR
messages are being logged. -
#fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log a
FATAL
message. -
#fatal? ⇒ Boolean
Return
true
ifFATAL
messages are being logged. -
#flush ⇒ Object
Flush the logging device.
-
#formatter ⇒ Object
Get the Lumberjack::Formatter used to format objects for logging as messages.
-
#formatter=(value) ⇒ Object
Set the Lumberjack::Formatter used to format objects for logging as messages.
-
#info(message_or_progname_or_tags = nil, progname_or_tags = 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
(also: #sev_threshold)
Get the level of severity of entries that are logged.
-
#level=(value) ⇒ Object
(also: #sev_threshold=)
Set the log level using either an integer level like Logger::INFO or a label like :info or “info”.
- #reopen(logdev = nil) ⇒ Object
-
#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.
-
#tag(tags, &block) ⇒ Object
Set a hash of tags on logger.
-
#tags ⇒ Object
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) ⇒ Object
Log a message when the severity is not known.
-
#warn(message_or_progname_or_tags = nil, progname_or_tags = 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.
-
:formatter - The formatter to use for outputting messages to the log.
-
:datetime_format - The format to use for log timestamps.
-
: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.
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
# File 'lib/lumberjack/logger.rb', line 62 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 @_formatter = ([:formatter] || Formatter.new) time_format = ([:datetime_format] || [:time_format]) self.datetime_format = time_format if time_format @last_flushed_at = Time.now @silencer = true @tags = {} create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0 end |
Instance Attribute Details
#device ⇒ Object (readonly)
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 ⇒ Object
Get the program name associated with log messages.
284 285 286 |
# File 'lib/lumberjack/logger.rb', line 284 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 |
Instance Method Details
#<<(msg) ⇒ Object
252 253 254 |
# File 'lib/lumberjack/logger.rb', line 252 def <<(msg) add_entry(UNKNOWN, msg) end |
#add(severity, message = nil, progname = nil, &block) ⇒ Object Also known as: log
::Logger compatible method to add a log entry.
165 166 167 168 169 170 171 172 173 174 175 |
# File 'lib/lumberjack/logger.rb', line 165 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) ⇒ Object
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_entry(Logger::ERROR, exception)
logger.add_entry(Logger::INFO, "Request completed")
logger.add_entry(:warn, "Request took a long time")
logger.add_entry(Logger::DEBUG){"Start processing with options #{.inspect}"}
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 |
# File 'lib/lumberjack/logger.rb', line 135 def add_entry(severity, , progname = nil, = nil) severity = Severity.label_to_level(severity) unless severity.is_a?(Integer) return true unless @device && severity && severity >= level 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.() entry = LogEntry.new(time, severity, , progname, $$, ) write_to_device(entry) true end |
#close ⇒ Object
Close the logging device.
187 188 189 190 |
# File 'lib/lumberjack/logger.rb', line 187 def close flush @device.close if @device.respond_to?(:close) end |
#datetime_format ⇒ Object
Get the timestamp format on the device if it has one.
80 81 82 |
# File 'lib/lumberjack/logger.rb', line 80 def datetime_format @device.datetime_format if @device.respond_to?(:datetime_format) end |
#datetime_format=(format) ⇒ Object
Set the timestamp format on the device if it is supported.
85 86 87 88 89 |
# File 'lib/lumberjack/logger.rb', line 85 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) ⇒ Object
Log a DEBUG
message. The message can be passed in either the message
argument or in a block.
237 238 239 |
# File 'lib/lumberjack/logger.rb', line 237 def debug( = nil, = nil, &block) call_add_entry(DEBUG, , , &block) end |
#debug? ⇒ Boolean
Return true
if DEBUG
messages are being logged.
242 243 244 |
# File 'lib/lumberjack/logger.rb', line 242 def debug? level <= DEBUG end |
#error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log an ERROR
message. The message can be passed in either the message
argument or in a block.
207 208 209 |
# File 'lib/lumberjack/logger.rb', line 207 def error( = nil, = nil, &block) call_add_entry(ERROR, , , &block) end |
#error? ⇒ Boolean
Return true
if ERROR
messages are being logged.
212 213 214 |
# File 'lib/lumberjack/logger.rb', line 212 def error? level <= ERROR end |
#fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log a FATAL
message. The message can be passed in either the message
argument or in a block.
197 198 199 |
# File 'lib/lumberjack/logger.rb', line 197 def fatal( = nil, = nil, &block) call_add_entry(FATAL, , , &block) end |
#fatal? ⇒ Boolean
Return true
if FATAL
messages are being logged.
202 203 204 |
# File 'lib/lumberjack/logger.rb', line 202 def fatal? level <= FATAL end |
#flush ⇒ Object
Flush the logging device. Messages are not guaranteed to be written until this method is called.
180 181 182 183 184 |
# File 'lib/lumberjack/logger.rb', line 180 def flush device.flush @last_flushed_at = Time.now nil end |
#formatter ⇒ Object
Get the Lumberjack::Formatter used to format objects for logging as messages.
117 118 119 |
# File 'lib/lumberjack/logger.rb', line 117 def formatter @_formatter end |
#formatter=(value) ⇒ Object
Set the Lumberjack::Formatter used to format objects for logging as messages.
112 113 114 |
# File 'lib/lumberjack/logger.rb', line 112 def formatter=(value) @_formatter = value end |
#info(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log an INFO
message. The message can be passed in either the message
argument or in a block.
227 228 229 |
# File 'lib/lumberjack/logger.rb', line 227 def info( = nil, = nil, &block) call_add_entry(INFO, , , &block) end |
#info? ⇒ Boolean
Return true
if INFO
messages are being logged.
232 233 234 |
# File 'lib/lumberjack/logger.rb', line 232 def info? level <= INFO end |
#level ⇒ Object Also known as: sev_threshold
Get the level of severity of entries that are logged. Entries with a lower severity level will be ignored.
93 94 95 |
# File 'lib/lumberjack/logger.rb', line 93 def level thread_local_value(:lumberjack_logger_level) || @level end |
#level=(value) ⇒ Object Also known as: sev_threshold=
Set the log level using either an integer level like Logger::INFO or a label like :info or “info”
101 102 103 104 105 106 107 |
# File 'lib/lumberjack/logger.rb', line 101 def level=(value) if value.is_a?(Integer) @level = value else @level = Severity::label_to_level(value) end end |
#reopen(logdev = nil) ⇒ Object
192 193 194 |
# File 'lib/lumberjack/logger.rb', line 192 def reopen(logdev = nil) device.reopen(logdev) if device.respond_to?(:reopen) 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.
275 276 277 278 279 280 281 |
# File 'lib/lumberjack/logger.rb', line 275 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
265 266 267 268 269 270 271 |
# File 'lib/lumberjack/logger.rb', line 265 def silence(temporary_level = ERROR, &block) if silencer push_thread_local_value(:lumberjack_logger_level, temporary_level, &block) else yield end end |
#tag(tags, &block) ⇒ Object
Set a hash of tags on logger. If a block is given, the tags will only be set for the duration of the block.
290 291 292 293 294 295 296 297 298 299 |
# File 'lib/lumberjack/logger.rb', line 290 def tag(, &block) = Tags.stringify_keys() if block = thread_local_value(:lumberjack_logger_tags) value = ( ? .merge() : ) push_thread_local_value(:lumberjack_logger_tags, value, &block) else @tags.merge!() end end |
#tags ⇒ Object
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
303 304 305 306 307 308 309 310 311 |
# File 'lib/lumberjack/logger.rb', line 303 def = {} = Lumberjack. .merge!() if && !.empty? .merge!(@tags) if !@tags.empty? = thread_local_value(:lumberjack_logger_tags) .merge!() if && !.empty? end |
#unknown(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
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.
248 249 250 |
# File 'lib/lumberjack/logger.rb', line 248 def unknown( = nil, = nil, &block) call_add_entry(UNKNOWN, , , &block) end |
#warn(message_or_progname_or_tags = nil, progname_or_tags = nil, &block) ⇒ Object
Log a WARN
message. The message can be passed in either the message
argument or in a block.
217 218 219 |
# File 'lib/lumberjack/logger.rb', line 217 def warn( = nil, = nil, &block) call_add_entry(WARN, , , &block) end |
#warn? ⇒ Boolean
Return true
if WARN
messages are being logged.
222 223 224 |
# File 'lib/lumberjack/logger.rb', line 222 def warn? level <= WARN end |