Class: PEClient::Resource::PuppetDB::QueryV4::Reports

Inherits:
Base
  • Object
show all
Defined in:
lib/pe_client/resources/puppet_db/query.v4/reports.rb

Overview

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

  • Data about the entire run

  • Metadata about the report

  • Many events, describing what happened during the run

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

See Also:

Constant Summary collapse

BASE_PATH =

The base path for PuppetDB Query v4 Reports endpoints.

"#{QueryV4::BASE_PATH}/reports".freeze

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from PEClient::Resource::Base

Instance Method Details

#events(hash:, query: nil, **kwargs) ⇒ Hash+

Returns all events for a particular report, designated by its unique hash.

Most of PuppetDB’s query endpoints support a general set of HTTP URL parameters that can be used for paging results. PuppetDB also supports paging via query operators, as described in the AST documentation.

Parameters:

  • hash (String) —

    The unique hash of the report.

  • query (Array) (defaults to: nil) —

    An Array of query predicates, in prefix notation ([“<OPERATOR>”, “<FIELD>”, “<VALUE>”]).

  • kwargs (Hash) —

    Keyword arguments for paging

Options Hash (**kwargs):

  • :order_by (String) —

    This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in ascending or descending order. The value must be an Array of Hashes. Each map represents a field to sort by, and the order in which the maps are specified in the array determines the sort order. Each map must contain the key field, whose value must be the name of a field that can be returned by the specified query. Each map may also optionally contain the key order, whose value may either be “asc” or “desc”, depending on whether you wish the field to be sorted in ascending or descending order. The default value for this key, if not specified, is “asc”. Note that the legal values for field vary depending on which endpoint you are querying. For lists of legal fields, please refer to the documentation for the specific query endpoints.

  • :limit (Integer) —

    This parameter can be used to restrict the result set to a maximum number of results.

  • :include_total (Boolean) —

    This parameter lets you request a count of how many records would have been returned, had the query not been limited using the limit parameter. This is useful if you want your application to show how far the user has navigated (“page 3 of 15”). The value should be a Boolean, and defaults to false. If true, the HTTP response will contain a header X-Records, whose value is an integer indicating the total number of results available. Note: Setting this flag to true can decrease performance.

  • :offset (Integer) —

    This parameter can be used to tell PuppetDB to return results beginning at the specified offset. For example, if you’d like to page through query results with a page size of 10, your first query would specify ‘limit: 10` and `offset: 0`, your second query would specify `limit: 10` and `offset: 10`, and so on. Note that the order in which results are returned by PuppetDB is not guaranteed to be consistent unless you specify a value for :order_by, so this parameter should generally be used in conjunction with :order_by.

Returns:

  • (Hash)
  • (Array<Hash>)

See Also:



59
60
61
62
 
# File 'lib/pe_client/resources/puppet_db/query.v4/reports.rb', line 59

def events(hash:, query: nil, **kwargs)
  @client.get "#{BASE_PATH}/#{hash}/events",
    params: {query: query&.to_json}.merge!(QueryV4.query_paging(**kwargs)).compact
end

#get(query: nil, **kwargs) ⇒ Hash+

If :query is absent, PuppetDB will return all reports.

Most of PuppetDB’s query endpoints support a general set of HTTP URL parameters that can be used for paging results. PuppetDB also supports paging via query operators, as described in the AST documentation.

Parameters:

  • query (Array) (defaults to: nil) —

    An Array of query predicates, in prefix notation ([“<OPERATOR>”, “<FIELD>”, “<VALUE>”]).

  • kwargs (Hash) —

    Keyword arguments for paging

Options Hash (**kwargs):

  • :order_by (String) —

    This parameter can be used to ask PuppetDB to return results sorted by one or more fields, in ascending or descending order. The value must be an Array of Hashes. Each map represents a field to sort by, and the order in which the maps are specified in the array determines the sort order. Each map must contain the key field, whose value must be the name of a field that can be returned by the specified query. Each map may also optionally contain the key order, whose value may either be “asc” or “desc”, depending on whether you wish the field to be sorted in ascending or descending order. The default value for this key, if not specified, is “asc”. Note that the legal values for field vary depending on which endpoint you are querying. For lists of legal fields, please refer to the documentation for the specific query endpoints.

  • :limit (Integer) —

    This parameter can be used to restrict the result set to a maximum number of results.

  • :include_total (Boolean) —

    This parameter lets you request a count of how many records would have been returned, had the query not been limited using the limit parameter. This is useful if you want your application to show how far the user has navigated (“page 3 of 15”). The value should be a Boolean, and defaults to false. If true, the HTTP response will contain a header X-Records, whose value is an integer indicating the total number of results available. Note: Setting this flag to true can decrease performance.

  • :offset (Integer) —

    This parameter can be used to tell PuppetDB to return results beginning at the specified offset. For example, if you’d like to page through query results with a page size of 10, your first query would specify ‘limit: 10` and `offset: 0`, your second query would specify `limit: 10` and `offset: 10`, and so on. Note that the order in which results are returned by PuppetDB is not guaranteed to be consistent unless you specify a value for :order_by, so this parameter should generally be used in conjunction with :order_by.

Returns:

  • (Hash)
  • (Array<Hash>)

See Also:



46
47
48
 
# File 'lib/pe_client/resources/puppet_db/query.v4/reports.rb', line 46

def get(query: nil, **kwargs)
  @client.get(BASE_PATH, params: {query: query&.to_json}.merge!(QueryV4.query_paging(**kwargs)).compact)
end

#logs(hash:) ⇒ Array<Hash>

Returns all logs for a particular report, designated by its unique hash. This endpoint does not currently support querying or paging.

Parameters:

  • hash (String) —

    The unique hash of the report.

Returns:

  • (Array<Hash>)

See Also:



84
85
86
 
# File 'lib/pe_client/resources/puppet_db/query.v4/reports.rb', line 84

def logs(hash:)
  @client.get "#{BASE_PATH}/#{hash}/logs"
end

#metrics(hash:) ⇒ Array<Hash>

Returns all metrics for a particular report, designated by its unique hash. This endpoint does not currently support querying or paging.

Parameters:

  • hash (String) —

    The unique hash of the report.

Returns:

  • (Array<Hash>)

See Also:



72
73
74
 
# File 'lib/pe_client/resources/puppet_db/query.v4/reports.rb', line 72

def metrics(hash:)
  @client.get "#{BASE_PATH}/#{hash}/metrics"
end