module Puppet::Util::Logging

clear_deprecation_warnings() click to toggle source

# File lib/puppet/util/logging.rb, line 84
def clear_deprecation_warnings
  $deprecation_warnings.clear if $deprecation_warnings
end

deprecation_warning(message) click to toggle source

Log a warning indicating that the code path is deprecated. Note that this method keeps track of the offending lines of code that triggered the deprecation warning, and will only log a warning once per offending line of code. It will also stop logging deprecation warnings altogether after 100 unique deprecation warnings have been logged. Parameters:

message: The message to log (logs via )

# File lib/puppet/util/logging.rb, line 64
def deprecation_warning(message)
  $deprecation_warnings ||= {}
  if $deprecation_warnings.length < 100 then
    offender = get_deprecation_offender()
    if (! $deprecation_warnings.has_key?(offender)) then
      $deprecation_warnings[offender] = message
      warning("#{message}\n   (at #{offender})")
    end
  end
end

format_exception(exception, message = :default, trace = true) click to toggle source

# File lib/puppet/util/logging.rb, line 30
def format_exception(exception, message = :default, trace = true)
  arr = []
  case message
  when :default
    arr << exception.message
  when nil
    # don't log anything if they passed a nil; they are just calling for the optional backtrace logging
  else
    arr << message
  end

  if trace and exception.backtrace
    arr << Puppet::Util.pretty_backtrace(exception.backtrace)
  end
  if exception.respond_to?(:original) and exception.original
    arr << "Wrapped exception:"
    arr << format_exception(exception.original, :default, trace)
  end
  arr.flatten.join("\n")
end

get_deprecation_offender() click to toggle source

# File lib/puppet/util/logging.rb, line 75
def get_deprecation_offender()
  # we have to put this in its own method to simplify testing; we need to be able to mock the offender results in
  # order to test this class, and our framework does not appear to enjoy it if you try to mock Kernel.caller
  #
  # let's find the offending line;  we need to jump back up the stack a few steps to find the method that called
  #  the deprecated method
  caller()[2]
end

log_and_raise(exception, message) click to toggle source

# File lib/puppet/util/logging.rb, line 51
def log_and_raise(exception, message)
  log_exception(exception, message)
  raise exception, message + "\n" + exception.to_s, exception.backtrace
end

log_deprecations_to_file(deprecations_file, pattern = nil) click to toggle source

utility method that can be called, e.g., from spec_helper config.after, when tracking down calls to deprecated code. Parameters:

deprecations_file: relative or absolute path of a file to log the deprecations to
pattern: (default nil) if specified, will only log deprecations whose message matches the provided pattern

# File lib/puppet/util/logging.rb, line 96
def log_deprecations_to_file(deprecations_file, pattern = nil)
  # this method may get called lots and lots of times (e.g., from spec_helper config.after) without the global
  # list of deprecation warnings being cleared out.  We don't want to keep logging the same offenders over and over,
  # so, we need to keep track of what we've logged.
  #
  # It'd be nice if we could just clear out the list of deprecation warnings, but then the very next spec might
  # find the same offender, and we'd end up logging it again.
  $logged_deprecation_warnings ||= {}

  File.open(deprecations_file, "a") do |f|
    if ($deprecation_warnings) then
      $deprecation_warnings.each do |offender, message|
        if (! $logged_deprecation_warnings.has_key?(offender)) then
          $logged_deprecation_warnings[offender] = true
          if ((pattern.nil?) || (message =~ pattern)) then
            f.puts(message)
            f.puts(offender)
            f.puts()
          end
        end
      end
    end
  end
end

log_exception(exception, message = :default, options = {}) click to toggle source

Log an exception via Puppet.err. Will also log the backtrace if Puppet is set. Parameters:

exception: an Exception to log
message: an optional String overriding the message to be logged; by default, we log Exception.message.

If you pass a String here, your string will be logged instead.  You may also pass nil if you don't
wish to log a message at all; in this case it is likely that you are only calling this method in order
to take advantage of the backtrace logging.

# File lib/puppet/util/logging.rb, line 26
def log_exception(exception, message = :default, options = {})
  err(format_exception(exception, message, Puppet[:trace] || options[:trace]))
end

send_log(level, message) click to toggle source

# File lib/puppet/util/logging.rb, line 7
def send_log(level, message)
  Puppet::Util::Log.create({:level => level, :source => log_source, :message => message}.merge(log_metadata))
end

Public Instance Methods