module Logging
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.
Constants
- DIAGNOSTIC_MUTEX
- INHERIT_CONTEXT
- VERSION
Attributes
Public Class Methods
Access to the appenders.
# File lib/logging.rb, line 139 def appenders ::Logging::Appenders end
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.
# File lib/logging.rb, line 306 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
Used to define a `basepath` that will be removed from filenames when reporting tracing information for log events. Normally you would set this to the root of your project:
Logging.basepath = "/home/user/nifty_project"
Or if you are in a Rails environment:
Logging.basepath = Rails.root.to_s
The basepath is expanded to a full path with trailing slashes removed. This setting will be cleared by a call to `Logging.reset`.
# File lib/logging.rb, line 376 def basepath=( path ) if path.nil? || path.to_s.empty? @basepath = nil else @basepath = File.expand_path(path) end end
Set the default Exception#cause depth used when formatting Exceptions. This sets the maximum number of nested errors that will be formatted by the layouts before giving up. This is used to avoid extremely large outputs.
Logging.cause_depth = nil # set to the DEFAULT_CAUSE_DEPTH Logging.cause_depth = 0 # do not show any exception causes Logging.cause_depth = 1024 # show up to 1024 causes Logging.cause_depth = -1 # results in the DEFAULT_CAUSE_DEPTH
# File lib/logging.rb, line 353 def cause_depth=( value ) if value.nil? @cause_depth = DEFAULT_CAUSE_DEPTH else value = Integer(value) @cause_depth = value < 0 ? DEFAULT_CAUSE_DEPTH : value end end
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.
# 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
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.
# 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
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.
# File lib/logging.rb, line 282 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
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"
# File lib/logging.rb, line 196 def globally( name = :logger ) Module.new { eval "def #{name}() @_logging_logger ||= ::Logging::Logger[self] end" } end
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
# 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 initialize_plugins levels.keys end
Access to the layouts.
# File lib/logging.rb, line 133 def layouts ::Logging::Layouts end
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
.
# File lib/logging.rb, line 390 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
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.
# 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
Public: Accessor method for getting the current Thread's MappedDiagnosticContext.
Returns MappedDiagnosticContext
# File lib/logging/diagnostic_context.rb, line 379 def self.mdc() MappedDiagnosticContext end
Public: Accessor method for getting the current Thread's NestedDiagnosticContext.
Returns NestedDiagnosticContext
# File lib/logging/diagnostic_context.rb, line 386 def self.ndc() NestedDiagnosticContext end
Returns the lpath for the module. If any arguments are given, they will be
joined to the end of the path using File.join
.
# File lib/logging.rb, line 407 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 all appenders. This method should be called immediately after a fork to ensure no conflict with file descriptors and calls to fcntl or flock.
# File lib/logging.rb, line 162 def reopen log_internal {'re-opening all appenders'} ::Logging::Appenders.each {|appender| appender.reopen} self end
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.
# File lib/logging.rb, line 479 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
Set the default UTC offset used when formatting time values sent to the appenders. If left unset, the default local time zone will be used for time values. This method accepts the `utc_offset` format supported by the `Time#localtime` method in Ruby.
Passing “UTC” or `0` as the UTC offset will cause all times to be reported in the UTC timezone.
Logging.utc_offset = "-07:00" # Mountain Standard Time in North America Logging.utc_offset = "+01:00" # Central European Time Logging.utc_offset = "UTC" # UTC Logging.utc_offset = 0 # UTC
# File lib/logging.rb, line 331 def utc_offset=( value ) @utc_offset = case value when nil; nil when "UTC", "GMT", 0; 0 else Time.now.localtime(value) value end end
Returns the version string for the library.
# File lib/logging/version.rb, line 5 def self.version VERSION end