Module: SemanticLogger

Defined in:
lib/semantic_logger.rb,
lib/semantic_logger/log.rb,
lib/semantic_logger/base.rb,
lib/semantic_logger/logger.rb,
lib/semantic_logger/version.rb,
lib/semantic_logger/loggable.rb,
lib/semantic_logger/subscriber.rb,
lib/semantic_logger/ansi_colors.rb,
lib/semantic_logger/metrics/udp.rb,
lib/semantic_logger/appender/tcp.rb,
lib/semantic_logger/appender/udp.rb,
lib/semantic_logger/appender/file.rb,
lib/semantic_logger/formatters/raw.rb,
lib/semantic_logger/metrics/statsd.rb,
lib/semantic_logger/appender/syslog.rb,
lib/semantic_logger/formatters/base.rb,
lib/semantic_logger/formatters/json.rb,
lib/semantic_logger/semantic_logger.rb,
lib/semantic_logger/appender/mongodb.rb,
lib/semantic_logger/appender/wrapper.rb,
lib/semantic_logger/formatters/color.rb,
lib/semantic_logger/formatters/syslog.rb,
lib/semantic_logger/metrics/new_relic.rb,
lib/semantic_logger/formatters/default.rb,
lib/semantic_logger/debug_as_trace_logger.rb,
lib/semantic_logger/concerns/compatibility.rb,
lib/semantic_logger/jruby/garbage_collection_logger.rb

Overview

:nodoc:

Defined Under Namespace

Modules: AnsiColors, Appender, Concerns, Formatters, JRuby, Loggable, Metrics Classes: Base, DebugAsTraceLogger, Log, Logger, Subscriber

Constant Summary collapse

VERSION = 
'3.3.0'
LEVELS =

Logging levels in order of most detailed to most severe

[:trace, :debug, :info, :warn, :error, :fatal]
@@application = 
'Semantic Logger'

Class Method Summary collapse

Class Method Details

.[](klass) ⇒ Object

Return a logger for the supplied class or class_name



9
10
11
 
# File 'lib/semantic_logger/semantic_logger.rb', line 9

def self.[](klass)
  SemanticLogger::Logger.new(klass)
end

.add_appender(options, deprecated_level = nil, &block) ⇒ Object

Add a new logging appender as a new destination for all log messages emitted from Semantic Logger

Appenders will be written to in the order that they are added

If a block is supplied then it will be used to customize the format of the messages sent to that appender. See SemanticLogger::Logger.new for more information on custom formatters

Parameters

file_name: [String]
  File name to write log messages to.

Or,
io: [IO]
  An IO Stream to log to.
  For example STDOUT, STDERR, etc.

Or,
appender: [Symbol|SemanticLogger::Subscriber]
  A symbol identifying the appender to create.
  For example:
    :bugsnag, :elasticsearch, :graylog, :http, :mongodb, :new_relic, :splunk_http, :syslog, :wrapper
       Or,
  An instance of an appender derived from SemanticLogger::Subscriber
  For example:
    SemanticLogger::Appender::Http.new(url: 'http://localhost:8088/path')

Or,
logger: [Logger|Log4r]
  An instance of a Logger or a Log4r logger.

level: [:trace | :debug | :info | :warn | :error | :fatal]
  Override the log level for this appender.
  Default: SemanticLogger.default_level

formatter: [Symbol|Object|Proc]
  Any of the following symbol values: :default, :color, :json
    Or,
  An instance of a class that implements #call
    Or,
  A Proc to be used to format the output from this appender
  Default: :default

filter: [Regexp|Proc]
  RegExp: Only include log messages where the class name matches the supplied.
  regular expression. All other messages will be ignored.
  Proc: Only include log messages where the supplied Proc returns true
        The Proc must return true or false.

Examples:

# Send all logging output to Standard Out (Screen)
SemanticLogger.add_appender(io: STDOUT)

# Send all logging output to a file
SemanticLogger.add_appender(file_name: 'logfile.log')

