Module: Logging

Extended by:
LittlePlugger
Defined in:
lib/logging.rb,
lib/logging/proxy.rb,
lib/logging/filter.rb,
lib/logging/layout.rb,
lib/logging/logger.rb,
lib/logging/filters.rb,
lib/logging/layouts.rb,
lib/logging/version.rb,
lib/logging/appender.rb,
lib/logging/appenders.rb,
lib/logging/log_event.rb,
lib/logging/repository.rb,
lib/logging/root_logger.rb,
lib/logging/color_scheme.rb,
lib/logging/rails_compat.rb,
lib/logging/filters/level.rb,
lib/logging/diagnostic_context.rb

Overview

color_scheme.rb

Created by Jeremy Hinegardner on 2007-01-24 Copyright 2007. All rights reserved

This file is licensed under the terms of the MIT License. See the README for licensing details.

Defined Under Namespace

Modules: Appenders, Filters, Layouts, MappedDiagnosticContext, NestedDiagnosticContext, Plugins, RailsCompat Classes: Appender, ColorScheme, Filter, Layout, LogEvent, Logger, Proxy, Repository, RootLogger

Constant Summary collapse

LIBPATH =

:stopdoc:

::File.expand_path('..', __FILE__) + ::File::SEPARATOR
PATH = 
::File.expand_path('../..', __FILE__) + ::File::SEPARATOR
LEVELS = 
{}
LNAMES = 
[]
DEFAULT_CAUSE_DEPTH = 
8
VERSION = 
"2.3.1".freeze
DIAGNOSTIC_MUTEX = 
Mutex.new
INHERIT_CONTEXT =

:stopdoc:

if ENV.key?("LOGGING_INHERIT_CONTEXT")
  case ENV["LOGGING_INHERIT_CONTEXT"].downcase
  when 'false', 'no', '0'; false
  when false, nil; false
  else true end
else
  true
end

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.basepath ⇒ Object

Returns the value of attribute basepath.



385
386
387
 
# File 'lib/logging.rb', line 385

def basepath
  @basepath
end

.cause_depth ⇒ Object

Returns the value of attribute cause_depth.



363
364
365
 
# File 'lib/logging.rb', line 363

def cause_depth
  @cause_depth
end

.utc_offset ⇒ Object

Returns the value of attribute utc_offset.



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

def utc_offset
  @utc_offset
end

Class Method Details

.appenders ⇒ Object

Access to the appenders.



139
140
141
 
# File 'lib/logging.rb', line 139

def appenders
  ::Logging::Appenders
end

.backtrace(b = nil) ⇒ Object

call-seq:

Logging.backtrace             #=> true or false
Logging.backtrace( value )    #=> true or false

Without any arguments, returns the global exception backtrace logging value. When set to true backtraces will be written to the logs; when set to false backtraces will be suppressed.

When an argument is given the global exception backtrace setting will be changed. Value values are "on", :on<tt> and true to turn on backtraces and <tt>"off", :off and false to turn off backtraces.



307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/logging.rb', line 307

def backtrace( b = nil )
  @backtrace = true unless defined? @backtrace
  return @backtrace if b.nil?

  @backtrace = case b
      when :on, 'on', true;    true
      when :off, 'off', false; false
      else
        raise ArgumentError, "backtrace must be true or false"
      end
end

.clear_diagnostic_contexts(all = false) ⇒ Object

