Metrics API v1
The following v1 endpoints are available:
-
GET /metrics/v1/mbeans
-
POST /metrics/v1/mbeans
-
GET /metrics/v1/mbeans/<name>
To activate these endpoints in Hiera(Built-in key-value configuration data lookup system), set the following parameter:
puppet_enterprise::master::puppetserver::metrics_webservice_enabled: true
GET /metrics/v1/mbeans (deprecated)
It lists available mbeans in the metrics.
Response keys
The answer is a key-value pair, with the key being the name of a valid mbean and the value being a URI that may be used to request the mbean's characteristics or attributes.
POST /metrics/v1/mbeans
It retrieves requested MBean metrics.
Format of Request
The request body must include at least one of the following:
-
A JSON object with metric names as values.
-
A JSON array containing the names of metrics.
-
A JSON string holds the name of a single metric.
To acquire a list of metric names, use GET /metrics/v1/mbeans (deprecated).
Format of Response
Depending on the request format, the answer is either a JSON object or an array:
-
Requests that include a JSON object return a JSON object in which the original object's values are translated into the mbeans' attributes for the metric names.
- Requests that include a JSON array return a JSON array in which the original array's contents are translated into mbeans' attributes for the metric names.
GET /metrics/v1/mbeans/<name> (deprecated)
It reports on a single MBean metric.
Format of Request
There are no arguments required for the request. However, the endpoint URI URL must coincide with a metric returned by GET /metrics/v1/mbeans (deprecated).
This command, for example, asks for data on MBean memory consumption.
curl 'http://localhost:8080/metrics/v1/mbeans/java.lang:type=Memory'
Format of Response
The answer includes a JSON object that maps strings to values. The answer keys and values are determined by the metric specified in the request.
Metrics API v2
To query Orchestrator service metrics, the /metrics/v2/ endpoints use the Jolokia library for Java Management Extension (JMX) metrics.
Jolokia is a large and open-source metrics library. We've reviewed how to use the metrics in the standard Puppet Enterprise (PE) setup.
They only allow the read-access Jolokia interface by default for security reasons, which comprises the read, list, version, and search actions. If you wish to alter the security access policy, you can configure Jolokia.
Jolokia configuration
You may change the security access policy and metrics.conf settings in Jolokia. These procedures can also be used to deactivate the /metrics/v2/ endpoints.
1. To alter the security access policy, follow these steps:
-
Create a Jolokia-access.xml file in /etc/puppetlabs/orchestration-services/jolokia-access.xml.
-
Fill up the file contents with your chosen Jolokia access policy (as indicated in the Jolokia documentation's security chapter), and uncomment the following parameter: metrics.metrics-webservice.jolokia.servlet-init-params.policyLocation.
- After saving the file, restart the Puppet Server service.
2. Refer to the metrics.metrics-webservice.jolokia.servlet-init-params table in the metrics.conf file for further configuration options located at /etc/puppetlabs/orchestration-services/conf.d/metrics.conf .
The documentation for Jolokia's Servlet init parameters outlines the many choices accessible in this table.
API Requests for Metrics
The metrics API allows HTTPS queries that are properly formatted.
Orchestrator API calls must contain the following URI path:
https://<DNS>:<PORT>/metrics/v2/<OPERATION>
The variables in the route are derived from:
-
DNS: The DNS name of your PE console host. You may use localhost, input the DNS name manually, or by using puppet commands.
-
PORT: It's a service port for PuppetDB .
-
OPERATION: One or more parts indicating the request's operation, such as a list or read. Some actions, including queries, attributes, and MBean names, allow extra modifiers.
You might, for example, use any of the following URLs to contact the GET /metrics/v2/OPERATION> endpoint with the list operation:
GET https://$(puppet config print server ):????/metrics/v2/list
GET https://localhost:PORT_NUMBER/metrics/v2/list
GET https://puppet.example.dns:PORT_NUMBER/metrics/v2/list
To finish a curl command, you must specify suitable curl arguments, as well as authentication, the content type, and/or extra parameters relevant to the endpoint you are contacting.
Use example commands for basic information on constructing curl commands, authentication in commands, and Windows adjustments.
GET/metrics/v2/OPERATION>
Get statistics or information about operation service metrics.
Request structure
You must provide an operation when sending metrics API calls to this endpoint. Some procedures additionally need the specification of a query, for example:
GET /metrics/v2/OPERATION>/QUERY>
To begin, use the list procedure to obtain a list of all valid MBeans:
GET/metrics/v2/list
You may create more complicated and focused searches using the information supplied by the list operation. For example, the read operation is used in this request 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 formed by merging the first two keys in the value object of the list response with a colon (which is the domain and prop list in Jolokia terminology), for example, java.until.logging:type=Logging.
Use comma separation when specifying several MBean names or characteristics, such as: /java.lang:name=*,type=GarbageCollector/.
The inner path filter is optional and is determined by the MBeans and attributes being queried. To query MBeans, you must utilize the read operation.
POST/metrics/v2/<OPERATION>
To extract information or data from the orchestrator service metrics, use more complex queries. POST /metrics/v2/ is equivalent to GET /metrics/v2/<OPERATION>, except that your query is added in JSON format. This is useful if your query is complicated or contains special characters.
When creating your request, be sure that the content type is application/json and that the body is a JSON object.
Frequently asked questions
What is a Puppet?
Puppet is a tool for managing software configurations with declarative language describing system setup.
What precisely is Configuration Management?
Configuration management is the process through which an organization specifies and monitors the status of its infrastructure resources. Configuration management solutions log configuration changes as they occur, allowing you to see what needs to be fixed or changed on any given day of operation.
What is Metrics API in Puppet?
This API allows you to query Puppet Server performance and use statistics in a better and more precise way, which gives users a better grip on Puppet Tools.
What are the different versions of Metrics API in Puppet?
Metrics API in Puppet is of two different versions, Metrics API v1 and Metrics API v2, but we generally use Metrics API v2 because it is an updated version of Metrics API v1.
What is Metrics API v2?
The v2 metrics endpoint uses Jolokia-based metrics, allowing you to query the metrics v2 services using a GET or POST request that produces a JSON document.
Conclusion
In this article, we learned about Metrics API in Puppet.
After reading about Metrics API in Puppet, are you not feeling excited to read/explore more articles on Puppet? Don't worry; Coding Ninjas has you covered. See:
Managing Access in Puppet
SAML Authentication in Puppet
Basic Concept of Managing Nodes in Puppet
Refer to our Guided Path on Code studio to upskill yourself in Data Structures and Algorithms, Competitive Programming, JavaScript, System Design, and many more!
27+ registered 
