Formats: Reports

Sections

Puppet 5.5.3 uses report format 10.

Report Format 10

This is the format of reports output by Puppet versions 5.5.3 and newer. It is backward compatible with report format 9 (in Puppet versions 5.5.0 to 5.5.2).

Puppet::Transaction::Report

Property 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 Unix epoch.
transaction_uuid string A UUID covering the transaction. The query parameters for the catalog retrieval will have included the same UUID.
code_id string The id of the code input to the compiler.
job_id string, or null The id of the job that this transaction is a part of.
catalog_uuid string A master generated catalog uuid, useful for connecting a single catalog to multiple reports.
master_used string The name of the master that was used to compile the catalog. If failover occurred, this holds the first master successfully contacted. If this run had no master (for example, a "puppet apply" run), this field will be blank.
report_format string or integer "7", or 7
puppet_version string The version of the Puppet agent.
status string "failed", "changed", or "unchanged"
transaction_completed boolean Whether the transaction completed. For instance, if the transaction didn't have an unrescued exception, transaction_completed should be true.
noop boolean Whether or not the Puppet run was started in noop mode.
noop_pending boolean Whether or not there are changes that Puppet decided not to apply because of noop.
environment string The environment that was used for the puppet run.
corrective_change boolean True if a change or noop event in this report was caused by an unexpected change to the system between Puppet runs.
cached_catalog_status string Whether a cached catalog was used in the run, and if so, the reason that it was used. "not_used", "explicitly_requested", or "on_failure".

Puppet::Util::Log

Property 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.

Property Type Description
name string Specifies the 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, 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.

Property 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.
provider_used string The name of the provider used by the resource.
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.
failed_to_restart boolean True if Puppet experienced an error while trying to restart this resource (for example, when a Service resource has been notified from another resource), otherwise false.
containment_path array An array of strings; each element represents a container (type or class) that, together, make up the path of the resource in the catalog.

Puppet::Transaction::Event

A Puppet::Transaction::Event object represents a single event for a single resource.

Property 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. This value will be missing if the provider errored out before it could be determined.
previous_value string, array, or hash the value of the property before the change (if any) was applied. This value will be missing if the provider errored out before it could be determined.
desired_value string, array, or hash the value specified in the manifest. Absent in inspect reports. This value will be missing if the provider errored out before it could be determined.
historical_value string, array, or hash the audited value from a previous run of Puppet, if known. Otherwise nil. Absent in inspect reports. This value will be missing if the provider errored out before it could be determined.
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.
redacted boolean Whether or not this event has been redacted.
time datetime the time at which the property was evaluated
corrective_change boolean True if this event was caused by an unexpected change to the system between Puppet runs.

Puppet::Transaction::Event#status 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 9

  • failed_to_restart was added to Puppet::Resource::Status