The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

« Previous - Version 5/15 (diff) - Next » - Current version
Paul Berry, 12/28/2010 10:57 pm
Documented differences from report format 1


Report Format 2

This is the format of reports that is output by Puppet version 2.6.5.

The Puppet::Transaction::Report contains the following attributes:

nametypedescription
hoststringthe host that generated this report.
timedatetimewhen the run completed.
logsarray0 or more Puppet::Util::Log objects.
metricshashmaps from string (metric category) to Puppet::Util::Metric.
resource_statuseshashmaps from resource name to Puppet::Resource::Status
external_timeshashthis is always a hash from :config_retrieval to a float
configuration_versionstring or integerThe "configuration version" of the puppet run. This is a string if the user has specified their own versioning scheme, otherwise an integer representing seconds since the epoch.
report_formatinteger2
puppet_versionstringThe version of the Puppet agent.
kindstring"inspect" if this report came from a "puppet inspect" run, "apply" if it came from a "puppet apply" or "puppet agent" run.

A Puppet::Util::Log object contains the following attributes:

nametypedescription
filestringthe pathname of the manifest file which triggered the log message.
lineintegerthe line number in the manifest file which triggered the log message.
levelsymbolseverity of the message. Possible values for level are :debug, :info, :notice, :warning, :err, :alert, :emerg, :crit
messagestringthe message itself.
sourcestringthe origin of the log message. This could be a resource, a property of a resource, or the string "Puppet".
tagsarrayeach array element is a string.
timedatetimewhen the message was sent.
versionstring or integerIf the source is not "Puppet", this is the "configuration version" of the puppet run. This is a string if the user has specified their own versioning scheme, otherwise an integer representing seconds since the epoch. If the source is "Puppet", this is the Puppet version of the agent.

The “file” and “line” attributes are not always present.

A Puppet::Util::Metric object represents all the metrics in a single category. It contains the following attributes:

nametypedescription
namestringname of the metric category. This is the same as the key associated with this metric in the metrics hash of the Puppet::Transaction::Report.
labelstringThis is the "titleized" version of the name, which means underscores are replaced with spaces and the first word is capitalized.
valuesarrayAll the metric values within this category. Each element is of the form [name, titleized_name, value], where name is the name of the particular metric as a string or symbol, titleized_name is the "titleized" string of the name, and value is the quantity (an integer or a float).

The set of particular metrics and categories which appear in a report is a fixed set. In a successful apply report, the categories and metrics are:

  • In the “time” category, there is a metric for every resource type for which there is at least one resource in the catalog, plus an additional metric, called :config_retrieval. Each value in the “time” category is a float.
  • In the “resources” category, the metrics are :failed, :out_of_sync, :changed, and :total. Each value in the “resources” category is an integer.
  • In the “events” category, there are up to five metrics: “success”, “failure”, “audit”, “noop”, and :total. :total is always present; the others are only present when their values are non-zero. Each value in the “events” category is an integer.
  • In the “changes” category, there is only one metric, called :total. Its value is an integer.

Failed apply reports contain no metrics.

In an inspect report, the categories and metrics are:

  • In the “time” category, there are two metrics: “config_retrieval” and “inspect”. Both are floats.

A Puppet::Resource::Status object represents the status of a single resource. It contains the following attributes:

nametypedescription
resourcestringthe resource name, in the form Type[title]. This is always the same as the key corresponding to this Puppet::Resource::Status object in the resource_statuses hash.
filestringthe pathname of the manifest file which declared the resource
lineintegerthe line number in the manifest file which declared the resource
evaluation_timefloatthe amount of time, in seconds, taken to evaluate the resource. Not present in inspect reports.
change_countintegerthe number of properties which changed. Always 0 in inspect reports.
out_of_sync_countintegerthe number of properties which were out of sync. Always 0 in inspect reports.
source_descriptionstringthe path of the resource
tagsarraythe strings with which the resource is tagged
timedatetimethe time at which the resource was evaluated
versionstring or integerthe "configuration version" of the puppet run. For an apply report, this is the version of the run that produced the report. For an inspect report, this is the version recorded from the catalog that is being used as a reference.
eventsarraythe Puppet::Transaction::Event objects for the resource
out_of_syncbooleanTrue if out_of_sync_count > 0, otherwise absent
changedbooleanTrue if change_count > 0, otherwise absent

A Puppet::Transaction::Event object represents a single event for a single resource. It contains the following attributes:

nametypedescription
resourcestringthe resource name, in the form Type[title]. This is the same as the resource property of the Puppet::Resource::Status object.
auditedbooleantrue if this property is being audited, otherwise absent. Absent in inspect reports.
propertystringthe property for which the event occurred
previous_valuestring, array, or hashthe value of the property before the change (if any) was applied.
desired_valuestring, array, or hashthe value specified in the manifest. Absent in inspect reports.
historical_valuestring, array, or hashthe audited value from a previous run of Puppet, if known. Otherwise nil. Absent in inspect reports.
filestringthe pathname of the manifest file which declared the resource
lineintegerthe line number in the manifest file which declared the resource
default_log_levelsymbolthe level at which messages for this resource are logged
messagestringthe log message generated by this event
namesymbolthe name of the event. Absent in inspect reports.
source_descriptionstringthe path to the property. Absent in inspect reports.
statusstringone of the following strings: "success", "failure", "noop", "audit", depending on the type of the event. Always "audit" in inspect reports.
timedatetimethe time at which the property was evaluated
versionstring or integerthe "configuration version" of the puppet run

Differences from format 1

  • Puppet::Transaction::Report gained the properties configuration_version, report_format, puppet_version, and kind.
  • In Puppet::Resource::Status, change_count, changed, and out_of_sync have new meanings, and out_of_sync_count has been added.
  • In Puppet::Transaction::Event, the “audited” and “historical_value” properties have been added. The meaning of “previous_value” and “desired_value” has changed.