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.('..', __FILE__) + ::File::SEPARATOR
- PATH =
::File.('../..', __FILE__) + ::File::SEPARATOR
- LEVELS =
{}
- LNAMES =
[]
- VERSION =
"2.2.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
-
.basepath ⇒ Object
Returns the value of attribute basepath.
-
.utc_offset ⇒ Object
Returns the value of attribute utc_offset.
Class Method Summary collapse
-
.appenders ⇒ Object
Access to the appenders.
-
.backtrace(b = nil) ⇒ Object
call-seq: Logging.backtrace #=> true or false Logging.backtrace( value ) #=> true or false.
-
.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.
-
.color_scheme(name, opts = {}) ⇒ Object
Returns the color scheme identified by the given name.
-
.format_as(f) ⇒ Object
call-seq: Logging.format_as( obj_format ).
-
.globally(name = :logger) ⇒ Object
call-seq: include Logging.globally include Logging.globally( :logger ).
-
.init(*args) ⇒ Object
call-seq: Logging.init( levels ).
-
.initialized? ⇒ Boolean
Return
true
if the Logging framework is initialized. -
.layouts ⇒ Object
Access to the layouts.
-
.level_num(level) ⇒ Object
Convert the given level into a level number.
-
.levelify(level) ⇒ Object
:stopdoc: Convert the given level into a canonical form - a lowercase string.
-
.libpath(*args, &block) ⇒ Object
Returns the library path for the module.
-
.log_internal(level = 1, &block) ⇒ Object
Internal logging method for use by the framework.
-
.log_internal_error(err) ⇒ Object
Internal logging method for handling exceptions.
-
.logger(*args) ⇒ Object
call-seq: Logging.logger( device, age = 7, size = 1048576 ) Logging.logger( device, age = ‘weekly’ ).
-
.mdc ⇒ Object
Public: Accessor method for getting the current Thread’s MappedDiagnosticContext.
-
.ndc ⇒ Object
Public: Accessor method for getting the current Thread’s NestedDiagnosticContext.
-
.path(*args, &block) ⇒ Object
Returns the lpath for the module.
-
.reopen ⇒ Object
Reopen all appenders.
-
.reset ⇒ Object
Reset the Logging framework to it’s uninitialized state.
-
.show_configuration(io = STDOUT, logger = 'root', indent = 0) ⇒ Object
call-seq: show_configuration( io = STDOUT, logger = ‘root’ ).
-
.shutdown(*args) ⇒ Object
Close all appenders.
-
.version ⇒ Object
Returns the version string for the library.
Class Attribute Details
.basepath ⇒ Object
Returns the value of attribute basepath.
359 360 361 |
# File 'lib/logging.rb', line 359 def basepath @basepath end |
.utc_offset ⇒ Object
Returns the value of attribute utc_offset.
337 338 339 |
# File 'lib/logging.rb', line 337 def utc_offset @utc_offset end |
Class Method Details
.appenders ⇒ Object
Access to the appenders.
137 138 139 |
# File 'lib/logging.rb', line 137 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.
302 303 304 305 306 307 308 309 310 311 312 |
# File 'lib/logging.rb', line 302 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.
148 149 150 151 152 153 154 |
# File 'lib/logging.rb', line 148 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
, 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
, :yaml
is passed to this method.
278 279 280 281 282 283 284 285 286 287 |
# File 'lib/logging.rb', line 278 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"
194 195 196 197 198 |
# File 'lib/logging.rb', line 194 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
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 |
# File 'lib/logging.rb', line 237 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__ initialize_plugins levels.keys end |
.initialized? ⇒ Boolean
Return true
if the Logging framework is initialized.
524 525 526 |
# File 'lib/logging.rb', line 524 def initialized? const_defined? :MAX_LEVEL_LENGTH end |
.layouts ⇒ Object
Access to the layouts.
131 132 133 |
# File 'lib/logging.rb', line 131 def layouts ::Logging::Layouts end |
.level_num(level) ⇒ Object
Convert the given level into a level number.
478 479 480 481 482 483 484 |
# File 'lib/logging.rb', line 478 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.
470 471 472 473 474 475 |
# File 'lib/logging.rb', line 470 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
.
365 366 367 368 369 370 371 372 373 374 375 376 |
# File 'lib/logging.rb', line 365 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.
487 488 489 |
# File 'lib/logging.rb', line 487 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.
494 495 496 497 |
# File 'lib/logging.rb', line 494 def log_internal_error( err ) log_internal(-2) { err } raise err if Thread.abort_on_exception 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.
70 71 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 |
# File 'lib/logging.rb', line 70 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
.
382 383 384 385 386 387 388 389 390 391 392 393 |
# File 'lib/logging.rb', line 382 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 |
.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.
160 161 162 163 164 |
# File 'lib/logging.rb', line 160 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
508 509 510 511 512 513 514 515 516 517 518 519 520 521 |
# File 'lib/logging.rb', line 508 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 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.
454 455 456 457 458 459 460 461 462 463 464 465 466 |
# File 'lib/logging.rb', line 454 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
500 501 502 503 504 505 |
# File 'lib/logging.rb', line 500 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 |