Module: Logging

### Home Classes Methods

### In Files

- lib/logging.rb
- lib/logging/appender.rb
- lib/logging/appenders.rb
- lib/logging/color_scheme.rb
- lib/logging/diagnostic_context.rb
- lib/logging/filter.rb
- lib/logging/filters.rb
- lib/logging/filters/level.rb
- lib/logging/layout.rb
- lib/logging/layouts.rb
- lib/logging/log_event.rb
- lib/logging/logger.rb
- lib/logging/proxy.rb
- lib/logging/rails_compat.rb
- lib/logging/repository.rb
- lib/logging/root_logger.rb
- lib/logging/version.rb

### Namespace

- MODULE Logging::Appenders
- MODULE Logging::Filters
- MODULE Logging::Layouts
- MODULE Logging::MappedDiagnosticContext
- MODULE Logging::NestedDiagnosticContext
- MODULE Logging::RailsCompat
- CLASS Logging::Appender
- CLASS Logging::ColorScheme
- CLASS Logging::Filter
- CLASS Logging::Layout
- CLASS Logging::Logger
- CLASS Logging::Proxy
- CLASS Logging::Repository
- CLASS Logging::RootLogger

### Methods

- ::appenders
- ::backtrace
- ::clear_diagnostic_contexts
- ::color_scheme
- ::format_as
- ::globally
- ::init
- ::layouts
- ::libpath
- ::logger
- ::mdc
- ::ndc
- ::path
- ::reopen
- ::show_configuration
- ::version

### Files

- History.txt

### Class/Module Index

Quicksearch

- Logging
- Logging::Appender
- Logging::Appenders
- Logging::Appenders::Buffering
- Logging::Appenders::File
- Logging::Appenders::IO
- Logging::Appenders::RollingFile
- Logging::Appenders::RollingFile::Roller
- Logging::Appenders::Stderr
- Logging::Appenders::Stdout
- Logging::Appenders::StringIo
- Logging::Appenders::Syslog
- Logging::ColorScheme
- Logging::Filter
- Logging::Filters
- Logging::Filters::Level
- Logging::Layout
- Logging::Layouts
- Logging::Layouts::Basic
- Logging::Layouts::Parseable
- Logging::Layouts::Pattern
- Logging::Logger
- Logging::MappedDiagnosticContext
- Logging::NestedDiagnosticContext
- Logging::Proxy
- Logging::RailsCompat
- Logging::Repository
- Logging::Repository::Singleton
- Logging::RootLogger
- RSpec
- RSpec::Core
- RSpec::Core::Configuration
- RSpec::LoggingHelper
- RSpec::LoggingHelper
- Spec
- Spec::Runner
- Spec::Runner::Configuration
- Object
- Object::LoggingHelper
- File
- FileUtils
- Module
- ReentrantMutex
- String

No matching classes.

# 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

LogEvent

  This class defines a logging event.

VERSION

### Public Class Methods

appenders() click to toggle source

Access to the appenders.

    # File lib/logging.rb, line 137
    def appenders
      ::Logging::Appenders
    end

backtrace #=> true or false click to toggle source
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.

    # 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 ) click to toggle source

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 382
    def self.clear_diagnostic_contexts( all = false )
      if all
        Thread.exclusive {
          Thread.list.each { |thread|
            thread[MappedDiagnosticContext::NAME] = nil if thread[MappedDiagnosticContext::NAME]
            thread[NestedDiagnosticContext::NAME] = nil if thread[NestedDiagnosticContext::NAME]
            thread[MappedDiagnosticContext::STACK_NAME] = nil if thread[MappedDiagnosticContext::STACK_NAME]
          }
        }
      else
        MappedDiagnosticContext.clear
        NestedDiagnosticContext.clear
      end

      self
    end

color_scheme( name, opts = {} ) click to toggle source

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 148
    def color_scheme( name, opts = {} )
      if opts.empty?
        ::Logging::ColorScheme[name]
      else
        ::Logging::ColorScheme.new(name, opts)
      end
    end

format_as( obj_format ) click to toggle source

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 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

include Logging.globally click to toggle source
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"

    # File lib/logging.rb, line 194
    def globally( name = :logger )
      Module.new {
        eval "def #{name}() @_logging_logger ||= ::Logging::Logger[self] end"
      }
    end

init( levels ) click to toggle source

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 237
    def init( *args )
      args = %(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

layouts() click to toggle source

Access to the layouts.

    # File lib/logging.rb, line 131
    def layouts
      ::Logging::Layouts
    end

libpath( *args, &block ) click to toggle source

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 318
    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

logger( device, age = 7, size = 1048576 ) click to toggle source
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.

    # 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.instance_of?(Fixnum)
      a_opts[:age]  = age  if age.instance_of?(String)
      a_opts[:keep] = keep if keep.instance_of?(Fixnum)
      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() click to toggle source

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

Returns MappedDiagnosticContext

    # File lib/logging/diagnostic_context.rb, line 364
    def self.mdc() MappedDiagnosticContext end

ndc() click to toggle source

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

Returns NestedDiagnosticContext

    # File lib/logging/diagnostic_context.rb, line 371
    def self.ndc() NestedDiagnosticContext end

path( *args, &block ) click to toggle source

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 335
    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() click to toggle source

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 160
    def reopen
      log_internal {'re-opening all appenders'}
      ::Logging::Appenders.each {|appender| appender.reopen}
      self
    end

show_configuration( io = STDOUT, logger = 'root' ) click to toggle source

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 407
    def show_configuration( io = STDOUT, logger = 'root', indent = 0 )
      logger = ::Logging::Logger[logger] unless ::Logging::Logger === 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

version() click to toggle source

Returns the version string for the library.

    # File lib/logging/version.rb, line 5
    def self.version
      VERSION
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.