Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Monitoring and reporting Grey arrow pointing right Status API Grey arrow pointing right Metrics API Grey arrow pointing right

Metrics API

Sections

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'Copied!

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