Metrics API v1

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

Restriction: The metrics/v1/ endpoints are deprecated. We recommend using the Metrics API v2 endpoints instead.

If you choose to use the deprecated v1 endpoints, metrics are returned only when the request contains the level=debug parameter. The response structure might change in future versions.

The v1 endpoints include:

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

Set the following parameter in Hiera to enable these endpoints:

puppet_enterprise::master::puppetserver::metrics_webservice_enabled: true

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

For information about Java, refer to the Java documentation:

GET /metrics/v1/mbeans (deprecated)

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 (deprecated)

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 (deprecated) 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> (deprecated)

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 (deprecated).

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"
}