PuppetDB 1.5 » API » v3 » Querying Event Counts

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

Routes

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.

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.

  • 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.

Operators

This endpoint builds on top of the events endpoint and therefore supports all of the same operators.

Fields

This endpoint builds on top of the events endpoint and therefore 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
  }
]

Paging

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

Example

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]'

↑ Back to top