Reports endpoint

• query: optional. A JSON array of query predicates, in prefix notation (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general info about queries, see our guide to query structure.

If the query parameter is absent, PuppetDB will return all reports.

See the AST query language page.

The following fields are allowed as filter criteria and are returned in all responses.

• certname (string): the name of the node that the report was received from.

• hash (string): the ID of the report; these IDs can be acquired via event queries (see the /events endpoint).

• environment (string): the environment assigned to the node that submitted the report.

• status (string): the status associated to report's node. Possible values for this field come from Puppet's report status, which can be found here.

• job_id (string): the job id associated with the report (not present if the run wasn't part of a job)

• noop (Boolean): a flag indicating whether the report was produced by a noop run.

• noop_pending (Boolean): a flag indicating whether the report contains noop events (these can arise from use of --noop or from resources with the noop parameter set to true). This field will only be present when the agent originating the report is version 4.6.0 or higher.

• puppet_version (string): the version of Puppet that generated the report.

• report_format (number): the version number of the report format that Puppet used to generate the original report data.

• configuration_version (string): an identifier string that Puppet uses to match a specific catalog for a node to a specific Puppet run.

• start_time (timestamp): the time on the agent at which the Puppet run began. Timestamps are always ISO-8601 compatible date/time strings.

• end_time (timestamp): the time on the agent at which the Puppet run ended. Timestamps are always ISO-8601 compatible date/time strings.

• producer_timestamp (timestamp): the time of catalog submission from the Puppet Server to PuppetDB, according to the clock on the Puppet Server. Timestamps are always ISO-8601 compatible date/time strings.

• receive_time (timestamp): the time at which PuppetDB received the report. Timestamps are always ISO-8601 compatible date/time strings.

• producer (string): the certname of the Puppet Server that sent the report to PuppetDB.

• transaction_uuid (string): a string used to identify a Puppet run.

• catalog_uuid (string): a string used to tie a catalog to a report to the catalog used from that Puppet run.

• code_id (string): a string used to tie a catalog to the Puppet code which generated the catalog.

• cached_catalog_status (string): a string used to identify whether the Puppet run used a cached catalogs and whether or not the cached catalog was used due to an error or not. Possible values include explicitly_requested, on_failure, not_used or null.

• type: (string): either "agent", "plan", or "any" to restrict the results to reports submitteed from that source. If no type filter is provided, it will only return reports from puppet agent runs.

• corrective_change: (Boolean): a flag indicating whether any of the report's events remediated configuration drift. This field is only populated in PE.

• latest_report? (Boolean): return only reports associated with the most recent Puppet run for each node. Note: this field does not appear in the response.

The following list contains related entities that can be used to constrain the result set using implicit subqueries. For more information, consult the documentation for subqueries.

• environments: environment from where a report was received.

• events: events received in a report.

• producers: the Puppet Server that sent the report to PuppetDB.

The response is a JSON array of report summaries for all event reports that matched the input parameters. The array is unsorted. The top-level response is of the form:

{
  "hash": <sha1 of stored report command payload>,
  "puppet_version": <report puppet version>,
  "receive_time": <time of report reception by PDB>,
  "report_format": <report wireformat version>,
  "start_time": <start of run timestamp>,
  "end_time": <end of run timestamp>,
  "producer_timestamp": <time of transmission by Puppet Server>,
  "producer": <Puppet Server certname>,
  "transaction_uuid": <string to identify puppet run>,
  "status": <status of node after report's associated puppet run>,
  "noop": <boolean flag indicating noop run>,
  "noop_pending": <boolean flag indicating presence of noop events>
  "environment": <report environment>,
  "configuration_version": <catalog identifier>,
  "certname": <node name>,
  "code_id": <sha1 of Puppet code>,
  "catalog_uuid": <string to identify the corresponding catalog>,
  "cached_catalog_status": <reason a cached catalog was used>,
  "resource_events": <expanded resource events>,
  "resources" : <expanded resources (PE only)>
  "metrics" : <expanded metrics>,
  "logs" : <expanded logs>
}

Note: The resources field is only offered in Puppet Enterprise (PE)

The response format in PE contains an additional field, resources, which contains all the resource statuses for the Puppet run corresponding to the report, both changed and unchanged resources.

Below, in old_value and new_value, any rich data values will appear as readable strings.

The <expanded resource events> object is of the following form:

{
  "href": <url>,
  "data": [ {
    "status": <status of event (`success`, `failure`, `noop`, or `skipped`)>,
    "timestamp": <timestamp (from agent) at which event occurred>,
    "resource_type": <type of resource event occurred on>,
    "resource_title": <title of resource event occurred on>,
    "property": <property/parameter of resource on which event occurred>,
    "name": <name of the resource on which event occurred>,
    "new_value": <new value for resource property>,
    "old_value": <old value of resource property>,
    "message": <description of what happened during event>,
    "file": <manifest file containing resource definition>,
    "line": <line in manifest file on which resource is defined>,
    "containment_path": <containment heirarchy of resource within catalog>
  } ... ]
}

The <expanded resources> object is of the following form:

{
  "href": <url>,
  "data": [ {
    "timestamp": <timestamp (from agent) at which event occurred>,
    "resource_type": <type of resource event occurred on>,
    "resource_title": <title of resource event occurred on>,
    "containment_path": <containment heirarchy of resource within catalog>
    "skipped" : <boolean for whether or not the resource was skipped>,
    "events" : [<event> ...]
  } ... ]
}

Where an <event> object is of the form:

{
        "timestamp": <timestamp (from agent) at which event occurred>,
        "property": <property/parameter of resource on which event occurred>,
        "name": <name of resource on which event occurred>,
        "new_value": <new value for resource property>,
        "old_value": <old value of resource property>,
        "status": <status of event (`success`, `failure`, or `noop`)>,
        "message": <description of what happened during event>
}

Note: On resources versus resource_events

Unchanged resources are accessed through the resources field. The resource_events field does not contain this information.

The <expanded metrics> object is as follows:

{
  "href": <url>,
  "data": [ {
    "category" : <category of metric ("resources", "time", "changes", or "events")>,
    "name" : <name of the metric>,
    "value" : <value of the metric (double precision)>
  } ... ]
}

The <expanded logs> object returns a single log line per data entry as follows:

{
  "href": <url>,
  "data": [ {
    "file" : <file of resource declaration>,
    "line" : <line of resource declaration>,
    "level" : <log level>,
    "message" : <log message>,
    "source" : <log source>,
    "tags" : [<resource tag>],
    "time" : <log line timestamp>
 } ... ]

}

File and line may each be null if the log does not concern a resource.

Note: Fields that allow NULL values

In the resource_event schema above, containment_path, new_value, old_value, property, file, line, status, and message may all be null.

Note: On querying resource events, metrics, and logs

The reports endpoint does not support querying on the value of resource_events, logs, or metrics. For resource_events, the same information can be accessed by querying the events endpoint for events with field report equal to a given report's hash. Making metrics and logs queryable may be the target of future work.

You can use curl to query information about reports:

Query for all reports:

curl -G http://localhost:8080/pdb/query/v4/reports

[ {
  "receive_time" : "2015-02-19T16:23:11.034Z",
  "hash" : "32c821673e647b0650717db467abc51d9949fd9a",
  "transaction_uuid" : "9a7070e9-840f-446d-b756-6f19bf2e2efc",
  "puppet_version" : "3.7.4",
  "noop" : false,
  "noop_pending": true,
  "report_format" : 4,
  "start_time" : "2015-02-19T16:23:09.810Z",
  "end_time" : "2015-02-19T16:23:10.287Z",
  "producer_timestamp" : "2015-02-19T16:23:11.000Z",
  "producer" : "server.localdomain",
  "resource_events" : {
    "href": "/pdb/query/v4/reports/32c821673e647b0650717db467abc51d9949fd9a/events",
    "data": [ {
      "new_value" : "hi world",
      "property" : "message",
      "name": "define message",
      "file" : "/home/wyatt/.puppet/manifests/site.pp",
      "old_value" : "absent",
      "line" : 7,
      "resource_type" : "Notify",
      "status" : "success",
      "resource_title" : "hiloo",
      "timestamp" : "2015-02-19T16:23:10.768Z",
      "containment_path" : [ "Stage[main]", "Main", "Notify[hiloo]" ],
      "message" : "defined 'message' as 'hi world'"
    }, {
      "new_value" : "hi world",
      "property" : "message",
      "name": "define message",
      "file" : "/home/wyatt/.puppet/manifests/site.pp",
      "old_value" : "absent",
      "line" : 3,
      "resource_type" : "Notify",
      "status" : "success",
      "resource_title" : "hi",
      "timestamp" : "2015-02-19T16:23:10.767Z",
      "containment_path" : [ "Stage[main]", "Main", "Notify[hi]" ],
      "message" : "defined 'message' as 'hi world'"
    } ]
  },
  "status" : "changed",
  "configuration_version" : "1424362990",
  "environment" : "production",
  "certname" : "desktop.localdomain",
  "metrics" : {
    "href": "/pdb/query/v4/reports/32c821673e647b0650717db467abc51d9949fd9a/metrics",
    "data": [ {
      "category" : "resources",
      "name" : "changed",
      "value" : 2
    }, {
      "category" : "resources",
      "name" : "failed",
      "value" : 0
    },
    ...
    {
      "category" : "events",
      "name" : "success",
      "value" : 2
    }, {
      "category" : "events",
      "name" : "total",
      "value" : 2
    } ]
  },
  "logs" : {
    "href": "/pdb/query/v4/reports/32c821673e647b0650717db467abc51d9949fd9a/logs",
    "data": [ {
      "file" : null,
      "line" : null,
      "level" : "info",
      "message" : "Caching catalog for mbp.local",
      "source" : "//mbp.local/Puppet",
      "tags" : [ "info" ],
      "time" : "2015-02-26T16:27:48.416642000-08:00"
    },
    ...
    {
      "file" : null,
      "line" : null,
      "level" : "notice",
      "message" : "Finished catalog run in 0.01 seconds",
      "source" : "//mbp.local/Puppet",
      "tags" : [ "notice" ],
      "time" : "2015-02-26T16:27:48.483317000-08:00"
    } ]
  }
} ]

You can retrieve the resources field as part of the data from the reports endpoint or using the child data endpoint.

For example, the following query finds for all resources (changed and unchanged) for a report with hash 32c821673e647b0650717db467abc51d9949fd9a:

Note: The following is for PE only curl -G http://localhost:8080/pdb/query/v4/reports/32c821673e647b0650717db467abc51d9949fd9a/resources

[
   {
      "file":"/home/wyatt/.puppet/manifests/site.pp",
      "line":7,
      "resource_title":"hiloo",
      "timestamp":"2015-02-19T16:23:10.768Z",
      "containment_path":[
         "Stage[main]",
         "Main",
         "Notify[hiloo]"
      ],
      "resource_type":"Notify",
      "message":"defined 'message' as 'hi world'",
      "skipped":false,
      "events":[
         {
            "property":"message",
            "name": null,
            "old_value":"absent",
            "new_value":"hi world",
            "status":"success",
            "timestamp":"2015-02-19T16:23:10.768Z"
         }
      ]
   }
]

Get counts of reports grouped by status:

curl -X GET http://localhost:8080/pdb/query/v4/reports \
  -d 'query=["extract",[["function","count"], "status"],
                        ["~","certname",""],
                        ["group_by", "status"]]'

[ {
  "status" : "failed",
  "count" : 10
}, {
  "status" : "changed",
  "count" : 72
}, {
  "status" : "unchanged",
  "count" : 20
} ]

Get counts of reports grouped by status and day of the week received:

curl -X GET http://localhost:8080/pdb/query/v4/reports -d
'query=["extract",["status", ["function", "count"], ["function", "to_string","receive_time", "FMDay"]],["group_by","status",["function","to_string","receive_time", "FMDay"]]]'

[ {
  "status" : "failed",
  "count" : 10,
  "to_string" : "Thursday"
}, {
  "status" : "changed",
   "count" : 60,
   "to_string" : "Thursday"
}, {
  "status" : "unchanged",
   "count" : 30,
   "to_string" : "Thursday"
} ]

This route is an extension of the events endpoint. It uses the exact same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.