---
title: "PuppetDB 2.2 » API » Report Wire Format, Version 5"
layout: default
canonical: "/puppetdb/latest/api/wire_format/report_format_v5.html"
---

[puppetreportformat]: http://docs.puppetlabs.com/puppet/latest/reference/format_report.html
[reportsv4]: ../query/v4/reports.markdown

## 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>,
        "resource_events": [<resource_event>, <resource_event>, ...],
        "metrics": [<metric>, <metric>, ...],
        "logs": [<log>, <log>, ...],
        "transaction_uuid": <string>,
        "status": <string>,
        "noop": <boolean>
    }

**NOTE** `metrics` and `logs` may also take the value null.

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 master to
PuppetDB.  This field is currently populated by the master. 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`.

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

`"resource_events"` is an array of objects of the following form:

    {
      "status": <status of event (`success`, `failure`, `noop`, or `skipped`)>,
      "timestamp": <timestamp (from agent) at which event occurred>,
      "resource_type": <type of resource event occurred on>,
      "resource_title": <title of resource event occurred on>,
      "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>,
      "file": <manifest file containing resource definition>,
      "line": <line in manifest file on which resource is defined>,
      "containment_path": <containment heirarchy of resource within catalog>
    }

`"metrics"` is either null or an array of metric objects like so:

    {
      "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 like so:

    {
      "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 on 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 int.

### Data type: `<datetime>`

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

### Data type: `<resource_event>`

A JSON Object of the following form:

    {
     "resource_type": <string>,
     "resource_title": <string>,
     "property": <string>,
     "timestamp": <datetime>,
     "status": <string>,
     "old_value": <string>,
     "new_value": <string>,
     "message": <string>,
     "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.

`"property"` is the name of the property of the resource for which the event occurred.
This may be `null` only if the `status` is `skipped`.

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

`"status"` is a string representing the outcome of the event; this should be one
of `success`, `failure`, or `skipped`.

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

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

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