PuppetDB 2.2 » API » v3 » Querying Event Counts

Included in Puppet Enterprise 3.7. A newer version is available; see the version menu above for details.

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/event-counts

This will return count information about all of the resource events matching the given query. For a given object type (resource, containing-class, or node), you can retrieve counts of the number of events on objects of that type that had a status of success, failure, noop, or skip.

See the events endpoint for additional documentation as this endpoint builds heavily on it.

URL Parameters

  • 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 to see counts for. 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. 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 events endpoint, and supports all of the same operators.

Query Fields

This endpoint builds on top of the events endpoint, and supports all of the same fields.

Response Format

The response is a JSON array of maps. Each map contains the counts of events that matched the input parameters. The events are counted based on their statuses: failures, successes, noops, skips.

The maps also contain additional data about which object the events occurred on. The subject-type is the value that was used to summarize by (and therefore should match the input value to summarize-by). The subject map contains specific data about the object the event occurred on, and will vary based on the value specified for summarize-by.

When summarizing by certname, the subject will contain a title key:

[
  {
    "subject-type": "certname",
    "subject": { "title": "foo.local" },
    "failures": 0,
    "successes": 2,
    "noops": 0,
    "skips": 1
  },
  {
    "subject-type": "certname",
    "subject": { "title": "bar.local" },
    "failures": 1,
    "successes": 0,
    "noops": 0,
    "skips": 1
  }
]

When summarizing by resource, the subject will contain a type and title key:

[
  {
    "subject-type": "resource",
    "subject": { "type": "Notify", "title": "Foo happened" },
    "failures": 0,
    "successes": 1,
    "noops": 0,
    "skips": 0
  },
  {
    "subject-type": "resource",
    "subject": { "type": "Notify", "title": "Bar happened" },
    "failures": 0,
    "successes": 0,
    "noops": 0,
    "skips": 1
  }
]

When summarizing by containing-class, the subject will contain a title key:

[
  {
    "subject-type": "containing-class",
    "subject": { "title": "Foo::Class" },
    "failures": 1,
    "successes": 2,
    "noops": 0,
    "skips": 1
  },
  {
    "subject-type": "containing-class",
    "subject": { "title": null },
    "failures": 0,
    "successes": 0,
    "noops": 2,
    "skips": 0
  }
]

Examples

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

curl -G 'http://localhost:8080/v3/event-counts' \
        --data-urlencode 'query=["=", "certname", "foo.local"]' \
        --data-urlencode 'summarize-by=resource' \
        --data-urlencode 'count-by=certname' \
        --data-urlencode 'counts-filter=[">", "failures", 0]'

Paging

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

↑ Back to top