Skip to content

Latest commit

 

History

History
210 lines (153 loc) · 9.53 KB

events.markdown

File metadata and controls

210 lines (153 loc) · 9.53 KB
Raw
title layout canonical
PuppetDB 3.1 » API » v4 » Querying Events
default
/puppetdb/latest/api/query/v4/events.html

Puppet agent nodes submit reports after their runs, and the puppet master forwards these to PuppetDB. Each report includes:

  • Some data about the entire run
  • Some metadata about the report
  • Many events, describing what happened during the run

Once this information is stored in PuppetDB, it can be queried in various ways.

  • You can query data about the run and report metadata by making an HTTP request to the /reports endpoint.
  • You can query data about individual events by making an HTTP request to the /events endpoint.
  • You can query summaries of event data by making an HTTP request to the /event-counts or aggregate-event-counts endpoints.

/pdb/query/v4/events

This will return all resource events matching the given query. (Resource events are generated from Puppet reports.)

URL Parameters

  • query: Optional. A JSON array of query predicates, in prefix form (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general info about queries, see the page on query structure. If query is omitted all events are returned.

  • distinct_resources: Optional. Boolean. (I.e. distinct_resources=true.) (EXPERIMENTAL: it is possible that the behavior of this parameter may change in future releases.) If specified, the result set will only return the most recent event for a given resource on a given node.

    For example: if the resource File[/tmp/foo] was failing on some node but has since been fixed and is now succeeding, then a "normal" event query might return both the success and failure events. A query with distinct_resources=true would only return the success event, since it's the most recent event for that resource.

    Since a distinct_resources query can be expensive, it requires a limited window of time to examine. Use the distinct_start_time and distinct_end_time parameters to define this interval. Issuing a distinct_resources query without specifying both of these parameters will cause an error.

  • distinct_start_time: Used with distinct_resources. The start of the window of time to examine, as an ISO-8601 compatible date/time string.

  • distinct_end_time: Used with distinct_resources. The end of the window of time to examine, as an ISO-8601 compatible date/time string.

Query Operators

See the Operators page for the full list of available operators. Note that inequality operators (<, >, <=, >=) are only supported against the timestamp field.

Query Fields

Note on fields that allow NULL values

In the case of a skipped resource event, some of the fields of an event may not have values. Queries using equality (=) and inequality (!=) will not return null values. See the null? operator, if you want to query for nodes that do not have a value.

  • certname (string): the name of the node that the event occurred on.

  • report (string): 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 (string): the status of the event; legal values are success, failure, noop, and skipped.

  • timestamp (timestamp): the timestamp (from the puppet agent) at which the event occurred. Timestamps are always ISO-8601 compatible date/time strings.

  • run_start_time (timestamp): the timestamp (from the puppet agent) at which the puppet run began. Timestamps are always ISO-8601 compatible date/time strings.

  • run_end_time (timestamp): the timestamp (from the puppet agent) at which the puppet run finished. Timestamps are always ISO-8601 compatible date/time strings.

  • report_receive_time (timestamp): the timestamp (from the PuppetDB server) at which the puppet report was received. Timestamps are always ISO-8601 compatible date/time strings.

  • resource_type (string, with first letter always capitalized): the type of resource that the event occurred on; e.g., File, Package, etc.

  • resource_title (string): the title of the resource that the event occurred on.

  • property (string or null): 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 above.

  • new_value (string or null): the new value that Puppet was attempting to set for the specified resource property. NOTE: this field may contain NULL values; see notes above.

  • old_value (string or null): the previous value of the resource property, which Puppet was attempting to change. NOTE: this field may contain NULL values; see notes above.

  • message (string or null): a description (supplied by the resource provider) of what happened during the event. NOTE: this field may contain NULL values; see notes above.

  • file (string or null): the manifest file in which the resource definition is located. NOTE: this field may contain NULL values; see notes above.

  • line (number or null): the line (of the containing manifest file) at which the resource definition can be found. NOTE: this field may contain NULL values; see notes above.

  • containing_class (string or null): the Puppet class where this resource is declared. NOTE: this field may contain NULL values; see notes above.

  • latest_report? (boolean): 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.

  • environment (string): the environment associated with the reporting node.

  • configuration_version (string): an identifier string that puppet uses to match a specific catalog for a node to a specific puppet run.

  • containment_path (array of strings, where each string is a containment path element): the containment path associated with the event, as an ordered array that ends with the most specific containing element.

Response Format

The response is a JSON array of events that matched the input parameters. The array is unordered.

[
  {
    "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"
  }
]

Examples

You can use curl to query information about events like so:

curl -G 'http://localhost:8080/pdb/query/v4/events' \
  --data-urlencode 'query=["=", "report", "38ff2aef3ffb7800fe85b322280ade2b867c8d27"]' \
  --data-urlencode 'limit=1000'

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 with name matching '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"]]

To retrieve event status counts for each active node:

curl -X GET http://localhost:8080/pdb/query/v4/events --data-urlencode \
'query=["extract", [["function", "count"], "status","certname"],
                   ["=", ["node","active"], true],
                   ["group_by","status","certname"]]'

Paging

This endpoint supports paged results via the common PuppetDB paging URL parameters. For more information, please see the documentation on paging.