class Lumberjack::Logger
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 #{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.
Attributes
The device being written to.
The time that the device was last flushed.
The name of the program associated with log messages.
Set silencer
to false to disable silencing the log.
Public Class Methods
Source
# File lib/lumberjack/logger.rb, line 60 def initialize(device = STDOUT, options = {}) @thread_settings = {} options = options.dup self.level = options.delete(:level) || INFO self.progname = options.delete(:progname) max_flush_seconds = options.delete(:flush_seconds).to_f @device = open_device(device, options) @_formatter = Formatter.new @last_flushed_at = Time.now @silencer = true create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0 end
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 aDevice::DateRollingLogFile
if this is set. -
:max_size
- If the log device is a file path, it will be aDevice::SizeRollingLogFile
if this is set.
All other options are passed to the device constuctor.
Public Instance Methods
Source
# File lib/lumberjack/logger.rb, line 101 def add(severity, message = 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 message.nil? if block_given? message = yield else message = progname progname = nil end end message = @_formatter.format(message) progname ||= self.progname entry = LogEntry.new(time, severity, message, progname, $$, Lumberjack.unit_of_work_id) begin device.write(entry) rescue => e $stderr.puts("#{e.class.name}: #{e.message}#{' at ' + e.backtrace.first if e.backtrace}") $stderr.puts(entry.to_s) end nil end
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 #{options.inspect}"}
Source
# File lib/lumberjack/logger.rb, line 139 def close flush @device.close if @device.respond_to?(:close) end
Close the logging device.
Source
# File lib/lumberjack/logger.rb, line 185 def debug(message = nil, progname = nil, &block) add(DEBUG, message, progname, &block) end
Log a DEBUG
message. The message can be passed in either the message
argument or in a block.
Source
# File lib/lumberjack/logger.rb, line 190 def debug? level <= DEBUG end
Return true
if DEBUG
messages are being logged.
Source
# File lib/lumberjack/logger.rb, line 155 def error(message = nil, progname = nil, &block) add(ERROR, message, progname, &block) end
Log an ERROR
message. The message can be passed in either the message
argument or in a block.
Source
# File lib/lumberjack/logger.rb, line 160 def error? level <= ERROR end
Return true
if ERROR
messages are being logged.
Source
# File lib/lumberjack/logger.rb, line 145 def fatal(message = nil, progname = nil, &block) add(FATAL, message, progname, &block) end
Log a FATAL
message. The message can be passed in either the message
argument or in a block.
Source
# File lib/lumberjack/logger.rb, line 150 def fatal? level <= FATAL end
Return true
if FATAL
messages are being logged.
Source
# File lib/lumberjack/logger.rb, line 132 def flush device.flush @last_flushed_at = Time.now nil end
Flush the logging device. Messages are not guaranteed to be written until this method is called.
Source
# File lib/lumberjack/logger.rb, line 77 def formatter @_formatter end
Get the Formatter
object used to convert messages into strings.
Source
# File lib/lumberjack/logger.rb, line 175 def info(message = nil, progname = nil, &block) add(INFO, message, progname, &block) end
Log an INFO
message. The message can be passed in either the message
argument or in a block.
Source
# File lib/lumberjack/logger.rb, line 180 def info? level <= INFO end
Return true
if INFO
messages are being logged.
Source
# File lib/lumberjack/logger.rb, line 83 def level thread_local_value(:lumberjack_logger_level) || @level end
Get the level of severity of entries that are logged. Entries with a lower severity level will be ignored.
Source
# File lib/lumberjack/logger.rb, line 203 def level=(severity) if severity.is_a?(Integer) @level = severity else @level = Severity.label_to_level(severity) end end
Set the minimum level of severity of messages to log.
Source
# File lib/lumberjack/logger.rb, line 239 def progname thread_local_value(:lumberjack_logger_progname) || @progname end
Get the program name associated with log messages.
Source
# File lib/lumberjack/logger.rb, line 230 def set_progname(value, &block) if block push_thread_local_value(:lumberjack_logger_progname, value, &block) else self.progname = value end end
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.
Source
# File lib/lumberjack/logger.rb, line 220 def silence(temporary_level = ERROR, &block) if silencer push_thread_local_value(:lumberjack_logger_level, temporary_level, &block) else yield end end
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
Source
# File lib/lumberjack/logger.rb, line 196 def unknown(message = nil, progname = nil, &block) add(UNKNOWN, message, progname, &block) end
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.
Source
# File lib/lumberjack/logger.rb, line 165 def warn(message = nil, progname = nil, &block) add(WARN, message, progname, &block) end
Log a WARN
message. The message can be passed in either the message
argument or in a block.
Source
# File lib/lumberjack/logger.rb, line 170 def warn? level <= WARN end
Return true
if WARN
messages are being logged.