How to use the Hawkular Metrics API
Overview
This guide is intended to give you enough information to formulate basic memory usage or cpu queries against nodes in your cluster. For more advanced usage please refer to the Hawkular documentation at https://www.hawkular.org/hawkular-metrics/docs/user-guide/#_metrics or the OpenShift Hawkular repository readme at https://github.com/openshift/origin-metrics/blob/master/docs/hawkular_metrics.adoc.
Using the API
To query the API, you must be authenticated as a user that has reader permissions on the OpenShift project that contains the Hawkular-Tenant you are querying. If you are querying the _system tenant then you must also have cluster-reader permissions.
To get a list of all node level counters and gauges you can use, run the following:
curl -X GET https://hawkular-metrics.$(cluster-url)/hawkular/metrics/metrics "Content-Type: application/json" -H "Hawkular-Tenant: _system" -H "Authorization: Bearer $token"
Where
$token
is a variable storing the output ofoc whoami -t
from an OpenShift user with the correct permissions to view metrics and$cluster-url
is the domain suffix of your cluster.For example, if your cluster URL is
https://ocp.openshift-test.cna.ukcloud.com:8443
, your query would be the following:curl -X GET https://hawkular-metrics.openshift-test.cna.ukcloud.com/hawkular/metrics/metrics "Content-Type: application/json" -H "Hawkular-Tenant: _system" -H "Authorization: Bearer $token"
You'll need to pass the output from the request into some form of JSON parser to get human readable results. It will return a series of JSON blocks similar to the following:
{ "dataRetention": 7, "id": "cluster/memory/usage", "maxTimestamp": 1543500090000, "minTimestamp": 1543491120000, "tags": { "descriptor_name": "memory/usage", "group_id": "/memory/usage", "type": "cluster", "units": "bytes" }, "tenantId": "_system", "type": "gauge" }
This is the gauge for cluster memory usage and you can query the raw data using the id from the above block as follows:
curl -X GET https://hawkular-metrics.openshift-test.cna.ukcloud.com/hawkular/metrics/gauges/cluster%2Fmemory%2Fusage/raw "Content-Type: application/json" -H "Hawkular-Tenant: _system" -H "Authorization: Bearer $token"
This will return a series of data points like the following:
{ "timestamp": 1543491120000, "value": 3593875456.0 }
The timestamp is in Epoch and you can determine the value by looking at the gauge object. The code sample in step 3 shows that the value is in bytes ("units": "bytes").
Note
You must encode the ID returned in the first request (cluster/memory/usage) correctly in the second request by replacing the / with %2F.
Feedback
If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to feedback@ukcloud.com.