Public: Convenience method that will clear both the Mapped Diagnostic Context and the Nested Diagnostic Context of the current thread. If the ‘all` flag passed to this method is true, then the diagnostic contexts for every thread in the application will be cleared.

all - Boolean flag used to clear the context of every Thread (default is false)

Returns the Logging module.



397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/logging/diagnostic_context.rb', line 397

def self.clear_diagnostic_contexts( all = false )
  if all
    DIAGNOSTIC_MUTEX.synchronize do
      Thread.list.each do |t|
        t.thread_variable_set(MappedDiagnosticContext::NAME, nil)       if t.thread_variable?(MappedDiagnosticContext::NAME)
        t.thread_variable_set(NestedDiagnosticContext::NAME, nil)       if t.thread_variable?(NestedDiagnosticContext::NAME)
        t.thread_variable_set(MappedDiagnosticContext::STACK_NAME, nil) if t.thread_variable?(MappedDiagnosticContext::STACK_NAME)
      end
    end
  else
    MappedDiagnosticContext.clear
    NestedDiagnosticContext.clear
  end

  self
end

.color_scheme(name, opts = {}) ⇒ Object

Returns the color scheme identified by the given name. If there is no color scheme nil is returned.

If color scheme options are supplied then a new color scheme is created. Any existing color scheme with the given name will be replaced by the new color scheme.



150
151
152
153
154
155
156
 
# File 'lib/logging.rb', line 150

def color_scheme( name, opts = {} )
  if opts.empty?
    ::Logging::ColorScheme[name]
  else
    ::Logging::ColorScheme.new(name, opts)
  end
end

.format_as(f) ⇒ Object

call-seq:

Logging.format_as( obj_format )

Defines the default obj_format method to use when converting objects into string representations for logging. obj_format can be one of :string, :inspect, :json or :yaml. These formatting commands map to the following object methods

  • :string => to_s

  • :inspect => inspect

  • :yaml => to_yaml

  • :json => MultiJson.encode(obj)

An ArgumentError is raised if anything other than :string, :inspect, :json or :yaml is passed to this method.



283
284
285
286
287
288
289
290
291
292
 
# File 'lib/logging.rb', line 283

def format_as( f )
  f = f.intern if f.instance_of? String

  unless [:string, :inspect, :yaml, :json].include? f
    raise ArgumentError, "unknown object format '#{f}'"
  end

  module_eval "OBJ_FORMAT = :#{f}", __FILE__, __LINE__
  self
end

.globally(name = :logger) ⇒ Object

call-seq:

include Logging.globally
include Logging.globally( :logger )

Add a “logger” method to the including context. If included from Object or Kernel, the logger method will be available to all objects.

Optionally, a method name can be given and that will be used to provided access to the logger:

include Logging.globally( :log )
log.info "Just using a shorter method name"

If you prefer to use the shorter “log” to access the logger.

Example

include Logging.globally

class Foo
  logger.debug "Loading the Foo class"
  def initialize
    logger.info "Creating some new foo"
  end
end

logger.fatal "End of example"



196
197
198
199
200
 
# File 'lib/logging.rb', line 196

def globally( name = :logger )
  Module.new {
    eval "def #{name}() @_logging_logger ||= ::Logging::Logger[self] end"
  }
end

.init(*args) ⇒ Object

call-seq:

Logging.init( levels )

Defines the levels available to the loggers. The levels is an array of strings and symbols. Each element in the array is downcased and converted to a symbol; these symbols are used to create the logging methods in the loggers.

The first element in the array is the lowest logging level. Setting the logging level to this value will enable all log messages. The last element in the array is the highest logging level. Setting the logging level to this value will disable all log messages except this highest level.

This method should be invoked only once to configure the logging levels. It is automatically invoked with the default logging levels when the first logger is created.

The levels “all” and “off” are reserved and will be ignored if passed to this method.

Example:

Logging.init :debug, :info, :warn, :error, :fatal
log = Logging::Logger['my logger']
log.level = :warn
log.warn 'Danger! Danger! Will Robinson'
log.info 'Just FYI'                        # => not logged

or

Logging.init %w(DEBUG INFO NOTICE WARNING ERR CRIT ALERT EMERG)
log = Logging::Logger['syslog']
log.level = :notice
log.warning 'This is your first warning'
log.info 'Just FYI'                        # => not logged



239
240
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
 
# File 'lib/logging.rb', line 239

def init( *args )
  args = %w(debug info warn error fatal) if args.empty?

  args.flatten!
  levels = LEVELS.clear
  names = LNAMES.clear

  id = 0
  args.each do |lvl|
    lvl = levelify lvl
    unless levels.has_key?(lvl) or lvl == 'all' or lvl == 'off'
      levels[lvl] = id
      names[id] = lvl.upcase
      id += 1
    end
  end

  longest = names.inject {|x,y| (x.length > y.length) ? x : y}
  longest = 'off' if longest.length < 3
  module_eval "MAX_LEVEL_LENGTH = #{longest.length}", __FILE__, __LINE__

  self.cause_depth = nil unless defined? @cause_depth
  self.raise_errors = false unless defined? @raise_errors

  initialize_plugins
  levels.keys
end

.initialized? ⇒ Boolean

Return true if the Logging framework is initialized.

Returns:

  • (Boolean) 


566
567
568
 
# File 'lib/logging.rb', line 566

def initialized?
  const_defined? :MAX_LEVEL_LENGTH
end

.layouts ⇒ Object

Access to the layouts.



133
134
135
 
# File 'lib/logging.rb', line 133

def layouts
  ::Logging::Layouts
end

.level_num(level) ⇒ Object

Convert the given level into a level number.



519
520
521
522
523
524
525
 
# File 'lib/logging.rb', line 519

def level_num( level )
  l = levelify(level) rescue level
  case l
  when 'all'; 0
  when 'off'; LEVELS.length
  else begin; Integer(l); rescue ArgumentError; LEVELS[l] end end
end

.levelify(level) ⇒ Object

:stopdoc: Convert the given level into a canonical form - a lowercase string.



511
512
513
514
515
516
 
# File 'lib/logging.rb', line 511

def levelify( level )
  case level
  when String; level.downcase
  when Symbol; level.to_s.downcase
  else raise ArgumentError, "levels must be a String or Symbol" end
end

.libpath(*args, &block) ⇒ Object

Returns the library path for the module. If any arguments are given, they will be joined to the end of the library path using File.join.



391
392
393
394
395
396
397
398
399
400
401
402
 
# File 'lib/logging.rb', line 391

def libpath( *args, &block )
  rv = args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
  if block
    begin
      $LOAD_PATH.unshift LIBPATH
      rv = block.call
    ensure
      $LOAD_PATH.shift
    end
  end
  return rv
end

.log_internal(level = 1, &block) ⇒ Object

Internal logging method for use by the framework.



528
529
530
 
# File 'lib/logging.rb', line 528

def log_internal( level = 1, &block )
  ::Logging::Logger[::Logging].__send__(levelify(LNAMES[level]), &block)
end

.log_internal_error(err) ⇒ Object

Internal logging method for handling exceptions. If the ‘Thread#abort_on_exception` flag is set then the exception will be raised again.



