Report wire format - v7

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.

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

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

  • "certname" is the certname the report is associated with.

  • "environment" is the environment associated to the node at the time of the report

  • "puppet_version" is the version of Puppet that was run to generate this report.

  • "report_format" is 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" is an identifier string that Puppet uses to match a specific catalog for a node to a specific Puppet run. This value is generated by Puppet.

  • "start_time" is the time on the agent at which the Puppet run began; see more details about the datetime format below.

  • "end_time" is the time on the agent at which the Puppet run completed; see more details about the datetime format below.

  • "producer_timestamp" is 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.

  • "transaction_uuid" is a string used to identify a Puppet run. It can be used to match a report with the catalog that was used for the run. This field may be null.

  • "catalog_uuid" is a string used to identify the catalog used to generate a report during a Puppet run. It can be used to match a report with the catalog that was used for the run. This field may be null.

  • "code_id" is a string used to match the catalog with the Puppet code which generated the report. This field may be null.

  • "cached_catalog_status" is a string used to identify 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" is a string used to identify the status of the Puppet run.

  • "noop" is a flag that indicates whether the report was produced with a --noop run.

  • "resources" is an array of objects of the following form:

    Copy 
    {
      "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:

    Copy 
    {
      "status": <status of event (`success`, `failure`, `noop`)>,
      "timestamp": <timestamp (from agent) at which event occurred>,
      "property": <property/parameter 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>,
    }

  • "metrics" is either null or an array of metric objects:

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

  • "logs" is either null or an array of log objects:

    Copy 
    {
      "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, 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:

Copy 
{
  "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:

Copy 
{
 "property": <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.

  • "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.