Report wire format - v8

Report interchange format

A report is represented as JSON (this implies UTF-8 encoding). Unless otherwise noted, null is not allowed anywhere in the report.

{
    "certname": <string>,
    "environment": <string>,
    "puppet_version": <string>,
    "report_format": <int>,
    "configuration_version": <string>,
    "start_time": <datetime>,
    "end_time": <datetime>,
    "producer_timestamp": <datetime>,
    "producer": <string>,
    "resources": [<resource>, <resource>, ...],
    "metrics": [<metric>, <metric>, ...],
    "logs": [<log>, <log>, ...],
    "transaction_uuid": <string>,
    "catalog_uuid": <string>,
    "code_id": <string>,
    "job_id": <string>,
    "cached_catalog_status": <string>,
    "status": <string>,
    "noop": <boolean>,
    "corrective_change": <boolean>,
    "noop_pending": <boolean>,
    "type": <string>
}

All keys are mandatory unless otherwise noted, though values that are lists may be empty lists.

certname

String. The certname the report is associated with.

environment

String. The environment associated to the node at the time of the report.

puppet_version

String. The version of Puppet that was run to generate this report.

report_format

Integer. The version number of the report format that Puppet used to generate the original report data. This is a constant defined by Puppet.

configuration_version

String. An identifier that Puppet uses to match a specific catalog for a node to a specific Puppet run. This value is generated by Puppet.

start_time

DateTime. The time on the agent at which the Puppet run began; see more details about the datetime format below.

end_time

DateTime. The time on the agent at which the Puppet run completed; see more details about the datetime format below.

producer_timestamp

DateTime. The time of catalog submission from the Puppet Server to PuppetDB. This field is currently populated by the Puppet Server. See more details about the datetime format below.

producer

String. The certname of the Puppet Server that sent the report to PuppetDB. This field may be null.

transaction_uuid

String. A string used to match the report to a Puppet run, and when not using cached catalogs, to its corresponding catalog. This field may be null.

catalog_uuid

String. A string used to identify the report with the catalog that generated it, when using cached ctalogs. This field may be null.

code_id

String. A string used to match the catalog with the Puppet code that generated it. For example, a git sha. This field may be null.

job_id

String. A string used to match a report to a Puppet run initiated by the Puppet Enterprise Orchestrator.

cached_catalog_status

String. Used to represent whether the Puppet run used a cached catalogs and whether or not the cached catalog was used due to an error or not. This field may be null.

status

String. The status of the Puppet run.

noop

Boolean. Indicates whether the report was resulted from a noop Puppet run.

noop_pending

Boolean. A flag indicating whether the report contained "noop" events. These may result from use of the --noop flag, or from resources tagged with the noop parameter. This field may be null.

corrective_change

Boolean. A flag indicating whether the report contained changes to correct configuration drift. This field may be null.

type

String. A string that indicates the source of the report. Valid values are agent or plan. If this field is absent in the command type defaults to the value of agent.

resources

Array. An array of objects of the following form:

{
  "timestamp": <timestamp (from agent) when the resource was managed>,
  "resource_type": <type of resource>,
  "resource_title": <title of resource>,
  "skipped" : <boolean for whether or not the resource was skipped>,
  "events" : [<event>, <event>, ...]
  "file": <manifest file containing resource definition>,
  "line": <line in manifest file on which resource is defined>,
  "containment_path": <containment heirarchy of resource within catalog>
}

In each <resource> object "events" is an array of objects of the following form:

{
  "status": <status of event (`success`, `failure`, `noop`)>,
  "timestamp": <timestamp (from agent) at which event occurred>,
  "property": <property/parameter of resource on which event occurred>,
  "name": <name of resource on which event occurred>,
  "new_value": <new value for resource property>,
  "old_value": <old value of resource property>,
  "message": <description of what happened during event>,
  "corrective_change": <flag indicating whether the event corrected system drift>
}

metrics

Array. An array of metric objects (below) or null.

{
  "category" : <category of metric ("resources", "time", "changes", or "events")>,
  "name" : <name of the metric>,
  "value" : <value of the metric (double precision)>
}

logs

Array. An array of log objects (below) or null.

{
  "file" : <file of resource declaration>,
  "line" : <line of resource declaration>,
  "level" : <log level>,
  "message" : <log message>,
  "source" : <log source>,
  "tags" : [<resource tag>],
  "time" : <log line timestamp>
 }

Note: Fields that allow NULL values In the resource_event schema above, containment_path, new_value, old_value, property, file, line, status, corrective_change, and message may all be null.

Encoding

The entire report is expected to be valid JSON, which implies UTF-8 encoding.

Data type: <string>

A JSON string. By virtue of the report being UTF-8, these must also be UTF-8.

Data type: <integer>

A JSON integer.

Data type: <datetime>

A JSON string representing a date and time (with time zone), formatted based on the recommendations in ISO 8601. For example, for a UTC time, the string would be formatted as YYYY-MM-DDThh:mm:ss.sssZ. For non-UTC time, the Z may be replaced with ±hh:mm to represent the specific timezone.

Data type: <resource>

A JSONObject of the following form:

{
  "timestamp": <datetime>,
  "resource_type": <type>,
  "resource_title": <title>,
  "skipped" : <boolean>,
  "events" : [<event>, <event>, ...]
  "file": <string>,
  "line": <integer>,
  "containment_path": [<string>, <string>, ...]
}

All keys are required.

"resource_type" is the name of the Puppet resource type that the event occurred on.

"resource_title" is the title of the Puppet resource that the event occurred on.

"timestamp" is the date/time at which the resource's events occurred.

"status" is a string representing the outcome of the event. Possible values are success, failure, and noop.

"skipped" is a Boolean representing whether or not the resource was skipped during the Puppet run; a skipped resource should have an empty list of "events".

"containment_path" is a collection of strings where each string is a Puppet type or class that represents the containment hierarchy of the resource within the catalog. This field may be null.

"events" is a collection of objects where each is a Puppet event corresponding to the resource. This array may be empty.

"file" is the manifest in which the resource is defined. This field may be null.

"line" is the line number (within "file") where the resource is defined. This field may be null.

Data type: <event>

A JSONObject of the following form:

{
 "property": <string>,
 "name": <string>,
 "timestamp": <datetime>,
 "status": <string>,
 "old_value": <string>,
 "new_value": <string>,
 "message": <string>
}

All keys are required.

"timestamp" is the date/time at which the event occurred.

"property" is the name of the property of the resource for which the event occurred.

"name" is the name of the resource for which the event occurred.

"old_value" is the value that Puppet determined the property to have held prior to the event.

"new_value" is the value that Puppet was instructed to set the property to.

"message" is a descriptive message providing extra information about the event. This should be null if status is success.