535
536
537
538
 
# File 'lib/logging.rb', line 535

def log_internal_error( err )
  log_internal(-2) { err }
  raise err if ::Logging.raise_errors?
end

.logger(*args) ⇒ Object

call-seq:

Logging.logger( device, age = 7, size = 1048576 )
Logging.logger( device, age = 'weekly' )

This convenience method returns a Logger instance configured to behave similarly to a core Ruby Logger instance.

The device is the logging destination. This can be a filename (String) or an IO object (STDERR, STDOUT, an open File, etc.). The age is the number of old log files to keep or the frequency of rotation (daily, weekly, or monthly). The size is the maximum logfile size and is only used when age is a number.

Using the same device twice will result in the same Logger instance being returned. For example, if a Logger is created using STDOUT then the same Logger instance will be returned the next time STDOUT is used. A new Logger instance can be obtained by closing the previous logger instance.

log1 = Logging.logger(STDOUT)
log2 = Logging.logger(STDOUT)
log1.object_id == log2.object_id  #=> true

log1.close
log2 = Logging.logger(STDOUT)
log1.object_id == log2.object_id  #=> false

The format of the log messages can be changed using a few optional parameters. The :pattern can be used to change the log message format. The :date_pattern can be used to change how timestamps are formatted.

log = Logging.logger(STDOUT,
          :pattern => "[%d] %-5l : %m\n",
          :date_pattern => "%Y-%m-%d %H:%M:%S.%s")

