Value report

Value analytics give you insight into time and money saved by Puppet Enterprise (PE) automation. You can access this information on the Value report page in the console or through the value API.

The information in the value report and the value API provide details about automated changes PE makes to nodes and estimates time saved by each type of change based on intelligent defaults or values you provide. If you specify an average hourly salary, the report also estimates cost savings from automated changes.

To ensure your value analysis is accurate:
  • Make sure tasks, plans, and Puppet runs are processing normally because value analysis doesn't track failed runs.
  • If you use the value API, query the endpoint regularly to gather data over time.

Value report defaults

Value analytics uses intelligent defaults to estimate time freed by automated changes. These defaults are based on customer research and take into account time to triage, research, and fix issues, as well as context switching. You can also provide your own default values.

When you query the value API, you can specify low, med, or high estimates for time freed parameters, or provide an exact value in minutes based on averages in your organization. In the console Value report, you specify an exact value in minutes. Unless you specify otherwise, both the API and the console use the med values. The baseline intelligent default values are as follows:
Parameter Intelligent default values
minutesFreedPerCorrectiveChange
  • low: 90 minutes
  • med: 180 minutes
  • high: 360 minutes
minutesFreedPerIntentionalChange
  • low: 30 min
  • med: 90 minutes
  • high: 180 minutes
minutesFreedPerTaskRun
  • low: 30 minutes
  • med: 90 minutes
  • high: 180 minutes
minutesFreedPerPlanRun
  • low: 90 minutes
  • med: 180 minutes
  • high: 360 minutes

You can change the low, med, and high times by specifying any of the value_report_* parameters in the PE Console node group in the puppet_enterprise::profile::console class.

GET /api/reports/value

Use the GET /api/reports/value endpoint to retrieve information about time and money freed by Puppet Enterprise (PE) automation.

Request format

You must provide well-formed HTTP(S) requests. By default, the value API uses the standard HTTPS port for console communication, which is port 443. You can omit the port from your requests unless you want to specify a different port.

You must authenticate requests to the value API using your Puppet CA certificate and an RBAC token. The RBAC token must have viewing permissions for the console.

This is an example of a basic, authenticated value API request without any parameters:
curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <RBAC_TOKEN>" \
"https://<HOSTNAME>/api/reports/value"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

You can use these parameters, attached with --data-urlencode, to modify your value API requests:
Parameter Description Default value
averageHourlySalary Numeric value specifying average hourly salary to use to cost savings for automated work. None
startDate A date in yyyy-mm-dd format. Today less nine days (One week plus two days in the past)
endDate A daate in yyyy-mm-dd format.

If you specify today's date, the response contains provisional data.

 today less two days
minutesFreedPerCorrectiveChange low, med, high, or any numeric value in minutes. med
minutesFreedPerIntentionalChange low, med, high, or any numeric value in minutes. med
minutesFreedPerTaskRun low, med, high, or any numeric value in minutes. med
minutesFreedPerPlanRun low, med, high, or any numeric value in minutes. med
The numerical basis for minutesFreed parameters are controlled by Value report defaults.

Response format

The response is a JSON object listing details about time and cost freed. Responses use these keys:
Key Definition
startDate Start date for the reporting period.
endDate End date for the reporting period.
totalCorrectiveChanges Total number of corrective changes made during the reporting period.
minutesFreedByCorrectiveChanges Total number of minutes freed by automated changes that prevent drift during regular Puppet runs. The calculation is based on the average minutes saved per change, as specified by the minutesFreedPerCorrectiveChange query parameter.
totalIntentionalChanges Total number of intentional changes made during the reporting period.
minutesFreedByIntentionalChanges Total number of minutes freed by automated changes based on new values or Puppet code. This calculation is based on the average minutes saved per change, as specified by the minutesFreedPerIntentionalChange query parameter.
totalNodesAffectedByTaskRuns Total number of nodes affected by successful task runs during the reporting period.
minutesFreedByTaskRuns Total number of minutes freed by automated task runs. This calculation is based on the average minutes saved per task run, as specified by the minutesFreedPerTaskRun query parameter.
totalNodesAffectedByPlanRuns Total number of nodes affected by successful plan runs during the reporting period.
minutesFreedByPlanRuns Total number of minutes freed by automated plan runs. This calculation is based on the average minutes saved per plan run, as specified by the minutesFreedPerPlanRun query parameter.
totalMinutesFreed Total number of minutes free by all automated changes.
totalDollarsSaved If the query specified an averageHourlySalary, total cost savings for all automated changes.

Request and response examples

This request generates a report for specified dates using the default time freed values:
curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <RBAC_TOKEN>" \
-G "https://<HOSTNAME>/api/reports/value" \
--data-urlencode 'startDate=2020-07-08' \
--data-urlencode 'endDate=2020-07-15'
The result is:
{
  "startDate": "2020-07-08",
  "endDate": "2020-07-15",
  "totalCorrectiveChanges": 0,
  "minutesFreedByCorrectiveChanges": 0,
  "totalIntentionalChanges": 18,
  "minutesFreedByIntentionalChanges": 1620,
  "totalNodesAffectedByPlanRuns": 0,
  "totalNodesAffectedByTaskRuns": 0,
  "minutesFreedByPlanRuns": 0,
  "minutesFreedByTaskRuns": 0,
  "totalMinutesFreed": 1620
}
This request generates cost savings using default report dates and time freed values:
curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: <rbac token>" \
-G "https://<pe-console-fqdn>/api/reports/value" \
--data-urlencode 'averageHourlySalary=40'
The result is:
{
  "startDate": "2020-07-08",
  "endDate": "2020-07-15",
  "totalCorrectiveChanges": 0,
  "minutesFreedByCorrectiveChanges": 0,
  "totalIntentionalChanges": 18,
  "minutesFreedByIntentionalChanges": 1620,
  "totalNodesAffectedByPlanRuns": 0,
  "totalNodesAffectedByTaskRuns": 0,
  "minutesFreedByPlanRuns": 0,
  "minutesFreedByTaskRuns": 0,
  "totalMinutesFreed": 1620,
  "totalDollarsSaved": 1080,
}
This request generates a report with custom values for time freed:
curl -X GET --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" \
-H "X-Authentication: $(cat ~/.puppetlabs/token)" \
-G "https://<pe-console-fqdn>/api/reports/value" \
--data-urlencode 'minutesFreedPerCorrectiveChange=10' \
--data-urlencode 'minutesFreedPerIntentionalChange=20' \
--data-urlencode 'minutesFreedPerTaskRun=30' \
--data-urlencode 'minutesFreedPerPlanRun=40'
The result is:
{
  "startDate": "2020-07-01",
  "endDate": "2020-07-08",
  "totalCorrectiveChanges": 1,
  "minutesFreedByCorrectiveChanges": 10,
  "totalIntentionalChanges": 2,
  "minutesFreedByIntentionalChanges": 40,
  "totalNodesAffectedByTaskRuns": 3,
  "minutesFreedByTaskRuns": 90,
  "totalNodesAffectedByPlanRuns": 4,
  "minutesFreedByPlanRuns": 160,
  "totalMinutesFreed": 300
}