Formats: Reports

Puppet 3 uses report format 3.

Report Format 3

This is the format of reports output by Puppet versions 2.7.12 and later, but the report version identifier did not get changed until Puppet 2.7.20 (See ticket #15739).

Puppet::Transaction::Report

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

name	type	description
host	string	the host that generated this report.
time	datetime	when the run began.
logs	array	0 or more Puppet::Util::Log objects.
metrics	hash	maps from string (metric category) to Puppet::Util::Metric.
resource_statuses	hash	maps from resource name to Puppet::Resource::Status
configuration_version	string or integer	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.
report_format	integer	3
puppet_version	string	The version of the Puppet agent.
kind	string	"inspect" if this report came from a "puppet inspect" run, "apply" if it came from a "puppet apply" or "puppet agent" run.
status	string	"failed", "changed", or "unchanged"
environment	string	The environment that was used for the puppet run.

Puppet::Util::Log

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

name	type	description
file	string	the pathname of the manifest file which triggered the log message.
line	integer	the line number in the manifest file which triggered the log message.
level	symbol	severity of the message. Possible values for level are :debug, :info, :notice, :warning, :err, :alert, :emerg, :crit
message	string	the message itself.
source	string	the origin of the log message. This could be a resource, a property of a resource, or the string "Puppet".
tags	array	each array element is a string.
time	datetime	when the message was sent.

The file and line attributes are not always present.

Puppet::Util::Metric

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

name	type	description
name	string	name of the metric category. This is the same as the key associated with this metric in the metrics hash of the Puppet::Transaction::Report.
label	string	This is the "titleized" version of the name, which means underscores are replaced with spaces and the first word is capitalized.
values	array	All 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, 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 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 two additional metrics, called config_retrieval and total. 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 reports contain no metrics.

In an inspect report, there is an additional inspect metric in the time category.

Puppet::Resource::Status

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

name	type	description
resource_type	string	the resource type, capitalized.
title	title	the resource title.
resource	string	the 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. *deprecated*
file	string	the pathname of the manifest file which declared the resource
line	integer	the line number in the manifest file which declared the resource
evaluation_time	float	the amount of time, in seconds, taken to evaluate the resource. Not present in inspect reports.
change_count	integer	the number of properties which changed. Always 0 in inspect reports.
out_of_sync_count	integer	the number of properties which were out of sync. Always 0 in inspect reports.
tags	array	the strings with which the resource is tagged
time	datetime	the time at which the resource was evaluated
events	array	the Puppet::Transaction::Event objects for the resource
out_of_sync	boolean	True if out_of_sync_count > 0, otherwise false. *deprecated*
changed	boolean	True if change_count > 0, otherwise false. *deprecated*
skipped	boolean	True if the resource was skipped, otherwise false.
failed	boolean	True if Puppet experienced an error while evaluating this resource, otherwise false. *deprecated*

Puppet::Transaction::Event

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

name	type	description
audited	boolean	true if this property is being audited, otherwise false. True in inspect reports.
property	string	the property for which the event occurred
previous_value	string, array, or hash	the value of the property before the change (if any) was applied.
desired_value	string, array, or hash	the value specified in the manifest. Absent in inspect reports.
historical_value	string, array, or hash	the audited value from a previous run of Puppet, if known. Otherwise nil. Absent in inspect reports.
message	string	the log message generated by this event
name	symbol	the name of the event. Absent in inspect reports.
status	string	one of the following strings: "success", "failure", "noop", "audit", depending on the type of the event (see below). Always "audit" in inspect reports.
time	datetime	the time at which the property was evaluated

Puppet::Transaction::Event#status has the following meanings:

• success: property was out of sync, and was successfully changed to be in sync.
• failure: property was out of sync, and couldn’t be changed to be in sync due to an error.
• noop: property was out of sync, and wasn’t changed due to noop mode.
• audit: property was in sync, and was being audited.

Differences from Report Format 2

• Puppet::Transaction::Report gained environment.

↑ Back to top