Status API: metrics endpoint

Puppet Server can track advanced metrics to give you additional insight into its performance and health.

Restriction: These API endpoints are a tech preview. These metrics are returned only when the request contains the level=debug parameter. The response structure might change in future versions.

There are three metrics endpoints:

The services/pe-jruby-metrics endpoint returns JRuby metrics.
The services/pe-master endpoint returns HTTP route metrics.
The services/pe-puppet-profiler endpoint returns catalog compilation profiler metrics.

These metrics reflect data collected over the lifetime of the current Puppet Server process. Data resets when the service is restarted. All time-related metrics report in milliseconds unless otherwise noted.

GET /status/v1/services/pe-jruby-metrics

Returns JSON-formatted information about the JRuby pools from which Puppet Server fulfills agent requests.

Request format

The HTTPS metrics endpoints are available on port 8140 of the primary server. Your request must query port 8140 and include the level=debug parameter. For example:

uri="https://$(puppet config print server):8140/status/v1/services/pe-jruby-metrics?level=debug"

curl --insecure "$uri"

For information about puppet config commands and curl commands in Windows, go to Using example commands.

Response format

The server uses these response codes:

200 if, and only if, all services report a status of running.
503 if any service’s status is unknown or error.

In addition to a response code, the metrics endpoints return machine-consumable (JSON-formatted) information about PE services. These JSON responses use the same keys returned by the GET /status/v1/services and GET /status/v1/services/<SERVICE NAME> endpoints. The metrics endpoints also return additional keys in the experimental section of the response.

Within the experimental section of the pe-jruby-metrics endpoint response, the metrics are divided into two subsections: jruby-pool-lock-status and metrics.

The jruby-pool-lock-status subsection contains these keys:


Key	Definition
`current-state`	The JRuby pool lock state: `:not-in-use` (unlocked) `:requested` (waiting for lock) `:acquired` (locked)
`last-change-time`	The date and time of the last `current-state` update, formatted as an ISO 8601 combined date and time in UTC.

The metrics subsection contains these keys:


Key	Definition
`average-borrow-time`	The average time a JRuby instance spends handling requests. This is alculated by dividing the total duration in milliseconds of the `borrowed-instances` value by the `borrow-count` value.
`average-free-jrubies`	The average number of JRuby instances not used over the Puppet Server process’s lifetime.
`average-lock-held-time`	The average time the JRuby pool held a lock, starting when the value of `jruby-pool-lock-status/current-state` changed to `:acquired`. This time mostly represents the file sync service syncing code into the live codedir, and it is calculated by dividing the total length of time Puppet Server held the lock by the `num-pool-locks` value.
`average-lock-wait-time`	The average time Puppet Server spent waiting to lock the JRuby pool, starting when the value of `jruby-pool-lock-status/current-state` changed to`:requested`. This time mostly represents how long Puppet Server takes to fulfill agent requests, and it is calculated by dividing the total length of time Puppet Server waits for locks by the `num-pool-locks` value.
`average-requested-jrubies`	The average number of requests waiting on an available JRuby instance over the Puppet Server process’s lifetime.
`average-wait-time`	The average time Puppet Server spends waiting to reserve an instance from the JRuby pool. It is calculated by dividing the total duration, in milliseconds, of `requested-instances` by the `requested-count` value.
`borrow-count`	The total number of JRuby instances that have been used.
`borrow-retry-count`	The total number of times a borrow attempt failed and was retried, such as when the JRuby pool is flushed while a borrow attempt is pending.
`borrow-timeout-count`	The number of requests that were not served because they timed out while waiting for a JRuby instance.
`borrowed-instances`	A list of JRuby instances currently in use, with each reporting: `duration-millis`: The length of time that the instance has been running. `reason/request`: A hash of details about the request being served. `request-method`: The HTTP request method, such as POST, GET, PUT, or DELETE. `route-id`: The route being served. For routing metrics, see the HTTP metrics endpoint. `uri`: The request’s full URI. `time`: The time (in milliseconds, since the Unix epoch) when the JRuby instance was borrowed.
`num-free-jrubies`	The number of JRuby instances in the pool that are ready to be used.
`num-jrubies`	The total number of JRuby instances.
`num-pool-locks`	The total number of times the JRuby pools have been locked.
`requested-count`	The number of JRuby instances borrowed, waiting, or that have timed out.
`requested-instances`	A list of requests waiting to be served, with each reporting: `duration-millis`: The length of time the request has waited. `reason/request`: A hash of details about the waiting request. `request-method`: The HTTP request method, such as POST, GET, PUT, or DELETE. `route-id`: The route being served. For routing metrics, see the HTTP metrics endpoint. `uri`: The request’s full URI. `time`:The time (in milliseconds, since the Unix epoch) when Puppet Server received the request.
`return-count`	The total number of JRuby instances that have been used.

Here is an example response for the pe-jruby-metrics endpoint:

