Value report

Value analytics give you insight into time and money freed by PE automation. You can access these analytics by viewing the Value report page in the console or using the value API.

The value report and the value API provide details about automated changes that PE makes to nodes, and provides an estimate of time freed by each type of change based on intelligent defaults or values you provide. You can also specify an average hourly salary and see an estimate of cost savings for all automated changes.

Follow these best practices to ensure your value analysis is accurate:
  • Failed runs aren't tallied by value analytics, so ensure that tasks, plans, and Puppet runs are processing normally.
  • If you are using the API, query the endpoint on a regular basis to gather data over a period of time.

Value report defaults

The value report provides an estimate of time freed by automated changes based on intelligent defaults. These defaults are based on customer research and take into account time to triage, research, and fix issues, as well as context switching.

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 business. In the console value report, you specify an exact value in minutes. Unless you select otherwise, both the API and the console value report use the med value to estimate time freed by automation.
Parameter Value
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 estimates of time freed 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 /value endpoint to retrieve information about time and money freed by PE automation.

Forming requests

Requests to the value API must be well-formed HTTP(S) requests.

By default, the value API uses the standard HTTPS port for console communication, port 443. You can omit the port from requests unless you want to specify a different port.

Authenticating

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.

A simple, authenticated API request without any parameters looks like this:
curl -X GET --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
-H "X-Authentication: <RBAC_TOKEN>" \
"https://<HOSTNAME>/api/reports/value"

See Usage notes for curl examples for information about forming curl commands.

Query parameters

The request accepts the following parameters, appended with --data-urlencode:

Parameter Value Default
averageHourlySalary Numeric value specifying average hourly cost savings for automated work. none
startDate Date in yyyy-mm-dd format. 1 week ago +2 days
endDate Date in yyyy-mm-dd format.

Specifying the current date results in provisional data.

 today -2 days
minutesFreedPerCorrectiveChange
  • low
  • med
  • high
  • any numeric value in minutes
 med
minutesFreedPerIntentionalChange
  • low
  • med
  • high
  • any numeric value in minutes
 med
minutesFreedPerTaskRun
  • low
  • med
  • high
  • any numeric value in minutes
 med
minutesFreedPerPlanRun
  • low
  • med
  • high
  • any numeric value in minutes
 med

Response format

The response is a JSON object that lists details about time and cost freed, using the following 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.

Examples

To generate 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'
Result:
{
  "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
}
To generate 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'
Result:
{
  "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,
}
To generate 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'
Result:
{
  "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
}