<commit_before>---
title: "PuppetDB 1.5 » Release Notes"
layout: default
canonical: "/puppetdb/latest/release_notes.html"
---

1.5.0
-----

PuppetDB 1.5.0 is a new feature release.  (For detailed information about
any of the API changes, please see the official documentation for PuppetDB 1.5.)

Notable features and improvements:

* (#21520) Configuration for soft failure when PuppetDB is unavailable

  This feature adds a new option 'soft_write_failure' to the puppetdb
  configuration.  If enabled the terminus behavior is changed so that if a
  command or write fails, instead of throwing an exception and causing the agent
  to stop it will simply log an error to the puppet master log.

* New v3 query API

  New `/v3` URLs are available for all query endpoints.  The `reports` and
  `events` endpoints, which were previously considered `experimental`, have
  been moved into `/v3`.  Most of the other endpoints are 100% backwards-compatible
  with `/v2`, but now offer additional functionality.  There are few minor
  backwards-incompatible changes, detailed in the comments about individual
  endpoints below.

* Query paging

  This feature adds a set of new HTTP query parameters that can be used with most
  of the query endpoints (`fact_names`, `facts`, `resources`, `nodes`, `events`,
  `reports`, `event-counts`) to allow paging through large result sets over
  multiple queries.  The available HTTP query parameters are:

     * `limit`: an integer specifying the maximum number of results to
        return.
     * `order-by`: a list of fields to sort by, in ascending or descending order.
        The legal set of fields varies by endpoint; see the documentation for
        individual endpoints for more info.
     * `offset`: an integer specifying the first result in the result set that
        should be returned.  This can be used in combination with `limit`
        and `order-by` to page through a result set over multiple queries.
     * `include-total`: a boolean flag which, if set, will cause the HTTP response
       to contain an `X-Records` header indicating the total number of results that are
       available that match the query.  (Mainly useful in combination with `limit`.)

* New features available on `events` endpoint

    * The `events` data now contains `file` and `line` fields.  These indicate
      the location in the manifests where the resource was declared.  They can
      be used as input to an `events` query.
    * Add new `configuration-version` field, which contains the value that Puppet
      supplied during the agent run.
    * New `containing-class` field: if the resource is declared inside of a
      Puppet class, this field will contain the name of that class.
    * New `containment-path` field: this field is an array showing the full
      path to the resource from the root of the catalog (contains an ordered
      list of names of the classes/types that the resource is contained within).
    * New queryable timestamp fields:
        * `run-start-time`: the time (on the agent node) that the run began
        * `run-end-time`: the time (on the agent node) that the run completed
        * `report-receive-time`: the time (on the puppetdb node)
    * Restrict results to only include events that occurred in the latest report
      for a given node: `["=", "latest-report?", true]`

* New `event-counts` endpoint

    `v3` of the query API contains a new `event-counts` endpoint, which can be
    used to retrieve count data for an event query.  The basic input to the
    endpoint is an event query, just as you'd provide to the `events` endpoint,
    but rather than returning the actual events, this endpoint returns counts
    of `successes`, `failures`, `skips`, and `noops` for the events that match
    the query.  The counts may be aggregated on a per-resource, per-class,
    or per-node basis.

* New `aggregate-event-counts` endpoint

  This endpoint is similar to the `event-counts` endpoint, but rather than
  aggregating the counts on a per-node, per-resource, or per-class basis,
  it returns aggregate counts across your entire population.

* New `server-time` endpoint

  This endpoint simply returns a timestamp indicating the current time on
  the PuppetDB server.  This can be used as input to time-based queries
  against timestamp fields that are populated by PuppetDB.

* Minor changes to `resources` endpoint for `v3`:

  The `sourcefile` and `sourceline` fields have been renamed to `file` and `line`,
  for consistency with other parts of the API.

* Minor changes relating to reports storage and query

  * `store report` command has been bumped up to version `2`.
  * Report data now includes a new `transaction-uuid` field; this is generated
    by Puppet (as of Puppet 3.3) and can be used to definitively correlate a report
    with the catalog that was used for the run.  This field is queryable on the
    `reports` endpoint.<commit_msg>fixes based on pull request feedback<commit_after>---
title: "PuppetDB 1.5 » Release Notes"
layout: default
canonical: "/puppetdb/latest/release_notes.html"
---

1.5.0
-----

PuppetDB 1.5.0 is a new feature release.  (For detailed information about
any of the API changes, please see the official documentation for PuppetDB 1.5.)

Notable features and improvements:

* (#21520) Configuration for soft failure when PuppetDB is unavailable

  This feature adds a new option 'soft_write_failure' to the puppetdb
  configuration.  If enabled the terminus behavior is changed so that if a
  command or write fails, instead of throwing an exception and causing the agent
  to stop it will simply log an error to the puppet master log.

* New v3 query API

  New `/v3` URLs are available for all query endpoints.  The `reports` and
  `events` endpoints, which were previously considered `experimental`, have
  been moved into `/v3`.  Most of the other endpoints are 100% backwards-compatible
  with `/v2`, but now offer additional functionality.  There are few minor
  backwards-incompatible changes, detailed in the comments about individual
  endpoints below.

* Query paging

  This feature adds a set of new HTTP query parameters that can be used with most
  of the query endpoints (`fact_names`, `facts`, `resources`, `nodes`, `events`,
  `reports`, `event-counts`) to allow paging through large result sets over
  multiple queries.  The available HTTP query parameters are:

     * `limit`: an integer specifying the maximum number of results to
        return.
     * `order-by`: a list of fields to sort by, in ascending or descending order.
        The legal set of fields varies by endpoint; see the documentation for
        individual endpoints for more info.
     * `offset`: an integer specifying the first result in the result set that
        should be returned.  This can be used in combination with `limit`
        and `order-by` to page through a result set over multiple queries.
     * `include-total`: a boolean flag which, if set, will cause the HTTP response
       to contain an `X-Records` header indicating the total number of results that are
       available that match the query.  (Mainly useful in combination with `limit`.)

* New features available on `events` endpoint

    * The `events` data now contains `file` and `line` fields.  These indicate
      the location in the manifests where the resource was declared.  They can
      be used as input to an `events` query.
    * Add new `configuration-version` field, which contains the value that Puppet
      supplied during the agent run.
    * New `containing-class` field: if the resource is declared inside of a
      Puppet class, this field will contain the name of that class.
    * New `containment-path` field: this field is an array showing the full
      path to the resource from the root of the catalog (contains an ordered
      list of names of the classes/types that the resource is contained within).
    * New queryable timestamp fields:
        * `run-start-time`: the time (on the agent node) that the run began
        * `run-end-time`: the time (on the agent node) that the run completed
        * `report-receive-time`: the time (on the puppetdb node) that the report was received by PuppetDB
    * Restrict results to only include events that occurred in the latest report
      for a given node: `["=", "latest-report?", true]`

* New `event-counts` endpoint

    `v3` of the query API contains a new `event-counts` endpoint, which can be
    used to retrieve count data for an event query.  The basic input to the
    endpoint is an event query, just as you'd provide to the `events` endpoint,
    but rather than returning the actual events, this endpoint returns counts
    of `successes`, `failures`, `skips`, and `noops` for the events that match
    the query.  The counts may be aggregated on a per-resource, per-class,
    or per-node basis.

* New `aggregate-event-counts` endpoint

  This endpoint is similar to the `event-counts` endpoint, but rather than
  aggregating the counts on a per-node, per-resource, or per-class basis,
  it returns aggregate counts across your entire population.

* New `server-time` endpoint

  This endpoint simply returns a timestamp indicating the current time on
  the PuppetDB server.  This can be used as input to time-based queries
  against timestamp fields that are populated by PuppetDB.

* Minor changes to `resources` endpoint for `v3`

  The `sourcefile` and `sourceline` fields have been renamed to `file` and `line`,
  for consistency with other parts of the API.

* Minor changes relating to reports storage and query

  * `store report` command has been bumped up to version `2`.
  * Report data now includes a new `transaction-uuid` field; this is generated
    by Puppet (as of Puppet 3.3) and can be used to definitively correlate a report
    with the catalog that was used for the run.  This field is queryable on the
    `reports` endpoint.
{'fraction_non_alphanumeric': 0.06260677318862426, 'fraction_numerical': 0.005426590292432921, 'mean_word_length': 3.4687920969914683, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '231608', 'n_tokens_mistral': 2655, 'n_tokens_neox': 2537, 'n_words': 1419}