module Puppet::Util::Logging

Public Class Methods

setup_facter_logging!() click to toggle source

Sets up Facter logging. This method causes Facter output to be forwarded to Puppet.

    # File lib/puppet/util/logging.rb
255 def self.setup_facter_logging!
256   Puppet.runtime[:facter]
257   true
258 end

Public Instance Methods

clear_deprecation_warnings() click to toggle source

    # File lib/puppet/util/logging.rb
214 def clear_deprecation_warnings
215   $unique_warnings.clear if $unique_warnings
216   $deprecation_warnings.clear if $deprecation_warnings
217 end

debug(*args) { |*args| ... } click to toggle source

Output a debug log message if debugging is on (but only then) If the output is anything except a static string, give the debug a block - it will be called with all other arguments, and is expected to return the single string result.

Use a block at all times for increased performance.

@example This takes 40% of the time compared to not using a block

Puppet.debug { "This is a string that interpolated #{x} and #{y} }"

   # File lib/puppet/util/logging.rb
33 def debug(*args)
34   return nil unless Puppet::Util::Log.level == :debug
35   if block_given?
36     send_log(:debug, yield(*args))
37   else
38     send_log(:debug, args.join(" "))
39   end
40 end

deprecation_warning(message, key = nil) click to toggle source

Logs a warning indicating that the Ruby 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. Finally, if Puppet includes 'deprecations', it will squelch all warning calls made via this method.

@param message [String] The message to log (logs via warning) @param key [String] Optional key to mark the message as unique. If not

passed in, the originating call line will be used instead.

    # File lib/puppet/util/logging.rb
141 def deprecation_warning(message, key = nil)
142   issue_deprecation_warning(message, key, nil, nil, true)
143 end

format_backtrace(exception, combined_trace, puppet_trace) click to toggle source

    # File lib/puppet/util/logging.rb
111 def format_backtrace(exception, combined_trace, puppet_trace)
112   puppetstack = exception.respond_to?(:puppetstack) ? exception.puppetstack : []
113 
114   if combined_trace and exception.backtrace
115     Puppet::Util.format_backtrace_array(exception.backtrace, puppetstack)
116   elsif puppet_trace && !puppetstack.empty?
117     Puppet::Util.format_backtrace_array(puppetstack)
118   else
119     []
120   end
121 end

format_exception(exception, message = :default, combined_trace = true, puppet_trace = false) click to toggle source

    # File lib/puppet/util/logging.rb
 90 def format_exception(exception, message = :default, combined_trace = true, puppet_trace = false)
 91   arr = []
 92   case message
 93   when :default
 94     arr << exception.message
 95   when nil
 96     # don't log anything if they passed a nil; they are just calling for the optional backtrace logging
 97   else
 98     arr << message
 99   end
100 
101   arr += format_backtrace(exception, combined_trace, puppet_trace)
102 
103   if exception.respond_to?(:original) and exception.original
104     arr << _("Wrapped exception:")
105     arr << format_exception(exception.original, :default, combined_trace, puppet_trace)
106   end
107 
108   arr.flatten.join("\n")
109 end

get_deprecation_offender() click to toggle source

    # File lib/puppet/util/logging.rb
201 def get_deprecation_offender()
202   # we have to put this in its own method to simplify testing; we need to be able to mock the offender results in
203   # order to test this class, and our framework does not appear to enjoy it if you try to mock Kernel.caller
204   #
205   # let's find the offending line;  we need to jump back up the stack a few steps to find the method that called
206   #  the deprecated method
207   if Puppet[:trace]
208     caller(3)
209   else
210     [caller(3, 1).first]
211   end
212 end

log_and_raise(exception, message) click to toggle source

    # File lib/puppet/util/logging.rb
123 def log_and_raise(exception, message)
124   log_exception(exception, message)
125   raise exception, message + "\n" + exception.to_s, exception.backtrace
126 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
227 def log_deprecations_to_file(deprecations_file, pattern = nil)
228   # this method may get called lots and lots of times (e.g., from spec_helper config.after) without the global
229   # list of deprecation warnings being cleared out.  We don't want to keep logging the same offenders over and over,
230   # so, we need to keep track of what we've logged.
231   #
232   # It'd be nice if we could just clear out the list of deprecation warnings, but then the very next spec might
233   # find the same offender, and we'd end up logging it again.
234   $logged_deprecation_warnings ||= {}
235 
236   # Deprecation messages are UTF-8 as they are produced by Ruby
237   Puppet::FileSystem.open(deprecations_file, nil, "a:UTF-8") do |f|
238     if ($deprecation_warnings) then
239       $deprecation_warnings.each do |offender, message|
240         if (! $logged_deprecation_warnings.has_key?(offender)) then
241           $logged_deprecation_warnings[offender] = true
242           if ((pattern.nil?) || (message =~ pattern)) then
243             f.puts(message)
244             f.puts(offender)
245             f.puts()
246           end
247         end
248       end
249     end
250   end
251 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
49 def log_exception(exception, message = :default, options = {})
50   level = options[:level] || :err
51   combined_trace = Puppet[:trace] || options[:trace]
52   puppet_trace = Puppet[:puppet_trace] || options[:puppet_trace]
53 
54   if message == :default && exception.is_a?(Puppet::ParseErrorWithIssue)
55     # Retain all detailed info and keep plain message and stacktrace separate
56     backtrace = build_exception_trace(exception, combined_trace, puppet_trace)
57     Puppet::Util::Log.create({
58         :level => level,
59         :source => log_source,
60         :message => exception.basic_message,
61         :issue_code => exception.issue_code,
62         :backtrace => backtrace.empty? ? nil : backtrace,
63         :file => exception.file,
64         :line => exception.line,
65         :pos => exception.pos,
66         :environment => exception.environment,
67         :node => exception.node
68       }.merge(log_metadata))
69   else
70     send_log(level, format_exception(exception, message, combined_trace, puppet_trace))
71   end
72 end

puppet_deprecation_warning(message, options = {}) click to toggle source

Logs a warning whose origin comes from Puppet source rather than somewhere internal within Puppet. Otherwise the same as deprecation_warning()

@param message [String] The message to log (logs via warning) @param options [Hash] @option options [String] :file File we are warning from @option options [Integer] :line Line number we are warning from @option options [String] :key (:file + :line) Alternative key used to mark

warning as unique

Either :file and :line and/or :key must be passed.

    # File lib/puppet/util/logging.rb
156 def puppet_deprecation_warning(message, options = {})
157   key = options[:key]
158   file = options[:file]
159   line = options[:line]
160   #TRANSLATORS the literals ":file", ":line", and ":key" should not be translated
161   raise Puppet::DevError, _("Need either :file and :line, or :key") if (key.nil?) && (file.nil? || line.nil?)
162 
163   key ||= "#{file}:#{line}"
164   issue_deprecation_warning(message, key, file, line, false)
165 end

send_log(level, message) click to toggle source

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

warn_once(kind, key, message, file = nil, line = nil, level = :warning) click to toggle source

Logs a (non deprecation) warning once for a given key.

@param kind [String] The kind of warning. The

kind must be one of the defined kinds for the Puppet[:disable_warnings] setting.

@param message [String] The message to log (logs via warning) @param key [String] Key used to make this warning unique @param file [String,:default,nil] the File related to the warning @param line [Integer,:default,nil] the Line number related to the warning

warning as unique

@param level [Symbol] log level to use, defaults to :warning

Either :file and :line and/or :key must be passed.

    # File lib/puppet/util/logging.rb
179 def warn_once(kind, key, message, file = nil, line = nil, level = :warning)
180   return if Puppet[:disable_warnings].include?(kind)
181   $unique_warnings ||= {}
182   if $unique_warnings.length < 100 then
183     if (! $unique_warnings.has_key?(key)) then
184       $unique_warnings[key] = message
185       call_trace = if file == :default and line == :default
186                      # Suppress the file and line number output
187                      ''
188                    else
189                      error_location_str = Puppet::Util::Errors.error_location(file, line)
190                      if error_location_str.empty?
191                        "\n   " + _('(file & line not available)')
192                      else
193                        "\n   %{error_location}" % { error_location: error_location_str }
194                      end
195                    end
196       send_log(level, "#{message}#{call_trace}")
197     end
198   end
199 end

Private Instance Methods

build_exception_trace(exception, combined_trace = true, puppet_trace = false) click to toggle source

   # File lib/puppet/util/logging.rb
74 def build_exception_trace(exception, combined_trace = true, puppet_trace = false)
75   built_trace = format_backtrace(exception, combined_trace, puppet_trace)
76 
77   if exception.respond_to?(:original)
78     original =  exception.original
79     unless original.nil?
80       built_trace << _('Wrapped exception:')
81       built_trace << original.message
82       built_trace += build_exception_trace(original, combined_trace, puppet_trace)
83     end
84   end
85 
86   built_trace
87 end

is_resource?() click to toggle source

    # File lib/puppet/util/logging.rb
280 def is_resource?
281   defined?(Puppet::Type) && is_a?(Puppet::Type)
282 end

is_resource_parameter?() click to toggle source

    # File lib/puppet/util/logging.rb
284 def is_resource_parameter?
285   defined?(Puppet::Parameter) && is_a?(Puppet::Parameter)
286 end

issue_deprecation_warning(message, key, file, line, use_caller) click to toggle source

    # File lib/puppet/util/logging.rb
262 def issue_deprecation_warning(message, key, file, line, use_caller)
263   return if Puppet[:disable_warnings].include?('deprecations')
264   $deprecation_warnings ||= {}
265   if $deprecation_warnings.length < 100
266     key ||= (offender = get_deprecation_offender)
267     unless $deprecation_warnings.has_key?(key)
268       $deprecation_warnings[key] = message
269       # split out to allow translation
270       call_trace = if use_caller
271                      _("(location: %{location})") % { location: (offender || get_deprecation_offender).join('; ') }
272                    else
273                      Puppet::Util::Errors.error_location_with_unknowns(file, line)
274                    end
275       warning("%{message}\n   %{call_trace}" % { message: message, call_trace: call_trace })
276     end
277   end
278 end

log_metadata() click to toggle source

    # File lib/puppet/util/logging.rb
288 def log_metadata
289   [:file, :line, :tags].inject({}) do |result, attr|
290     result[attr] = send(attr) if respond_to?(attr)
291     result
292   end
293 end

log_source() click to toggle source

    # File lib/puppet/util/logging.rb
295 def log_source
296   # We need to guard the existence of the constants, since this module is used by the base Puppet module.
297   (is_resource? or is_resource_parameter?) and respond_to?(:path) and return path.to_s
298   to_s
299 end