See the documentation for the Logging::Layouts::Pattern class for a full description of the :pattern and :date_pattern formatting strings.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/logging.rb', line 72

def logger( *args )
  return ::Logging::Logger if args.empty?

  opts = args.pop if args.last.instance_of?(Hash)
  opts ||= Hash.new

  dev = args.shift
  keep = age = args.shift
  size = args.shift

  name = case dev
         when String; dev
         when File; dev.path
         else dev.object_id.to_s end

  repo = ::Logging::Repository.instance
  return repo[name] if repo.has_logger? name

  l_opts = {
    :pattern => "%.1l, [%d #%p] %#{::Logging::MAX_LEVEL_LENGTH}l : %m\n",
    :date_pattern => '%Y-%m-%dT%H:%M:%S.%s'
  }
  [:pattern, :date_pattern, :date_method].each do |o|
    l_opts[o] = opts.delete(o) if opts.has_key? o
  end
  layout = ::Logging::Layouts::Pattern.new(l_opts)

  a_opts = Hash.new
  a_opts[:size] = size if size.is_a?(Integer)
  a_opts[:age]  = age  if age.instance_of?(String)
  a_opts[:keep] = keep if keep.is_a?(Integer)
  a_opts[:filename] = dev if dev.instance_of?(String)
  a_opts[:layout] = layout
  a_opts.merge! opts

  appender =
      case dev
      when String
        ::Logging::Appenders::RollingFile.new(name, a_opts)
      else
        ::Logging::Appenders::IO.new(name, dev, a_opts)
      end

  logger = ::Logging::Logger.new(name)
  logger.add_appenders appender
  logger.additive = false

  class << logger
    def close
      @appenders.each {|a| a.close}
      h = ::Logging::Repository.instance.instance_variable_get :@h
      h.delete(@name)
      class << self; undef :close; end
    end
  end

  logger
end

.mdc ⇒ Object

Public: Accessor method for getting the current Thread’s MappedDiagnosticContext.

Returns MappedDiagnosticContext



379
 
# File 'lib/logging/diagnostic_context.rb', line 379

def self.mdc() MappedDiagnosticContext end

.ndc ⇒ Object

Public: Accessor method for getting the current Thread’s NestedDiagnosticContext.

Returns NestedDiagnosticContext



386
 
# File 'lib/logging/diagnostic_context.rb', line 386

def self.ndc() NestedDiagnosticContext end

.path(*args, &block) ⇒ Object

Returns the lpath for the module. If any arguments are given, they will be joined to the end of the path using File.join.



408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/logging.rb', line 408

def path( *args, &block )
  rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
  if block
    begin
      $LOAD_PATH.unshift PATH
      rv = block.call
    ensure
      $LOAD_PATH.shift
    end
  end
  return rv
end

.raise_errors=(boolean) ⇒ Object

Raise an exception when an error is encountered while logging, be it with a backing store, formatter, or anything else. You probably wouldn’t want to enable this outside of test.

Not that only one error will ever be raised per logging backend, as backends that raise errors on write will be set to :off.



500
501
502
 
# File 'lib/logging.rb', line 500

def raise_errors=(boolean)
  @raise_errors = boolean
end

.raise_errors? ⇒ Boolean

Whether or not we should raise errors when writing logs.

Returns:

  • (Boolean) 


505
506
507
 
# File 'lib/logging.rb', line 505

def raise_errors?
  @raise_errors
end

.reopen ⇒ Object

Reopen all appenders. This method should be called immediately after a fork to ensure no conflict with file descriptors and calls to fcntl or flock.



162
163
164
165
166
 
# File 'lib/logging.rb', line 162