# Send all logging output to a file and only :info and above to standard output
SemanticLogger.add_appender(file_name: 'logfile.log')
SemanticLogger.add_appender(io: STDOUT, level: :info)

Log to log4r, Logger, etc.:

# Send Semantic logging output to an existing logger
require 'logger'
require 'semantic_logger'

# Built-in Ruby logger
log = Logger.new(STDOUT)
log.level = Logger::DEBUG

SemanticLogger.default_level = :debug
SemanticLogger.add_appender(logger: log)

logger = SemanticLogger['Example']
logger.info "Hello World"
logger.debug("Login time", user: 'Joe', duration: 100, ip_address: '127.0.0.1')



154
155
156
157
158
159
160
161
162
 
# File 'lib/semantic_logger/semantic_logger.rb', line 154

def self.add_appender(options, deprecated_level = nil, &block)
  options  = options.is_a?(Hash) ? options.dup : convert_old_appender_args(options, deprecated_level)
  appender = appender_from_options(options, &block)
  @@appenders << appender

  # Start appender thread if it is not already running
  SemanticLogger::Logger.start_appender_thread
  appender
end

.add_signal_handler(log_level_signal = 'USR2', thread_dump_signal = 'TTIN', gc_log_microseconds = 100000) ⇒ Object

Add signal handlers for Semantic Logger

Two signal handlers will be registered by default:

  1. Changing the log_level:

The log level can be changed without restarting the process by sending the
log_level_signal, which by default is 'USR2'

When the log_level_signal is raised on this process, the global default log level
rotates through the following log levels in the following order, starting
from the current global default level:
  :warn, :info, :debug, :trace

If the current level is :trace it wraps around back to :warn

  1. Logging a Ruby thread dump

When the signal is raised on this process, Semantic Logger will write the list
of threads to the log file, along with their back-traces when available

For JRuby users this thread dump differs form the standard QUIT triggered
Java thread dump which includes system threads and Java stack traces.

It is recommended to name any threads you create in the application, by
calling the following from within the thread itself:
   Thread.current.name = 'My Worker'

Also adds JRuby Garbage collection logging so that any garbage collections that exceed the time threshold will be logged. Default: 100 ms Currently only supported when running JRuby

Note:

To only register one of the signal handlers, set the other to nil
Set gc_log_microseconds to nil to not enable JRuby Garbage collections



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/semantic_logger/semantic_logger.rb', line 258

def self.add_signal_handler(log_level_signal='USR2', thread_dump_signal='TTIN', gc_log_microseconds=100000)
  Signal.trap(log_level_signal) do
    index     = (default_level == :trace) ? LEVELS.find_index(:error) : LEVELS.find_index(default_level)
    new_level = LEVELS[index-1]
    self['SemanticLogger'].warn "Changed global default log level to #{new_level.inspect}"
    self.default_level = new_level
  end if log_level_signal

  Signal.trap(thread_dump_signal) do
    logger = SemanticLogger['Thread Dump']
    Thread.list.each do |thread|
      next if thread == Thread.current
      message = thread.name
      if backtrace = thread.backtrace
        message += "\n"
        message << backtrace.join("\n")
      end
      tags = thread[:semantic_logger_tags]
      tags = tags.nil? ? [] : tags.clone
      logger.tagged(tags) { logger.warn(message) }
    end
  end if thread_dump_signal

  if gc_log_microseconds && defined?(JRuby)
    listener = SemanticLogger::JRuby::GarbageCollectionLogger.new(gc_log_microseconds)
    Java::JavaLangManagement::ManagementFactory.getGarbageCollectorMXBeans.each do |gcbean|
      gcbean.add_notification_listener(listener, nil, nil)
    end
  end

  true
end

.appenders ⇒ Object

Returns [SemanticLogger::Subscriber] a copy of the list of active appenders for debugging etc. Use SemanticLogger.add_appender and SemanticLogger.remove_appender to manipulate the active appenders list



174
175
176
 
# File 'lib/semantic_logger/semantic_logger.rb', line 174

def self.appenders
  @@appenders.clone
end

.application ⇒ Object

