Metrics API v2

To configure Jolokia metrics, create the /etc/puppetlabs/puppetdb/conf.d/metrics.conf file if one doesn't exist. This file should contain a section like the example shown below.

metrics {
    metrics-webservice: {
        jolokia: {
          #enabled: false # uncomment this line to disable jolokia metrics
            #servlet-init-params: {
                ## Specify a custom security policy:
                ## https://jolokia.org/reference/html/security.html
                #policyLocation: "file:///etc/puppetlabs/puppetdb/jolokia-access.xml"
            #}
        }
    }
}

To change the security access policy, create the /etc/puppetlabs/puppetdb/jolokia-access.xml file with contents that follow the Jolokia access policy and uncomment the metrics.metrics-webservice.jolokia.servlet-init-params.policyLocation parameter before restarting puppetdb.

The metrics.metrics-webservice.jolokia.servlet-init-params table within the /etc/puppetlabs/puppetdb/conf.d/metrics.conf file provides more configuration options. See Jolokia's agent initialization documentation for all of the available options.

To disable the v2 endpoints, set the metrics.metrics-webservice.jolokia.enabled parameter in metrics.conf to false.

This endpoint requires an operation, and depending on the operation can accept or might require an additional query:

GET /metrics/v2/<OPERATION>/<QUERY>

You can also submit a POST request with the query as a JSON document in the body of the POST.

You can combine both of these features to query garbage collection data, but return only the collection counts and times.

GET metrics/v2/read/java.lang:name=*,type=GarbageCollector/CollectionCount,CollectionTime

This returns a JSON response:

{
  "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 advanced usage.

• puppetlabs.puppetdb.population:name=num-nodes: the number of nodes in your population.

• puppetlabs.puppetdb.population:name=num-resources: the number of resources in your population.

• puppetlabs.puppetdb.population:name=avg-resources-per-node: the average number of resources per node in your population.

• puppetlabs.puppetdb.population:name=pct-resource-dupes: the percentage of resources that exist on more than one node.

PuppetDB relies on the HikariCP connection pool. The complete list of HikariCP metrics and their names can be found in their documentation. All the database metrics have the following naming convention:

puppetlabs.puppetdb.database:PDBWritePool.<HikariCP metric>
puppetlabs.puppetdb.database:PDBReadPool.<HikariCP metric>

PuppetDB maintains various command processing metrics, all computed with respect to the last restart. There are global statistics, aggregated across all commands, and individual statistics, computed for each version of each command.

PuppetDB automatically collects metrics about every URL it has served to clients. You can see things like the average response time on a per-URL basis, or see how many requests against a particular URL resulted in a HTTP 400 response code. Each of the following metrics is available for each URL. The list of automatically generated metrics is available via the /metrics/v2 endpoint.

Additionally, we also support the following explicit names:

Note: The use of these explicit names is deprecated; please use, for example, /pdb/cmd/v1 instead.

• commands: stats relating to the command processing REST endpoint. The PuppetDB-termini in Puppet talk to this endpoint to submit new catalogs, facts, etc.

• metrics: stats relating to the metrics REST endpoint. This is the endpoint you're reading about right now!

• facts: stats relating to fact querying.

• resources: stats relating to resource querying. This is the endpoint used when collecting exported resources.

In addition to customizing <name>, the following metrics are available for each HTTP status code (<status code>). For example, you can see the stats for all 200 responses for the resources endpoint. This allows you to see, per endpoint and per response, independent counters and statistics.

• puppetlabs.puppetdb.http:name=<name>.service-time: stats about how long it takes to service all HTTP requests to this endpoint

• puppetlabs.puppetdb.http:name=<name>.<status code>: stats about how often we're returning this response code

Metrics involving the PuppetDB storage subsystem all begin with the puppetlabs.puppetdb.storage:name= prefix. There are a number of metrics concerned with individual storage operations (storing resources, storing edges, etc.). Metrics of particular note include:

• puppetlabs.puppetdb.storage:name=duplicate-pct: the percentage of catalogs that PuppetDB determines to be duplicates of existing catalogs.

• puppetlabs.puppetdb.storage:name=gc-time: states about how long it takes to do storage compaction.

• java.lang:type=Memory: memory usage statistics.

• java.lang:type=Threading: stats about JVM threads.