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