Metrics API

Puppet Enterprise (PE) includes an optional web endpoint for Java Management Extension (JMX) metrics, namely managed beans (MBeans).

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.

These endpoints include:

GET /metrics/v1/mbeans
POST /metrics/v1/mbeans
GET /metrics/v1/mbeans/<name>

These endpoints are enabled by default, and you can disable them by setting puppet_enterprise::master::puppetserver::metrics_webservice_enabled: false in Hiera.

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

GET /metrics/v1/mbeans

Lists available MBeans.

Response keys

The response consists of a key-value pairs where the key is the name of a valid MBean and the value is a URI you can use to request the MBean's attributes.

POST /metrics/v1/mbeans

Retrieves requested MBean metrics.

Request format

The request body must contain one of the following:

A JSON object whose values are metric names
A JSON array of metric names
A JSON string containing a single metric's name

Use GET /metrics/v1/mbeans to get a list of metric names.

Response format

The response is either a JSON object or array, depending on the request format:

Requests supplying a JSON object return a JSON object where the values of the original object are transformed into the Mbeans' attributes for the metric names.
Requests supplying a JSON array return a JSON array where the items of the original array are transformed into the Mbeans' attributes for the metric names.
Requests supplying a JSON string return the a JSON object of the Mbean's attributes for the given metric name.

GET /metrics/v1/mbeans/<name>

Reports on a single MBean metric.

Request format

The request doesn't require any parameters, but the endpoint URI path must correspond to a metric returned by GET /metrics/v1/mbeans.

For example, this curl request queries data on MBean memory usage:

curl 'http://localhost:8080/metrics/v1/mbeans/java.lang:type=Memory'

Response format

The response contains a JSON object mapping strings to values. The keys and values returned in the response depend on the metric supplied in the request.

For example, a request querying MBean memory usage (such as the java.lang:type=Memory metric), might return a response similar to the following:

{
  "ObjectPendingFinalizationCount" : 0,
  "HeapMemoryUsage" : {
    "committed" : 807403520,
    "init" : 268435456,
    "max" : 3817865216,
    "used" : 129257096
  },
  "NonHeapMemoryUsage" : {
    "committed" : 85590016,
    "init" : 24576000,
    "max" : 184549376,
    "used" : 85364904
  },
  "Verbose" : false,
  "ObjectName" : "java.lang:type=Memory"
}