def reopen
  log_internal {'re-opening all appenders'}
  ::Logging::Appenders.each {|appender| appender.reopen}
  self
end

.reset ⇒ Object

Reset the Logging framework to it’s uninitialized state



549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'lib/logging.rb', line 549

def reset
  ::Logging::Repository.reset
  ::Logging::Appenders.reset
  ::Logging::ColorScheme.reset
  ::Logging.clear_diagnostic_contexts(true)
  LEVELS.clear
  LNAMES.clear
  remove_instance_variable :@backtrace if defined? @backtrace
  remove_instance_variable :@basepath  if defined? @basepath
  remove_const :MAX_LEVEL_LENGTH if const_defined? :MAX_LEVEL_LENGTH
  remove_const :OBJ_FORMAT if const_defined? :OBJ_FORMAT
  self.utc_offset  = nil
  self.cause_depth = nil
  self
end

.show_configuration(io = STDOUT, logger = 'root', indent = 0) ⇒ Object

call-seq:

show_configuration( io = STDOUT, logger = 'root' )

This method is used to show the configuration of the logging framework. The information is written to the given io stream (defaulting to stdout). Normally the configuration is dumped starting with the root logger, but any logger name can be given.

Each line contains information for a single logger and it’s appenders. A child logger is indented two spaces from it’s parent logger. Each line contains the logger name, level, additivity, and trace settings. Here is a brief example:

root  ...........................   *info      -T
  LoggerA  ......................    info  +A  -T
    LoggerA::LoggerB  ...........    info  +A  -T
    LoggerA::LoggerC  ...........  *debug  +A  -T
  LoggerD  ......................   *warn  -A  +T

The lines can be deciphered as follows:

1) name       - the name of the logger

2) level      - the logger level; if it is preceded by an
                asterisk then the level was explicitly set for that
                logger (as opposed to being inherited from the parent
                logger)

3) additivity - a "+A" shows the logger is additive, and log events
                will be passed up to the parent logger; "-A" shows
                that the logger will *not* pass log events up to the
                parent logger

4) tracing    - a "+T" shows that the logger will include caller
                tracing information in generated log events (this
                includes filename and line number of the log
                message); "-T" shows that the logger does not include
                caller tracing information in the log events

If a logger has appenders then they are listed, one per line, immediately below the logger. Appender lines are pre-pended with a single dash:

root  ...........................   *info      -T
- <Appenders::Stdout:0x8b02a4 name="stdout">
  LoggerA  ......................    info  +A  -T
    LoggerA::LoggerB  ...........    info  +A  -T
    LoggerA::LoggerC  ...........  *debug  +A  -T
  LoggerD  ......................   *warn  -A  +T
  - <Appenders::Stderr:0x8b04ca name="stderr">

We can see in this configuration dump that all the loggers will append to stdout via the Stdout appender configured in the root logger. All the loggers are additive, and so their generated log events will be passed up to the root logger.

The exception in this configuration is LoggerD. Its additivity is set to false. It uses its own appender to send messages to stderr.



480
481
482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/logging.rb', line 480

def show_configuration( io = STDOUT, logger = 'root', indent = 0 )
  logger = ::Logging::Logger[logger] unless logger.is_a?(::Logging::Logger)

  io << logger._dump_configuration(indent)

  indent += 2
  children = ::Logging::Repository.instance.children(logger.name)
  children.sort {|a,b| a.name <=> b.name}.each do |child|
    ::Logging.show_configuration(io, child, indent)
  end

  io
end

.shutdown(*args) ⇒ Object

Close all appenders



541
542
543
544
545
546
 
# File 'lib/logging.rb', line 541

def shutdown( *args )
  return unless initialized?
  log_internal {'shutdown called - closing all appenders'}
  ::Logging::Appenders.each {|appender| appender.close}
  nil
end

.version ⇒ Object

Returns the version string for the library.



5
6
7
 
# File 'lib/logging/version.rb', line 5

def self.version
  VERSION
end