This documentation supports the releases of BMC Helix Operations Management up to December 31, 2021.To view the documentation for the latest version, select 23.1 from the Product version picker.

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

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
        }
      ]

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"
}
]
}

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

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

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"}

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
]
}



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


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

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.*"}

Response codes:

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

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


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*