Experimental Endpoint: The aggregate-event-counts endpoint is designated as experimental. It may be altered or removed in a future release.

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.

GET /v3/aggregate-event-counts

This will return aggregated count information about all of the resource events matching the given query. This endpoint is built entirely on the event-counts endpoint and will aggregate those results into a single map.

URL Parameters

This endpoint builds on top of the event-counts endpoint, and it uses all of the same URL parameters. The supported parameters are re-listed below for reference.

  • query: Required. A JSON array of query predicates in prefix form (["<OPERATOR>", "<FIELD>", "<VALUE>"]). This query is forwarded to the events endpoint - see there for additional documentation. For general info about queries, see the page on query structure.

  • summarize-by: Required. A string specifying which type of object you’d like count. Supported values are resource, containing-class, and certname.

  • count-by: Optional. A string specifying what type of object is counted when building up the counts of successes, failures, noops, and skips. Supported values are resource (default) and certname.

  • counts-filter: Optional. A JSON array of query predicates in the usual prefix form. This query is applied to the final event-counts output, but before the results are aggregated. Supported operators are =, >, <, >=, and <=. Supported fields are failures, successes, noops, and skips.

  • distinct-resources: Optional. (EXPERIMENTAL: it is possible that the behavior of this parameter may change in future releases.) This parameter is passed along to the event query - see there for additional documentation.

Query Operators

This endpoint builds on top of the event-counts and events endpoints, and supports all of the same operators.

Query Fields

This endpoint builds on top of the event-counts and events endpoints, and supports all of the same fields.

Response Format

The response is a single JSON map containing aggregated event-count information and a total for how many event-count results were aggregated.

{
  "successes": 2,
  "failures": 0,
  "noops": 0,
  "skips": 1,
  "total": 3
}

Examples

You can use curl to query information about aggregated resource event counts like so:

curl -G 'http://localhost:8080/v3/aggregate-event-counts' \
        --data-urlencode 'query=["=", "certname", "foo.local"]' \
        --data-urlencode 'summarize-by=containing-class'

No Paging

This endpoint always returns a single result, so paging is not necessary.

Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.