Class: Lumberjack::Logger

Inherits:
Object
  • Object
show all
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 #{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

Instance Method Summary collapse

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, 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
  @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.



225
226
227
 
# File 'lib/lumberjack/logger.rb', line 225

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 #{options.inspect}"}



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/lumberjack/logger.rb', line 98

def add(severity, message = nil, progname = nil)
  severity = Severity.label_to_level(severity) if severity.is_a?(String) || severity.is_a?(Symbol)
  if severity && severity >= level
    time = Time.now
    message = yield if message.nil? && block_given?
    message = @formatter.format(message)
    entry = LogEntry.new(time, severity, message, progname || self.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
  end
  nil
end

#close ⇒ Object

Close the logging device.



125
126
127
128
 
# File 'lib/lumberjack/logger.rb', line 125

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.



171
172
173
 
# File 'lib/lumberjack/logger.rb', line 171

def debug(message = nil, progname = nil, &block)
  add(DEBUG, message, progname, &block)
end

#debug? ⇒ Boolean

Return true if DEBUG messages are being logged.

Returns:

  • (Boolean) 


176
177
178
 
# File 'lib/lumberjack/logger.rb', line 176

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.



141
142
143
 
# File 'lib/lumberjack/logger.rb', line 141

def error(message = nil, progname = nil, &block)
  add(ERROR, message, progname, &block)
end

#error? ⇒ Boolean

Return true if ERROR messages are being logged.

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/lumberjack/logger.rb', line 146

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.



131
132
133
 
# File 'lib/lumberjack/logger.rb', line 131

def fatal(message = nil, progname = nil, &block)
  add(FATAL, message, progname, &block)
end

#fatal? ⇒ Boolean

Return true if FATAL messages are being logged.

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/lumberjack/logger.rb', line 136

def fatal?
  level <= FATAL
end

#flush ⇒ Object

Flush the logging device. Messages are not guaranteed to be written until this method is called.



118
119
120
121
122
 
# File 'lib/lumberjack/logger.rb', line 118

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.



161
162
163
 
# File 'lib/lumberjack/logger.rb', line 161

def info(message = nil, progname = nil, &block)
  add(INFO, message, progname, &block)
end

#info? ⇒ Boolean

Return true if INFO messages are being logged.

Returns:

  • (Boolean) 


166
167
168
 
# File 'lib/lumberjack/logger.rb', line 166

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.



189
190
191
192
193
194
195
 
# File 'lib/lumberjack/logger.rb', line 189

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.



216
217
218
219
220
221
222
 
# File 'lib/lumberjack/logger.rb', line 216

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



206
207
208
209
210
211
212
 
# File 'lib/lumberjack/logger.rb', line 206

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.



182
183
184
 
# File 'lib/lumberjack/logger.rb', line 182

def unknown(message = nil, progname = nil, &block)
  add(UNKNOWN, message, 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.



151
152
153
 
# File 'lib/lumberjack/logger.rb', line 151

def warn(message = nil, progname = nil, &block)
  add(WARN, message, progname, &block)
end

#warn? ⇒ Boolean

Return true if WARN messages are being logged.

Returns:

  • (Boolean) 


156
157
158
 
# File 'lib/lumberjack/logger.rb', line 156

def warn?
  level <= WARN
end