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.