1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
---
title: "Report wire format, version 7"
layout: default
canonical: "/puppetdb/latest/api/wire_format/report_format_v6.html"
---
# 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.
{
"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:
{
"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>,
"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:
{
"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:
{
"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:
{
"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>,
"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`.
|
