Performing metric operations with the REST API

The following section provides a list of supported endpoints and an overview about running these endpoints. Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API Open link

Metric Ingestion

POST /insert

Insert metrics data in the time series database, and convert the data to the device and entity format

Request URL

https://<Host:Port>/metrics-gateway-service/api/v1.0/insert

Request Header

Content-Type: Application/json
Authorization: Bearer <Jwt_Token>/<apiKey>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Request body

#Following is an example of the PATROL Agent metrics data format
[
{
"labels": {
"metricName": "<metric name>",
"hostname": "<hostname>" ,
"entityId": "<source name>:<hostname>:<entityTypeId>:<entityName>",
"entityTypeId": "<Name of the entityTypeId>",
"entityName": "<Name of entity name>",
"hostType": "<type of host>",
"isKpi": <isKpi>,
"unit": "<unit type>",
"entityId":"<entity ID>",
"instanceName":"<instance name>"
"source": "<source type>"
}
"samples": [
{
"value": <value>,
"timestamp": <timestamp>
},
{
"value": <value>,
"timestamp": <timestamp>
}
]
}
]

Example - Request body

[
   {
      "labels":{
         "metricName":"offset",
         "hostname":"clm-HostA",
         "source":"nagios",
         "entityTypeId":"segmentEntityType1",
         "entityName":"entitysegment",
         "hostType":"server",
         "isKpi":"True",
         "unit":"Percent",
         "entityId":"nagios:clm-pun-microbots77:segmentEntityType1:entitysegment",
         "instanceName":"segment"
      },
      "samples":[
         {
            "value":90,
            "timestamp":1639030067000
         }
      ]
   },
   {
      "labels":{
         "metricName":"offset",
         "hostname":"clm-HostA",
         "source":"nagios",
         "entityTypeId":"segmentEntityType2",
         "entityName":"entitytower1",
         "hostType":"server",
         "isKpi":"True",
         "unit":"Percent",
         "parentEntityName":"entitysegment",
         "parentEntityTypeId":"segmentEntityType1",
         "entityId":"nagios:clm-pun-microbots77:segmentEntityType2:entitytower1",
         "instanceName":"tower1",
         "isDeviceMappingEnabled":"true"
      },
      "samples":[
         {
            "value":90,
            "timestamp":1639030067000
         }
      ]

Parameter Name Value Type Mandatory Description

labels : {

metricName hostname entityId entityTypeId entityName hostType isKpi unit source

}

Object (Map)

Yes

The following parameters are supported:

metricName (type: String): Name of the metric data.
Note: The metricName is stored as __name__ label in the timeseries database.
hostname (type: String): Hostname of the monitored device.
entityId (type: String): <source name>:<hostname>:<entityTypeId>:<entityName>
entityTypeId (type: String): Entity type identifier.
entityName (type: String): Entity name of the monitored data.
parentEntityName (type: String): Entity name of the monitored data parent.
parentEntityTypeID (type: String): Entity type identifier of the monitored data parent.
hostType(type: String): Host computer type. For example, server, web server, application server, etc.
isKpi (type: Boolean): Specifies if the monitored data is a key performance indicator.
Possible values:
True
False
Default value: False
isDeviceMappingEnabled: Indicates the monitor in the hierarchy that is mapped to the device. At least one monitor must be mapped.
unit (type: String): Unit used to measure the monitored data. For example, byte is used to measure total disk capacity (DISK_TOTAL), seconds is used to measure the CPU speed.
source (type: String): Name of the monitored data source. For example, CO (Capacity Optimization), HM (Helix Operations Management), CCC (Cloud Cost Control), etc.
instanceName (type:String): The display name of the monitor.
external_id: Parameter used to add a custom tag on the monitor.

samples: [

{ value timestamp }

Object (List)

No

List of samples. Samples contain the monitored data value and the timestamp details.

The following parameters are supported:

value (type: Double (float value) or Integer): Monitored data value
timestamp (type: Integer): Epoch time (in milliseconds)

Response codes:

200 (OK): Successful response
400 (Bad Request): Unsuccessful response
401 (Unauthorized): Unsuccessful response

POST /prometheus

Send Prometheus metrics to BMC Helix Operations Management

Request URL

https://<Host:Port>/metrics-gateway-service/api/v1.0/prometheus

Request Header

Content-Type : application/x-www-form-urlencodedapplication/x-protobuf
Authorization: Bearer <Jwt_Token>/<apiKey>
Content-Encoding : Snappy

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

To send Prometheus metrics to BMC Helix Operations Management, following exporters are supported:

Node exporter
Windows exporter
Oracle database exporter
Kafka exporter
Redis exporter

Response codes:

200 (OK): Successful response
400 (Bad Request): Unsuccessful response
401 (Unauthorized): Unsuccessful response

POST /delete

Delete the device details from BMC Helix Operations Management

You can use this API to delete only the data that is inserted using the /insert API.

Request URL

https://<Host:Port>/metrics-gateway-service/api/v1.0/delete

Request Header

Content-Type: Application/json
Authorization: Bearer <Jwt_Token>/<apiKey>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{
"devices": [
{
"hostname": "<hostname>",
"source": "<source name>"
}
]
}

Example - Request body

{
"devices": [
{
"hostname": "clm-HostA",
"source": "co"
}
]
}

Parameter Name Value Type Mandatory Description

devices : [
{
hostname
source
}
]

Object (List)

Yes

A list of devices.

The following parameters are supported:

hostname (type: String): Hostname of the monitored device.
source (type: String): Name of the monitored data source. For example, CO (Capacity Optimization), HM (Helix Operations Management), CCC (Cloud Cost Control), etc.

Response codes:

200 (OK): Successful response
400 (Bad Request): Unsuccessful response
401 (Unauthorized): Unsuccessful response

Note

The monitor details in the Non BMC MonitorTypes category are retained in the system even after device deletion.
For example: entityTypeId, entityName

Metric Query

GET /query?query=<query>

Get the time series data by specifying the timeselector query using labels and timestamp

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/query?query=<query>

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<Labels name>="<name>"}&time=<time stamp>

Example - Request body

{entityName="NUK_Memory"}&time=1595226431

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

For example, if you have inserted the following labels, you can query the timeseries data using any of the labels such as __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

{
"labels": {
"metricName": "Utilization",
"hostname": "clm-HostA",
"entityId": "CO:clm-HostA:DISKMONITOR:CPU_TOTAL",
"entityTypeId": "DISKMONITOR",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

time

Integer

No

Epoch time (in milliseconds)

Note: If you do not specify the time, the API will get the data for the current timestamp.

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET /query_range?query=<query>

Get the time series data by specifying the timeselector query using labels and time frame

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/query_range?query=<query>

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<labels name>="<name>"}&start=<start time stamp>&end=<end timestamp>

Example - Request body

{source="Helix"}&start=1595230019&end=1595250019

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

If you have inserted labels as shown in the following example, you can query the timeseries data using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

Example:

{
"labels": {
"metricName": "Utilization",
"hostname": "clm-HostA",
"entityId": "CO:clm-HostA:DISKMONITOR:CPU_TOTAL",
"entityTypeId": "DISKMONITOR",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

start

Integer

No

Epoch time (in milliseconds)

Note: If you do not specify both the start and end time, the API will get the data for the following time frame: Current time - 5 minutes

end Integer No Epoch time (in milliseconds)

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET /labels

Get all the labels from the time series database

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/labels

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Example: Output

{
"status": "success",
"data": [
  "VictoriaMetrics_AccountID",
  "__name__",
  "deviceId",
  "entityId",
  "entityName",
  "entityTypeId",
  "hostname",
  "isblackout",
  "source"
],
 
}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET /label/<lable_name>/values

Get the specified label values from the time series database

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/label/<lable_name>/values

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Example request URL: List the entityNames

https://<Host:Port>/metrics-query-service/api/v1.0/label/entityName/values

Example: Output

Labels/Values
{
"status": "success",
"data": [
  "CPU0",
  "CPU1",
  "NUK_CPU",
  "NUK_FileSystem_Container",
  "NUK_Linux_OS",
  "NUK_Memory",
  "NUK_Network_Container",
  "boot",
  "dev",
  "dev-hugepages",
  "dev-mqueue",
  "dev-pts",
  "dev-shm",
  "docker0",
  "ens160",
  "ens192",
  "lo",
  "proc",
  "proc-sys-fs-binfmt_misc",
],
}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET series

Get the unique time series data that match the specified criteria

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/series?match[]=<condition>

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{
<labels name>="<name>"}&start=<time stamp>

Example - Request body

{
hostname="clm-HostB"}&start=1596786531

Description

#Consider the following example to understand the series API:

{hostname="clm-HostA", server="web server"} 10
{hostname="clm-HostA", server="web server"} 1
{hostname="clm-HostA", server="web server"} 10
{hostname="clm-HostA", server="web server"} 2
{hostname="clm-HostB", server="web server"} 3455
{hostname="clm-HostB", server="web server"} 321
{hostname="clm-HostB", server="web server"} 32
{hostname="clm-HostB", server="web server"} 34

#In the above example, there is only 1 unique time series matching the hostname criteria and timestamp, and therefore the /series API will display the output as shown below:
#Example Output

{hostname="clm-HostB", server="web server"}

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

If you have inserted labels as shown in the following example, you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

Example:

{
"labels": {
"metricName": "Utilization",
"hostname": "clm-HostA",
"entityId": "CO:clm-HostA:DISKMONITOR:CPU_TOTAL",
"entityTypeId": "DISKMONITOR",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

start

Integer

No

Epoch time (in milliseconds)

If you do not specify the time, the API will get the data for the current timestamp.

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET /series/count

Get the count of unique time series data

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/series/count

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Description

#Consider the following example to understand the series/count API: {hostname="clm-HostA", server="web server"} 10 {hostname="clm-HostA", server="web server"} 1 {hostname="clm-HostA", server="web server"} 10 {hostname="clm-HostA", server="web server"} 2 {hostname="clm-HostB", server="web server"} 3455 {hostname="clm-HostB", server="web server"} 321 {hostname="clm-HostB", server="web server"} 32 {hostname="clm-HostB", server="web server"} 34 #In the above example, there are only 2 unique time series data, and therefore the /series/count API will display the count as 2. {hostname="clm-HostA", server="web server"} {hostname="clm-HostB", server="web server"} #Example Output { "status": "success", "data": [ 2 ], }

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

GET /export?match=<condition>

Get the time series data by specifying the query using labels

Request URL

https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match=<condition>

Consider the following sample examples to understand possible values for <condition>:

Sample examples

https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="data1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={__name__=" total1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="data1111",__name__="total1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="NUK_CPU",source="HM",hostname="<hostname>"}

Request Header

Authorization: Bearer <Jwt_Token>
Payload Encoding: url-encoded key value format

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<labels name>=~"<name>"}

Example - Request body

{__name__=~"tee.*"}

Example: Output

#The API will list the labels, values, and timestamps as shown in the following example
{
"metric": {
"__name__": "teemetric",
VictoriaMetrics_AccountID": "888",
"tag": "dev1",
"tag2": "inst2"
},
"values": [
110,
765
],
"timestamps": [
1589367922000,
1589368322000
]
}


{
"metric": {
"__name__": "teemetric1",
VictoriaMetrics_AccountID": "888",
"tag": "dev2",
"tag2": "inst2"
},
"values": [
110,
765
],
"timestamps": [
1589344422000,
1589128322000
]
}

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

If you have inserted labels as shown in the following example, you can query the timeseries data using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, and source.

Example:

{
"labels": {
"metricName": "Utilization",
"hostname": "clm-HostA",
"entityId": "CO:clm-HostA:DISKMONITOR:CPU_TOTAL",
"entityTypeId": "DISKMONITOR",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

The response Content-Type is application/stream+json.

POST /query

Get the time series data by specifying the timeselector query using labels and timestamp

You can run this API by specifying the API key in the header.

Request URL

https://<HOST_NAME>/metrics-query-service/api/v1.0/query

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<labels name>="<name>"}&time=<time stamp>

Example - Request body

{__name__=\"Utilization\",hostname=\"prometheus-k8s-0\",entityTypeId=\"K8S_POD_CPU\"}&time=1596786531

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

For example, if you have inserted the following labels, you can query the timeseries data using any of the labels such as __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

{
"labels": {
"metricName": "Utilization",
"hostname": "prometheus-k8s-0",
"entityId": "CO:prometheus-k8s-0:K8S_POD_CPU:DISK_TOTAL",
"entityTypeId": "K8S_POD_CPU",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

time

Integer

No

Epoch time (in milliseconds)

Note: If you do not specify the time, the API will get the data for the current timestamp.

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

POST /query_range

Get the time series data by specifying the timeselector query using labels and time frame

You can run this API by specifying the API key in the header.

Request URL

https://<HOST_NAME>/metrics-query-service/api/v1.0/query_range

Request Header

Authorization: Bearer <Jwt_Token>
Encoding format: url-encoded key value format

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<labels parameter name>="<name>"}&start=<start time stamp>&end=<end timestamp>

Example - Request body

{__name__="Utilization"}&start=1595230019&end=1595250019

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

Labels defined in your time series database.

If you have inserted labels as shown in the following example, you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

Example:

{
"labels": {
"metricName": "Utilization",
"hostname": "clm-HostA",
"entityId": "CO:clm-HostA:DISKMONITOR:CPU_TOTAL",
"entityTypeId": "DISKMONITOR",
"entityName": "DISK_TOTAL",
"hostType": "server",
"isKpi": true,
"unit": "byte",
"source": "CO"
}

start

Integer

No

Epoch time (in milliseconds)

Note: If you do not specify both the start and end time, the API will get the data for the following time frame: Current time - 5 minutes

end Integer No Epoch time (in milliseconds)

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

POST /labels

Get all the labels from the time series database

Request URL

https://<Host:Port>/metrics-query-service/api/v1.0/labels

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Example: Output

{
"status": "success",
"data": [
  "VictoriaMetrics_AccountID",
  "__name__",
  "deviceId",
  "entityId",
  "entityName",
  "entityTypeId",
  "hostname",
  "isblackout",
  "source"
],
}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

POST series

Get the unique time series data that match the specified criteria

Request URL

https://<HOST_NAME>/metrics-query-service/api/v1.0/series

Request Header

Authorization: Bearer <Jwt_Token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{
hostname="clm-HostB"}&start=1596786531

Example - Request body

#Consider the following example to understand the series API:
{hostname="clm-HostA", server="web server"}  10
{hostname="clm-HostA", server="web server"}  1
{hostname="clm-HostA", server="web server"}  10
{hostname="clm-HostA", server="web server"}  2
 
{hostname="clm-HostB", server="web server"}  3455
{hostname="clm-HostB", server="web server"}  321
{hostname="clm-HostB", server="web server"}  32
{hostname="clm-HostB", server="web server"}  34
 

#Example Output - In the above example, there is only 1 unique time series matching the hostname criteria and timestamp:
{hostname="clm-HostB", server="web server"}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

POST /export?match=<condition>

Get the time series data by specifying the query using labels

You can run this API by specifying the API key in the header.

Request URL

https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match=<condition>

Consider the following sample examples to understand possible values for <condition>:

Sample examples

https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="data1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={__name__=" total1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="data1111",__name__="total1111"}
https://<HOST_NAME>/metrics-query-service/api/v1.0/export?match[]={entityName="NUK_CPU",source="HM",hostname="<hostname>"}

Curl sample example

curl -X POST 'https://$<HOST_NAME>/metrics-query-service/api/v1.0/export' -d 'match[]=<TIMESERIES_SELECTOR_QUERY>' -H 'Authorization: Bearer <JWT_TOKEN>'

Request Header

Authorization: Bearer <Jwt_Token>
Payload Encoding: url-encoded key value format

For instructions on obtaining the JWT token, see Access and authentication for the REST API. .

Syntax - Request body

{<label name>=~"<name>"}

Example - Request body

{__name__=~"tee.*"}

Parameter Name Value Type Mandatory Description

<labels name>

String

Yes

#The API will list the labels, values, and timestamps as shown in the following example
{
"metric": {
"__name__": "teemetric",
VictoriaMetrics_AccountID": "888",
"tag": "dev1",
"tag2": "inst2"
},
"values": [
110,
765
],
"timestamps": [
1589367922000,
1589368322000
]
}


{
"metric": {
"__name__": "teemetric1",
VictoriaMetrics_AccountID": "888",
"tag": "dev2",
"tag2": "inst2"
},
"values": [
110,
765
],
"timestamps": [
1589344422000,
1589128322000
]
}

Response codes:

200 (OK): Successful response
401 (Unauthorized): Unsuccessful response

The response Content-Type is application/stream+json.

Performing metric operations with the REST API

Metric Ingestion

Metric Query

Comments