1---
2title: "Report wire format, version 5"
3layout: default
4canonical: "/puppetdb/latest/api/wire_format/report_format_v5.html"
5---
6# Report wire format - v5
7
8[puppetreportformat]: https://puppet.com/docs/puppet/latest/format_report.html
9[reportsv4]: ../query/v4/reports.markdown
10
11## Report interchange format
12
13A report is represented as JSON (this implies UTF-8 encoding). Unless
14otherwise noted, `null` is not allowed anywhere in the report.
15
16    {
17        "certname": <string>,
18        "environment": <string>,
19        "puppet_version": <string>,
20        "report_format": <int>,
21        "configuration_version": <string>,
22        "start_time": <datetime>,
23        "end_time": <datetime>,
24        "producer_timestamp": <datetime>,
25        "resource_events": [<resource_event>, <resource_event>, ...],
26        "metrics": [<metric>, <metric>, ...],
27        "logs": [<log>, <log>, ...],
28        "transaction_uuid": <string>,
29        "status": <string>,
30        "noop": <boolean>
31    }
32
33>**Note:** `metrics` and `logs` may also take the value `null`.
34
35All keys are mandatory unless otherwise noted, though values that are lists may be empty lists.
36
37`"certname"` is the certname the report is associated with.
38
39`"environment"` is the environment associated to the node at the time of the report
40
41`"puppet_version"` is the version of Puppet that was run to generate this report.
42
43`"report_format"` is the version number of the report format that Puppet used
44to generate the original report data. This is a constant defined by Puppet.
45
46`"configuration_version"` is an identifier string that Puppet uses to match a
47specific catalog for a node to a specific Puppet run. This value is
48generated by Puppet.
49
50`"start_time"` is the time on the agent at which the Puppet run began; see more
51details about the `datetime` format below.
52
53`"end_time"` is the time on the agent at which the Puppet run completed; see
54more details about the `datetime` format below.
55
56`"producer_timestamp"` is the time of catalog submission from the Puppet Server to
57PuppetDB. This field is currently populated by the Puppet Server. See more details
58about the `datetime` format below.
59
60`"transaction_uuid"` is a string used to identify a Puppet run. It can be used to
61match a report with the catalog that was used for the run. This field may be `null`.
62
63`"status"` is a string used to identify the status of the Puppet run.
64
65`"noop"` is a flag that indicates whether the report was produced with a `--noop` run.
66
67`"resource_events"` is an array of objects of the following form:
68
69    {
70      "status": <status of event (`success`, `failure`, `noop`, or `skipped`)>,
71      "timestamp": <timestamp (from agent) at which event occurred>,
72      "resource_type": <type of resource event occurred on>,
73      "resource_title": <title of resource event occurred on>,
74      "property": <property/parameter of resource on which event occurred>,
75      "new_value": <new value for resource property>,
76      "old_value": <old value of resource property>,
77      "message": <description of what happened during event>,
78      "file": <manifest file containing resource definition>,
79      "line": <line in manifest file on which resource is defined>,
80      "containment_path": <containment heirarchy of resource within catalog>
81    }
82
83`"metrics"` is either null or an array of metric objects:
84
85    {
86      "category" : <category of metric ("resources", "time", "changes", or "events")>,
87      "name" : <name of the metric>,
88      "value" : <value of the metric (double precision)>
89    }
90
91`"logs"` is either null or an array of log objects:
92
93    {
94      "file" : <file of resource declaration>,
95      "line" : <line of resource declaration>,
96      "level" : <log level>,
97      "message" : <log message>,
98      "source" : <log source>,
99      "tags" : [<resource tag>],
100      "time" : <log line timestamp>
101     }
102
103>**Note: Fields that allow `null` values**
104>In the resource_event schema above, `containment_path`, `new_value`, `old_value`, `property`, `file`, `line`, `status`, and `message` may all be null.
105
106### Encoding
107
108The entire report is expected to be valid JSON, which implies UTF-8
109encoding.
110
111### Data type: `<string>`
112
113A JSON string. By virtue of the report being UTF-8, these must also
114be UTF-8.
115
116### Data type: `<integer>`
117
118A JSON integer.
119
120### Data type: `<datetime>`
121
122A JSON string representing a date and time (with time zone), formatted based on
123the recommendations in ISO 8601. For example, for a UTC time, the string would be
124formatted as `YYYY-MM-DDThh:mm:ss.sssZ`. For non-UTC time, the `Z` may be replaced
125with `±hh:mm` to represent the specific timezone.
126
127### Data type: `<resource_event>`
128
129A JSONObject of the following form:
130
131    {
132     "resource_type": <string>,
133     "resource_title": <string>,
134     "property": <string>,
135     "timestamp": <datetime>,
136     "status": <string>,
137     "old_value": <string>,
138     "new_value": <string>,
139     "message": <string>,
140     "file": <string>,
141     "line: <integer>,
142     "containment_path": [<string>, <string>, ...]
143    }
144
145All keys are required.
146
147`"resource_type"` is the name of the Puppet resource type that the event occurred on.
148
149`"resource_title"` is the title of the Puppet resource that the event occurred on.
150
151`"property"` is the name of the property of the resource for which the event occurred.
152This may be `null` only if the `status` is `skipped`.
153
154`"timestamp"` is the date/time at which the event occurred.
155
156`"status"` is a string representing the outcome of the event. Possible values are `success`, `failure`, and `skipped`.
157
158`"old_value"` is the value that Puppet determined the property to have held prior
159to the event.
160
161`"new_value"` is the value that Puppet was instructed to set the property to.
162
163`"message"` is a descriptive message providing extra information about the event.
164This should be `null` if `status` is `success`.
165
166`"file"` is the manifest in which the resource is defined. This field may be `null`.
167
168`"line"` is the line number (within `"file"`) where the resource is defined. This field may be `null`.
169
170`"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`.
171