"pe-jruby-metrics": {
    "detail_level": "debug",
    "service_status_version": 1,
    "service_version": "2.2.22",
    "state": "running",
    "status": {
        "experimental": {
            "jruby-pool-lock-status": {
                "current-state": ":not-in-use",
                "last-change-time": "2015-12-03T18:59:12.157Z"
            },
            "metrics": {
                "average-borrow-time": 292,
                "average-free-jrubies": 0.4716243097301104,
                "average-lock-held-time": 1451,
                "average-lock-wait-time": 0,
                "average-requested-jrubies": 0.21324752542875958,
                "average-wait-time": 156,
                "borrow-count": 639,
                "borrow-retry-count": 0,
                "borrow-timeout-count": 0,
                "borrowed-instances": [
                    {
                        "duration-millis": 3972,
                        "reason": {
                            "request": {
                                "request-method": "post",
                                "route-id": "puppet-v3-catalog-/*/",
                                "uri": "/puppet/v3/catalog/hostname.example.com"
                            }
                        },
                        "time": 1448478371406
                    }
                ],
                "num-free-jrubies": 0,
                "num-jrubies": 1,
                "num-pool-locks": 2849,
                "requested-count": 640,
                "requested-instances": [
                    {
                        "duration-millis": 3663,
                        "reason": {
                            "request": {
                                "request-method": "put",
                                "route-id": "puppet-v3-report-/*/",
                                "uri": "/puppet/v3/report/hostname.example.com"
                            }
                        },
                        "time": 1448478371715
                    }
                ],
                "return-count": 638
            }
        }
    }
}

GET /status/v1/services/pe-master

Returns JSON-formatted information about the routes that agents use to connect to the primary server.

Request format

The HTTPS metrics endpoints are available on port 8140 of the primary server. Your request must query port 8140 and include the level=debug parameter. For example:

uri="https://$(puppet config print server):8140/status/v1/services/pe-master?level=debug"

curl --insecure "$uri"

For information about puppet config commands and curl commands in Windows, go to Using example commands.

Response format

The server uses the following response codes:

200 if, and only if, all services report a status of running.
503 if any service’s status is unknown or error.

Within the experimental section of the pe-master endpoint response, there is one subsection, http-metrics, containing these keys:


Key	Definition
`aggregate`	The total time Puppet Server spent processing requests for this route.
`count`	The total number of requests Puppet Server processed for this route.
`mean`	The average time Puppet Server spent on each request for this route, calculated by dividing the `aggregate` value by the `count` value.
`route-id`	The route being served. The request returns a route with the special `route-id` of `total`, which represents the aggregate data for all requests along all routes. If not `total`, values use the `puppet-v3` prefix, such as `puppet-v3-report/*/`.

GET /status/v1/services/pe-puppet-profiler

Returns JSON-formatted statistics about catalog compilation. You can use this data to discover which functions or resources are consuming the most resources or are most frequently used.

Request format

The HTTPS metrics endpoints are available on port 8140 of the primary server. Your request must query port 8140 and include the level=debug parameter. For example:

uri="https://$(puppet config print server):8140/status/v1/services/pe-puppet-profiler?level=debug"

curl --insecure "$uri"

For information about puppet config commands and curl commands in Windows, go to Using example commands.

Response format

The server uses the following response codes:

200 if, and only if, all services report a status of running.
503 if any service’s status is unknown or error.

The Puppet Server profiler is enabled by default, but if it is disabled, there are no metrics available for the pe-puppet-profiler endpoint to return. In this case, the endpoint returns the same keys as GET /status/v1/services and an empty status key.

If the profiler is enabled, within the experimental section of the pe-puppet-profiler endpoint response, the metrics are divided into two subsections:

function-metrics: Contains statistics about functions evaluated by Puppet Server when compiling catalogs.
resource-metrics: Contains statistics about resources declared in manifests compiled by Puppet Server.

You'll find these keys in the two subsections:


Key	Definition
`function` or `resource`	Each function measured in the `function-metrics` section has a `function` key containing the function's name. Each resource measured in the `resource-metrics` section has a `resource` key containing the resource's name.
`aggregate`	The total time spent handling the function call or resource during catalog compilation.
`count`	The number of times during catalog compilation that Puppet Server has called the function or instantiated the resource.
`mean`	The average time spent handling the function call or resource during catalog compilation. This is calculated by dividing the `aggregate` value by the `count` value.

Here is an example response for the pe-puppet-profiler endpoint:

"pe-puppet-profiler": {
    {...},
    "status": {
        "experimental": {
            "function-metrics": [
                {
                    "aggregate": 1628,
                    "count": 407,
                    "function": "include",
                    "mean": 4
                },
                {...},
            "resource-metrics": [
                {
                    "aggregate": 3535,
                    "count": 5,
                    "mean": 707,
                    "resource": "Class[Puppet_enterprise::Profile::Console]"
                },
                {...},
            ]
        }
    }
}

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

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.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.