Returns [String] name of this application for logging purposes Note: Not all appenders use ‘application`



65
66
67
 
# File 'lib/semantic_logger/semantic_logger.rb', line 65

def self.application
  @@application
end

.application=(application) ⇒ Object

Override the default application



70
71
72
 
# File 'lib/semantic_logger/semantic_logger.rb', line 70

def self.application=(application)
  @@application = application
end

.backtrace_level ⇒ Object

Returns the current backtrace level



42
43
44
 
# File 'lib/semantic_logger/semantic_logger.rb', line 42

def self.backtrace_level
  @@backtrace_level
end

.backtrace_level=(level) ⇒ Object

Sets the level at which backtraces should be captured for every log message.

By enabling backtrace capture the filename and line number of where message was logged can be written to the log file. Additionally, the backtrace can be forwarded to error management services such as Bugsnag.

Warning:

Capturing backtraces is very expensive and should not be done all
the time. It is recommended to run it at :error level in production.



35
36
37
38
39
 
# File 'lib/semantic_logger/semantic_logger.rb', line 35

def self.backtrace_level=(level)
  @@backtrace_level       = level
  # For performance reasons pre-calculate the level index
  @@backtrace_level_index = level.nil? ? 65535 : level_to_index(level)
end

.backtrace_level_index ⇒ Object

Returns the current backtrace level index For internal use only



48
49
50
 
# File 'lib/semantic_logger/semantic_logger.rb', line 48

def self.backtrace_level_index #:nodoc
  @@backtrace_level_index
end

.close ⇒ Object

Close and flush all appenders



185
186
187
 
# File 'lib/semantic_logger/semantic_logger.rb', line 185

def self.close
  SemanticLogger::Logger.close
end

.default_level ⇒ Object

Returns the global default log level



21
22
23
 
# File 'lib/semantic_logger/semantic_logger.rb', line 21

def self.default_level
  @@default_level
end

.default_level=(level) ⇒ Object

Sets the global default log level



14
15
16
17
18
 
# File 'lib/semantic_logger/semantic_logger.rb', line 14

def self.default_level=(level)
  @@default_level       = level
  # For performance reasons pre-calculate the level index
  @@default_level_index = level_to_index(level)
end

.fast_tag(tag) ⇒ Object

If the tag being supplied is definitely a string then this fast tag api can be used for short lived tags



293
294
295
296
297
298
 
# File 'lib/semantic_logger/semantic_logger.rb', line 293

def self.fast_tag(tag)
  (Thread.current[:semantic_logger_tags] ||= []) << tag
  yield
ensure
  Thread.current[:semantic_logger_tags].pop
end

.flush ⇒ Object

Wait until all queued log messages have been written and flush all active appenders



180
181
182
 
# File 'lib/semantic_logger/semantic_logger.rb', line 180

def self.flush
  SemanticLogger::Logger.flush
end

.host ⇒ Object

Returns [String] name of this host for logging purposes Note: Not all appenders use ‘host`



54
55
56
 
# File 'lib/semantic_logger/semantic_logger.rb', line 54

def self.host
  @@host ||= Socket.gethostname
end

.host=(host) ⇒ Object

Override the default host name



59
60
61
 
# File 'lib/semantic_logger/semantic_logger.rb', line 59

def self.host=(host)
  @@host = host
end

.named_tags(tag) ⇒ Object

Add the supplied named tags to the list of tags to log for this thread whilst the supplied block is active.

Returns result of block

Example:



306
307
308
309
310
311
 
# File 'lib/semantic_logger/semantic_logger.rb', line 306

def self.named_tags(tag)
  (Thread.current[:semantic_logger_tags] ||= []) << tag
  yield
ensure
  Thread.current[:semantic_logger_tags].pop
end

.on_metric(options = {}, &block) ⇒ Object

Supply a block to be called whenever a metric is seen during measure logging

Parameters
  appender: [Symbol | Object | Proc]
    [Proc] the block to call.
    [Object] the block on which to call #call.
    [Symbol] :new_relic, or :statsd to forward metrics to

  block
    The block to be called

Example:

