| title | layout | canonical |
|---|---|---|
PuppetDB 2.0 » API » v3 » Querying Events |
default |
/puppetdb/latest/api/query/v3/events.html |
This will return all resource events matching the given query. (Resource events are generated from Puppet reports.)
query: Required. A JSON array of query predicates, in prefix form (the standard["<OPERATOR>", "<FIELD>", "<VALUE>"]format), conforming to the format described below.
The query parameter is described by the following grammar:
query: [ {bool} {query}+ ] | [ "not" {query} ] | [ {match} {field} {value} ] | [ {inequality} {field} {value} ]
field: FIELD (conforming to [Fields](#fields) specification below)
value: string
bool: "or" | "and"
match: "=" | "~"
inequality: ">" | ">=" | "<" | "<="
For example, for all events in the report with hash '38ff2aef3ffb7800fe85b322280ade2b867c8d27', the JSON query structure would be:
["=", "report", "38ff2aef3ffb7800fe85b322280ade2b867c8d27"]
To retrieve all of the events within a given time period:
["and", ["<", "timestamp", "2011-01-01T12:01:00-03:00"],
[">", "timestamp", "2011-01-01T12:00:00-03:00"]]
To retrieve all of the 'failure' events for nodes named 'foo.*' and resources of type 'Service':
["and", ["=", "status", "failure"],
["~", "certname", "^foo\\."],
["=", "resource-type", "Service"]]
To retrieve latest events that are tied to the class found in your update.pp file
["and", ["=", "latest-report?", true],
["~", "file", "update.pp"]]
For more information on the available values for FIELD, see the fields section below.
distinct-resources: Optional. (EXPERIMENTAL: it is possible that the behavior of this parameter may change in future releases.) If specified, then in addition to the normal event query filtering, the result set will be limited to only returning the most recent event for a given resource on a given node.
So, for example, if the resource File[/tmp/foo] was failing on a certain node,
but has since been fixed and is now succeeding, then a "normal" event query might
return both the success and failure events. Using the distinct-resources flag
ensures that your query only returns the most recent event for a given resource,
so you would only get the success event in your result set.
The distinct-resources query can be expensive; therefore, it requires two
additional query parameters to go along with it: distinct-start-time and
distinct-end-time. (Issuing a distinct-resources query without
specifying both of these parameters will cause an error.) The values of these
parameters should be timestamp strings in the same format as used with the normal
"timestamp" field, and will define a window of time in which to find the most
recent event for each resource.
See the Operators page for the full list of available operators.
Note that inequality operators (<, >, <=, >=) are only supported against
the timestamp FIELD.
FIELD may be any of the following. Unless otherwise noted, all fields support
both equality and regular expression match operators, but do not support inequality
operators.
certname
: the name of the node that the event occurred on.
report
: the id of the report that the event occurred in; these ids can be acquired
via event queries or via the /reports query endpoint.
status
: the status of the event; legal values are success, failure, noop, and skipped.
timestamp
: the timestamp (from the puppet agent) at which the event occurred. This field
supports the inequality operators. All values should be specified as ISO-8601
compatible date/time strings.
run-start-time
: the timestamp (from the puppet agent) at which the puppet run began. This field
supports the inequality operators. All values should be specified as ISO-8601
compatible date/time strings.
run-end-time
: the timestamp (from the puppet agent) at which the puppet run finished. This field
supports the inequality operators. All values should be specified as ISO-8601
compatible date/time strings.
report-receive-time
: the timestamp (from the PuppetDB server) at which the puppet report was
received. This field supports the inequality operators. All values should be
specified as ISO-8601 compatible date/time strings.
resource-type
: the type of resource that the event occurred on; e.g., File, Package, etc.
resource-title
: the title of the resource that the event occurred on
property:
: the property/parameter of the resource that the event occurred on; e.g., for a
Package resource, this field might have a value of ensure. NOTE: this field
may contain NULL values; see notes below.
new-value
: the new value that Puppet was attempting to set for the specified resource
property. NOTE: this field may contain NULL values; see notes below.
old-value
: the previous value of the resource property, which Puppet was attempting to
change. NOTE: this field may contain NULL values; see notes below.
message
: a description (supplied by the resource provider) of what happened during the
event. NOTE: this field may contain NULL values; see notes below.
file
: the manifest file in which the resource definition is located.
NOTE: this field may contain NULL values; see notes below.
line
: the line (of the containing manifest file) at which the resource definition
can be found. NOTE: this field may contain NULL values; see notes below.
containing-class
: the Puppet class where this resource is declared. NOTE: this field may
contain NULL values; see notes below.
latest-report?
: whether the event occurred in the most recent Puppet run (per-node). NOTE: the
value of this field is always boolean (true or false without quotes), and it
is not supported by the regex match operator.
In the case of a skipped resource event, some of the fields of an event may
not have values. We handle this case in a slightly special way when these
fields are used in equality (=) or inequality (!=) queries; specifically,
an equality query will always return false for an event with no value for
the field, and an inequality query will always return true.
The response is a JSON array of events that matched the input parameters. The events are sorted by their timestamps, in descending order:
[
{
"certname": "foo.localdomain",
"old-value": "absent",
"property": "ensure",
"timestamp": "2012-10-30T19:01:05.000Z",
"resource-type": "File",
"resource-title": "/tmp/reportingfoo",
"new-value": "file",
"message": "defined content as '{md5}49f68a5c8493ec2c0bf489821c21fc3b'",
"report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
"status": "success",
"file": "/home/user/path/to/manifest.pp",
"line": 6,
"containment-path": [ "Stage[main]", "Foo", "File[/tmp/reportingfoo]" ],
"containing-class": "Foo",
"run-start-time": "2012-10-30T19:00:00.000Z",
"run-end-time": "2012-10-30T19:05:00.000Z",
"report-receive-time": "2012-10-30T19:06:00.000Z"
},
{
"certname": "foo.localdomain",
"old-value": "absent",
"property": "message",
"timestamp": "2012-10-30T19:01:05.000Z",
"resource-type": "Notify",
"resource-title": "notify, yo",
"new-value": "notify, yo",
"message": "defined 'message' as 'notify, yo'",
"report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
"status": "success",
"file": "/home/user/path/to/manifest.pp",
"line": 10,
"containment-path": [ "Stage[main]", "", "Node[default]", "Notify[notify, yo]" ],
"containing-class": null,
"run-start-time": "2012-10-30T19:00:00.000Z",
"run-end-time": "2012-10-30T19:05:00.000Z",
"report-receive-time": "2012-10-30T19:06:00.000Z"
}
]
This query endpoint supports paged results via the common PuppetDB paging query parameters. For more information, please see the documentation on paging.
You can use curl to query information about events like so:
curl -G 'http://localhost:8080/v3/events' --data-urlencode 'query=["=", "report", "38ff2aef3ffb7800fe85b322280ade2b867c8d27"]' --data-urlencode 'limit=1000'