Module: Logging

Defined in:
lib/logging.rb,
lib/logging/layout.rb,
lib/logging/logger.rb,
lib/logging/appender.rb,
lib/logging/log_event.rb,
lib/logging/repository.rb,
lib/logging/root_logger.rb,
lib/logging/layouts/basic.rb,
lib/logging/layouts/pattern.rb,
lib/logging/config/yaml_configurator.rb

Overview

$Id$

Defined Under Namespace

Modules: Appenders, Config, Layouts Classes: Appender, Layout, LogEvent, Logger, Repository, RootLogger

Constant Summary collapse

VERSION =

:stopdoc:

'0.7.1'
LIBPATH = 
::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
PATH = 
::File.dirname(LIBPATH) + ::File::SEPARATOR
WIN32 = 
%r/djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM
LEVELS = 
{}
LNAMES = 
{}

Class Method Summary collapse

Class Method Details

.configure(filename, *args) ⇒ Object

call-seq:

Logging.configure( filename )

Configures the Logging framework using the configuration information found in the given file. The file extension should be either ‘.yaml’ or ‘.yml’ (XML configuration is not yet supported).



32
33
34
 
# File 'lib/logging.rb', line 32

def configure( filename, *args )
  ::Logging::Config::YamlConfigurator.load(filename, *args)
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

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



207
208
209
210
211
212
213
214
215
 
# File 'lib/logging.rb', line 207

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

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

  module_eval "OBJ_FORMAT = :#{f}"
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 only be invoked 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



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/logging.rb', line 169

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

  args.flatten!
  levels = ::Logging::LEVELS.clear
  names = ::Logging::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.values.inject {|x,y| (x.length > y.length) ? x : y}
  module_eval "MAX_LEVEL_LENGTH = #{longest.length}"

  levels.keys
end

.level_num(level) ⇒ Object

Convert the given level into a level number.



262
263
264
265
266
267
268
 
# File 'lib/logging.rb', line 262

def level_num( level )
  l = levelify 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 connaconical form - a lowercase string.



254
255
256
257
258
259
 
# File 'lib/logging.rb', line 254

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) ⇒ Object

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



227
228
229
 
# File 'lib/logging.rb', line 227

def libpath( *args )
  args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
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.



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

def logger( *args )
  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

.path(*args) ⇒ 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.



235
236
237
 
# File 'lib/logging.rb', line 235

def path( *args )
  args.empty? ? PATH : ::File.join(PATH, *args)
end

.require_all_libs_relative_to(fname, dir = nil) ⇒ Object

Utility method used to rquire all files ending in .rb that lie in the directory below this file that has the same name as the filename passed in. Optionally, a specific directory name can be passed in such that the filename does not have to be equivalent to the directory.



244
245
246
247
248
249
250
 
# File 'lib/logging.rb', line 244

def require_all_libs_relative_to( fname, dir = nil )
  dir ||= ::File.basename(fname, '.*')
  search_me = ::File.expand_path(
      ::File.join(::File.dirname(fname), dir, '*.rb'))

  Dir.glob(search_me).sort.each {|rb| require rb}
end

.version ⇒ Object

Returns the version string for the library.



219
220
221
 
# File 'lib/logging.rb', line 219

def version
  VERSION
end