Metrics API v2

The /metrics/v2/ endpoints use the Jolokia library for Java Management Extension (JMX) metrics to query Orchestrator service metrics.

Jolokia is an extensive, open-source metrics library. We've described how to use the metrics according to the default Puppet Enterprise (PE) configuration; however, you can find more features described in the Jolokia documentation.

For security reasons, by default, we only enable the read-access Jolokia interface, which includes the read, list, version, and search operations. You can Configure Jolokia if you want to change the security access policy.

Configure Jolokia

You can customize your Jolokia security access policy and metrics.conf settings. You can also use these steps to disable the /metrics/v2/ endpoints.

  1. To change the security access policy:
    1. Create a jolokia-access.xml file at the following location: 
      /etc/puppetlabs/orchestration-services/jolokia-access.xml
    2. Populate the file contents according to your desired Jolokia access policy (as described in the security chapter of the Jolokia documentation), and uncomment the following parameter: 
      metrics.metrics-webservice.jolokia.servlet-init-params.policyLocation
    3. Save the file and restart the Puppet Server service.
  2. For additional configuration options, refer to the metrics.metrics-webservice.jolokia.servlet-init-params table in the metrics.conf file located at: 
    /etc/puppetlabs/orchestration-services/conf.d/metrics.conf
    Jolokia's Servlet init parameters documentation explains the various options available in this table.
    Tip: To disable the /metrics/v2/ endpoints, open the metrics.conf file and set the metrics.metrics-webservice.jolokia.enabled parameter to false.

Forming metrics API requests

The metrics API accepts well-formed HTTPS requests.

Orchestrator API requests must include a URI path following the pattern:
https://<DNS>:<PORT>/metrics/v2/<OPERATION>
The variable path components derive from:
  • DNS: Your PE console host's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
  • PORT: The PuppetDB service port.
  • OPERATION: One or more sections specifying the operation for the request, such as list or read. Some operations require, or allow, additional modifiers such as queries, attributes, and MBean names.
For example, you could use these paths to call the GET /metrics/v2/<OPERATION> endpoint with the list operation:
https://$(puppet config print server):8081/metrics/v2/list
https://puppet.example.dns:8081/metrics/v2/list

To form a complete curl command, you need to provide appropriate curl arguments, and authorization (in the form of a Puppet certificate), the content type, and/or additional parameters specific to the endpoint you are calling.

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

Metrics API wildcards and filtering

The /metrics/v2/ endpoints support globbing (wildcard selection) and response filtering. You can also combine these features in the same request.

For example, this request uses GET /metrics/v2/<OPERATION> with wildcards and filtering to get only collection counts and times from garbage collection data:
curl 'http://puppet.example.dns:8081/metrics/v2/read/java.lang:name=*,type=GarbageCollector/CollectionCount,CollectionTime'
The response is:
{
  "request": {
    "mbean": "java.lang:name=*,type=GarbageCollector",
    "attribute": [
      "CollectionCount",
      "CollectionTime"
    ],
    "type": "read"
  },
  "value": {
    "java.lang:name=PS Scavenge,type=GarbageCollector": {
      "CollectionTime": 1314,
      "CollectionCount": 27
    },
    "java.lang:name=PS MarkSweep,type=GarbageCollector": {
      "CollectionTime": 580,
      "CollectionCount": 5
    }
  },
  "timestamp": 1497977710,
  "status": 200
}

Refer to the Jolokia protocol documentation for more information.

GET /metrics/v2/<OPERATION>

Retrieve orchestrator service metrics data or metadata.

Request format

When Forming metrics API requests to this endpoint, you must specify an operation. Some operations also require you to specify a query. For example:
GET /metrics/v2/<OPERATION>/<QUERY>
As a starting point, use the list operation to get a list of all valid MBeans:
GET /metrics/v2/list
Using information returned from the list operation, you can form more complex and targeted queries. For example, this request uses the read operation to query registered logger names:
GET /metrics/v2/read/java.until.logging:type=Logging/LoggerNames
The request format to query MBeans is:
GET /metrics/v2/read/<MBEAN_NAMES>/<ATTRIBUTES>/<INNER_PATH_FILTER>

MBean names are created by joining the first two keys in the list response's value object with a colon (which are the domain and prop list, in Jolokia terms), such as java.until.logging:type=Logging.

Attributes are derived from the attr object, which is within the value object in the list response.

If you specify multiple MBean names or attributes, use comma separation, such as: /java.lang:name=*,type=GarbageCollector/

The inner path filter is optional and depends on the MBeans and attributes you are querying.

You must use the read operation to query MBeans.

Tip: Requests can also use wildcards and filtering, as described in Forming metrics API requests.

For more complex queries, or queries containing special characters, use POST /metrics/v2/<OPERATION>.

Response format

A successful request returns a JSON object containing a series of objects, arrays, and/or key-value pairs describing metrics data or metadata, based on the content of the request.

For example, the response to GET /metrics/v2/list contains metadata about MBeans you can use to create targeted queries, such as:
{
  "request": {
    "type": "list"
  },
  "value": {
    "java.util.logging": {
      "type=Logging": {
        "op": {
          "getLoggerLevel": {
            ...
          },
          ...
        },
        "attr": {
          "LoggerNames": {
            "rw": false,
            "type": "[Ljava.lang.String;",
            "desc": "LoggerNames"
          },
          "ObjectName": {
            "rw": false,
            "type": "javax.management.ObjectName",
            "desc": "ObjectName"
          }
        },
        "desc": "Information on the management interface of the MBean"
      }
    },
    ...
  }
}
In contrast, the response to a targeted query, such as /metrics/v2/read/java.until.logging:type=Logging/LoggerNames, contains more specific data. For example:
{
  "request": {
    "mbean": "java.util.logging:type=Logging",
    "attribute": "LoggerNames",
    "type": "read"
  },
  "value": [
    "javax.management.snmp",
    "global",
    "javax.management.notification",
    "javax.management.modelmbean",
    "javax.management.timer",
    "javax.management",
    "javax.management.mlet",
    "javax.management.mbeanserver",
    "javax.management.snmp.daemon",
    "javax.management.relation",
    "javax.management.monitor",
    "javax.management.misc",
    ""
  ],
  "timestamp": 1497977258,
  "status": 200
}

POST /metrics/v2/<OPERATION>

Use more complicated queries to retrieve orchestrator service metrics data or metadata.

POST /metrics/v2/ is functionally the same as GET /metrics/v2/<OPERATION>, except that your query is appended in JSON format. This is useful when your query is complex or includes special characters.

When forming your request, the content type is application/json and the body must be a JSON object.