SemanticLogger.on_metric do |log|
  puts "#{log.metric} was received. Log Struct: #{log.inspect}"
end

Note:

  • This callback is called in the logging thread.

  • Does not slow down the application.

  • Only context is what is passed in the log struct, the original thread context is not available.



219
220
221
 
# File 'lib/semantic_logger/semantic_logger.rb', line 219

def self.on_metric(options = {}, &block)
  SemanticLogger::Logger.on_metric(options, &block)
end

.pop_tags(quantity = 1) ⇒ Object

Remove specified number of tags from the current tag list



342
343
344
345
 
# File 'lib/semantic_logger/semantic_logger.rb', line 342

def self.pop_tags(quantity=1)
  t = Thread.current[:semantic_logger_tags]
  t.pop(quantity) unless t.nil?
end

.push_tags(*tags) ⇒ Object

Add tags to the current scope Returns the list of tags pushed after flattening them out and removing blanks



333
334
335
336
337
338
339
 
# File 'lib/semantic_logger/semantic_logger.rb', line 333

def self.push_tags(*tags)
  # Need to flatten and reject empties to support calls from Rails 4
  new_tags                              = tags.flatten.collect(&:to_s).reject(&:empty?)
  t                                     = Thread.current[:semantic_logger_tags]
  Thread.current[:semantic_logger_tags] = t.nil? ? new_tags : t.concat(new_tags)
  new_tags
end

.remove_appender(appender) ⇒ Object

Remove an existing appender Currently only supports appender instances



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

def self.remove_appender(appender)
  @@appenders.delete(appender)
end

.reopen ⇒ Object

After forking an active process call SemanticLogger.reopen to re-open any open file handles etc to resources

Note: Only appenders that implement the reopen method will be called



193
194
195
196
197
 
# File 'lib/semantic_logger/semantic_logger.rb', line 193

def self.reopen
  @@appenders.each { |appender| appender.reopen if appender.respond_to?(:reopen) }
  # After a fork the appender thread is not running, start it if it is not running
  SemanticLogger::Logger.start_appender_thread
end

.silence(new_level = :error) ⇒ Object

Silence noisy log levels by changing the default_level within the block

This setting is thread-safe and only applies to the current thread

Any threads spawned within the block will not be affected by this setting

#silence can be used to both raise and lower the log level within the supplied block.

Example:

# Perform trace level logging within the block when the default is higher
SemanticLogger.default_level = :info

logger.debug 'this will _not_ be logged'

SemanticLogger.silence(:trace) do
  logger.debug "this will be logged"
end

Parameters

new_level
  The new log level to apply within the block
  Default: :error

Example:

# Silence all logging for this thread below :error level
SemanticLogger.silence do
  logger.info "this will _not_ be logged"
  logger.warn "this neither"
  logger.error "but errors will be logged"
end

Note:

#silence does not affect any loggers which have had their log level set
explicitly. I.e. That do not rely on the global default level



383
384
385
386
387
388
389
 
# File 'lib/semantic_logger/semantic_logger.rb', line 383

def self.silence(new_level = :error)
  current_index                            = Thread.current[:semantic_logger_silence]
  Thread.current[:semantic_logger_silence] = SemanticLogger.level_to_index(new_level)
  yield
ensure
  Thread.current[:semantic_logger_silence] = current_index
end

.tagged(*tags) ⇒ Object

Add the supplied tags to the list of tags to log for this thread whilst the supplied block is active. Returns result of block



316
317
318
319
320
321
 
# File 'lib/semantic_logger/semantic_logger.rb', line 316

def self.tagged(*tags)
  new_tags = push_tags(*tags)
  yield self
ensure
  pop_tags(new_tags.size)
end

.tags ⇒ Object

Returns a copy of the [Array] of [String] tags currently active for this thread Returns nil if no tags are set



325
326
327
328
329
 
# File 'lib/semantic_logger/semantic_logger.rb', line 325

def self.tags
  # Since tags are stored on a per thread basis this list is thread-safe
  t = Thread.current[:semantic_logger_tags]
  t.nil? ? [] : t.clone
end