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/ansi_colors.rb,
lib/semantic_logger/appender/base.rb,
lib/semantic_logger/appender/file.rb,
lib/semantic_logger/metrics/statsd.rb,
lib/semantic_logger/appender/syslog.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/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

Constant Summary collapse

VERSION = 
'3.1.0'
LEVELS =

Logging levels in order of most detailed to most severe

[:trace, :debug, :info, :warn, :error, :fatal]

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::Appender::Base]
  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::Appender::Base
  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')



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

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



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/semantic_logger/semantic_logger.rb', line 241

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::Appender::Base] 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



172
173
174
 
# File 'lib/semantic_logger/semantic_logger.rb', line 172

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 ||= 'Semantic Logger'
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

.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

.flush ⇒ Object

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



178
179
180
 
# File 'lib/semantic_logger/semantic_logger.rb', line 178

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

.on_metric(object = nil, &block) ⇒ Object

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

Parameters
  block
    The block to be called

Example:

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



202
203
204
 
# File 'lib/semantic_logger/semantic_logger.rb', line 202

def self.on_metric(object = nil, &block)
  SemanticLogger::Logger.on_metric(object, &block)
end

.remove_appender(appender) ⇒ Object

Remove an existing appender Currently only supports appender instances



164
165
166
 
# File 'lib/semantic_logger/semantic_logger.rb', line 164

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



186
187
188
189
190
 
# File 'lib/semantic_logger/semantic_logger.rb', line 186

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