Collecting value analytics

We've updated our documentation to remove harmful terminology.
Sections

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.

Default settings for time freed by each type of automated change are based on customer research. Defaults take into account time to triage, research, and fix issues, as well as context switching. You can specify low, med, or high values for time freed parameters, or provide an exact value based on averages in your business.

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 suing the API, query the endpoint on a regular basis to gather data over a period of time.

Access the value report

You can use the console to access a snapshot of the time PE automation has reclaimed for you, as well as customize the date and time range PE uses to make these calculations.

Access the Value report page in the Admin section of the console. The Value report page displays the total time reclaimed per node, per day, and over the selected date range.

Click Configure report to change the date range or change the average amount of time reclaimed with each action in your environment: intentional changes, correctional changes, task runs, or plan runs. If you're unsure how much time each action reclaims, click View recommended ranges for guidance.

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 https://<HOSTNAME>/api/reports/value \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  -H "X-Authentication: <RBAC_TOKEN>"

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

Query parameters

The request accepts the following parameters:

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 (90 minutes)
  • med (180 minutes)
  • high (360 minutes)
  • any numeric value in minutes
med
minutesFreedPerIntentionalChange
  • low (30 min)
  • med (90 minutes)
  • high (180 minutes)
  • any numeric value in minutes
med
minutesFreedPerTaskRun
  • low (30 minutes)
  • med (90 minutes)
  • high (180 minutes)
  • any numeric value in minutes
med
minutesFreedPerPlanRun
  • low (90 minutes)
  • med (180 minutes)
  • high (360 minutes)
  • 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 -G https://<HOSTNAME>/api/reports/value \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  -H "X-Authentication: <RBAC_TOKEN>" \
  --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 -G https://<pe-console-fqdn>/api/reports/value \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  -H "X-Authentication: <rbac token>" \
  --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 -G https://<pe-console-fqdn>/api/reports/value \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  -H "X-Authentication: $(cat ~/.puppetlabs/token)" \
  --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
}
How helpful was this page?

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.