Custom metrics API

Custom metrics can be sent to the OpsClarity Custom Metric API available on the agent already installed in a host.  
URL End Point
Opsclarity Agent listens at port 10101 by default, if this port is taken, it will listen at port 10102 or 10103.. 
Current Port at which the agent is listening can be obtained by any of the below commands.
sudo netstat -tulnp | grep opsclarity 
grep port /opt/opsclarity/agent/current/conf/custom-application.gcfg  | uniq  | awk '{print $3}'
API URL for default Port (10101):
When the application is running in a container, the application can send custom metrics to host IP address. URL would be 
Host IP Address, which is usually the default route for the container can be obtained by executing the following command in container 
/sbin/ip route|awk '/default/ { print $3 }' 
The bare minimum JSON format is "name" and "points", where a point is an epoch timestamp and a value:
 [{"name": "", "points": [[ 1438018557, 50 ]]}]

The value can be floating point, so you can use fractional values: 
 [{"name": "", "points": [[ 1438018557, 0.50 ]]}] 
Here is an example for sending metrics from a script with curl: 
# curl example: post simple metric to api
timestamp=$(date +%s)
curl -H "Content-Type: application/json" -X POST --data-binary @- \ << JSON
"name": "$metric",
[$timestamp, $value]
Full API 
The API accepts lists of metrics, lists of points for each metric, and tag annotations for each metric or for each point.
      "name": "$",
      "tags": {
         "$tag1": "$label1",
         "$tag2": "$label2"
"aggregation": "max", // [Optional] min|max|avg|sum. Default is avg
"points": [
[ 1438018556, 25, { "$itemTag": "$label3" } ],
[ 1438018557, 50 ],
[ 1438018558, 75, {"$optionalTag": "$label4", "$optionalTag2": "$label5"}]
A tag annotation is a dictionary of key value pairs, and can be used to slice and dice your metrics. For example you might want to tag the cluster name, or the application, or the environment:
"tags": {
   "cluster": "primary",
   "env": "production",
   "app": "search"

The dataPoints received will be aggregated every 15 seconds into a single dataPoint
according to aggregation field.
Default aggregation is average. 
Request Headers
Content-Type          Application/JSON

Query Parameters


Response Codes

400                   Bad or malformed request
404                   Resource or api not found
500                   Internal server error
501                   API not implemented
503                   Service unavailable (retry later)
200                   OK
204                   No content 

Once you've implemented your custom code, head on over to our troubleshooting steps to see how you can drill down into the health status which can be based in part on your custom metrics.


If you have any questions or comments about this article, feel free to contact us at

2016.2.4 0.8.111

Have more questions? Submit a request


Please sign in to leave a comment.