Metric operation management endpoints in 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 about obtaining the JWT token, see Access and authentication for the REST API.

Important

  • The request payload for this endpoint is case-sensitive.

  • The following table lists the special characters supported for certain attributes:

    Request attributes

    Supported characters in the attribute value

    hostname

    -

    _

    .















    entityTypeId

    ~

    !

    @

    #

    $

    ^

    &

    *

    ()

    -

    _

    =

    []

    ;

    '

    ?

    .

    entityName

    ~

    !

    @

    #

    $

    ^

    &

    *

    ()

    -

    _

    =

    []

    ;

    '

    ?

    .

  • Characters that are supported for entityName apply to all attributes in labels.
  • When you create third-party instances, you can specify a maximum of 4000 characters in the entityName and entityId.
Request body
#Following is an example of the PATROL Agent metrics data format [
 {
   "labels": {
     "metricName": "<metric name>",
     "hostname": "<hostname>",
     "entityId": "<entity ID>",
     "entityTypeId": "<Name of the entityTypeId>",
     "entityName": "<Name of entity name>",
     "hostType": "<type of host>",
     "isKpi": "<isKpi>",
     "unit": "<unit type>",
     "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
     }
    ]
 }
]
Example - Hierarchical relationship for monitors
[
 {
   "labels": {
     "metricName": "offset",
     "hostname": "clm-pun-microbots77",
     "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-pun-microbots77",
     "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
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType3",
     "entityName": "entitypower1",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower1",
     "parentEntityTypeId": "segmentEntityType2",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType3:entitypower1",
     "instanceName": "power",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType4",
     "entityName": "entityrx1",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower1",
     "parentEntityTypeId": "segmentEntityType3",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType4:entityrx1",
     "instanceName": "rx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType5",
     "entityName": "entitytx1",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower1",
     "parentEntityTypeId": "segmentEntityType3",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType5:entitytx1",
     "instanceName": "tx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType6",
     "entityName": "entitygenerator_fuel1",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower1",
     "parentEntityTypeId": "segmentEntityType2",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType6:entitygenerator_fuel1",
     "instanceName": "generator_fuel_level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType7",
     "entityName": "entitylevel1",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitygenerator_fuel1",
     "parentEntityTypeId": "segmentEntityType6",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType7:entitylevel1",
     "instanceName": "level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "offset",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType8",
     "entityName": "entitytower2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitysegment",
     "parentEntityTypeId": "segmentEntityType1",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType8:entitytower2",
     "instanceName": "tower2",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType9",
     "entityName": "entitypower2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower2",
     "parentEntityTypeId": "segmentEntityType8",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType9:entitypower2",
     "instanceName": "power",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType10",
     "entityName": "entityrx2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower2",
     "parentEntityTypeId": "segmentEntityType9",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType10:entityrx2",
     "instanceName": "rx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType11",
     "entityName": "entitytx2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower2",
     "parentEntityTypeId": "segmentEntityType9",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType11:entitytx2",
     "instanceName": "tx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType12",
     "entityName": "entitygenerator_fuel2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower2",
     "parentEntityTypeId": "segmentEntityType8",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType12:entitygenerator_fuel2",
     "instanceName": "generator_fuel_level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType13",
     "entityName": "entitylevel2",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitygenerator_fuel2",
     "parentEntityTypeId": "segmentEntityType12",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType13:entitylevel2",
     "instanceName": "level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "offset",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType14",
     "entityName": "entitytower3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitysegment",
     "parentEntityTypeId": "segmentEntityType1",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType14:entitytower3",
     "instanceName": "tower3",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType15",
     "entityName": "entitypower3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower3",
     "parentEntityTypeId": "segmentEntityType14",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType15:entitypower3",
     "instanceName": "power",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType16",
     "entityName": "entityrx3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower3",
     "parentEntityTypeId": "segmentEntityType15",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType16:entityrx3",
     "instanceName": "rx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "dbm",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType17",
     "entityName": "entitytx3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitypower3",
     "parentEntityTypeId": "segmentEntityType15",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType17:entitytx3",
     "instanceName": "tx",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType18",
     "entityName": "entitygenerator_fuel3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitytower3",
     "parentEntityTypeId": "segmentEntityType14",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType18:entitygenerator_fuel3",
     "instanceName": "generator_fuel_level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 },
 {
   "labels": {
     "metricName": "Percentage",
     "hostname": "clm-pun-microbots77",
     "source": "nagios",
     "entityTypeId": "segmentEntityType19",
     "entityName": "entitylevel3",
     "hostType": "server",
     "isKpi": "True",
     "unit": "Percent",
     "parentEntityName": "entitygenerator_fuel3",
     "parentEntityTypeId": "segmentEntityType18",
     "entityId": "nagios:clm-pun-microbots77:segmentEntityType19:entitylevel3",
     "instanceName": "level",
     "isDeviceMappingEnabled": "true"
   },
   "samples": [
     {
       "value": 90,
       "timestamp": 1639030067000
     }
    ]
 }
]

Response codes:

  • 202 (Accepted): API request accepted
  • 400 (Bad Request): Unsuccessful response
  • 401 (Unauthorized): Unsuccessful response

POST  /prometheus

Send Prometheus metrics to BMC Helix Operations Management

The following video (2:25) created by BMC Customer Support describes how to send third-party metrics to BMC Helix Operations Management.


icon-play@2x.png https://youtu.be/jjnqIpi-i80

Request URL
https://<Host:Port>/metrics-gateway-service/api/v1.0/prometheus
Request Header
Content-Type : application/x-protobuf
Authorization: Bearer <Jwt_Token>/<apiKey>
Content-Encoding : Snappy

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

Important

We recommend that you use a Prometheus server remote write to ingest the data.

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

  • Node exporter
  • Windows exporter
  • Oracle database exporter
  • Kafka exporter
  • Redis exporter
  • JMX exporter

To learn about the exporters that Prometheus offers, see Exporters and integrations.

Response codes:

  • 202 (Accepted): API request accepted
  • 400 (Bad Request): Unsuccessful response
  • 401 (Unauthorized): Unsuccessful response

Important

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

The /delete API does not support the deletion of devices that are created by using the /prometheus API.

POST /delete

Delete the third-party device details from BMC Helix Operations Management

Use the /delete API to mark third-party devices for deletion. The device instances stay in the Marked for delete state by default for 7 days, after which they are deleted from the system. After 7 days, the device is deleted from the system if all its instances are deleted. If any instance is restored, the device is not deleted.

During the 7 days that a device is marked for deletion, you can restore its instances by using the /insert API.

The device instances are deleted through a scheduler that runs daily at 3:00 A.M. The scheduler discovers all device instances that have been in the Marked for delete state for the past 7 days and deletes those instances.

Contact BMC Support to change the time when the scheduler runs daily or the number of days that the instances stay in the Marked for delete state. 

Important

This API is accessible only to the members of the Administrators group.


Request URL
https://<Host:Port>/metrics-gateway-service/api/v1.0/delete
Request Header
Content-Type: Application/json
Authorization: Bearer <Jwt_Token>

For instructions about 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:

  • 202 (Accepted): API request accepted
  • 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

Important

Make sure that you encode the query parameters and conditions in the endpoint request URL. You can use different tools to encode the URL, for example, Postman.

Use Postman's Encode URI Component option to encode the required portion of the URL.

Encode URL.png

For example,

URL before encoding:

https://<Host:Port>/metrics-query-service/api/v1.0/query?query={entityName="NUK_Memory"}&time=1595226431

URL after encoding:

https://<Host:Port>/metrics-query-service/api/v1.0/query?query=%7BentityName%3D%22NUK_Memory%22%7D%26time%3D1595226431

For more information about encoding URLs, see Create and send API requests in Postman.

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>&time=<time>
Request Header
Authorization: Bearer <Jwt_Token>

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

Look at the following example to understand possible values for <query>:

Query examples
Syntax
query={<Labels name>="<name>"}
Example
query={entityName="NUK_Memory"}

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>&start=<start time stamp>&end=<end timestamp>&step=<step>
Request Header
Authorization: Bearer <Jwt_Token>

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

Look at the following example to understand possible values for <query>:

Query examples
Syntax
query={<labels name>="<name>"}
Example
query={source="Helix"}

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?match[]=<condition>&start=<start time stamp>&end=<end timestamp>
Request Header
Authorization: Bearer <Jwt_Token>

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

Look at the following example to understand possible values for <condition>:

Match condition examples
Syntax
match[]={<labels name>="<name>"}
Example
match[]={__name__="Utilization",entityName="NUK_CPU",hostname="<HOST_NAME>"}
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/<label_name>/values

Get the specified label values from the time series database


Request URL
https://<Host:Port>/metrics-query-service/api/v1.0/label/<label_name>/values
Example request URL: List the entityNames
https://<Host:Port>/metrics-query-service/api/v1.0/label/entityName/values
Request Header
Authorization: Bearer <Jwt_Token>

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

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>&start=<start time stamp>&end=<end timestamp>&step=<step>
Request Header
Authorization: Bearer <Jwt_Token>

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

Look at the following example to understand possible values for <condition>:

Match condition examples
Syntax
match[]={<labels name>="<name>"}
Example
match[]={__name__="Utilization",entityName="NUK_CPU",hostname="<HOST_NAME>"}

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 about 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>&start=<start time stamp>&end=<end timestamp>

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

Important

The queries data must be UTF-8 encoded. 

Match condition examples
Retrieving a single metric
match[]={__name__="Utilization",entityName="NUK_CPU",hostname="<HOST_NAME>"}
Retrieving multiple metrics
match[]={__name__="Utilization|attribute2",entityName="NUK_CPU",hostname="<HOST_NAME1>|<HOST_NAME2>”}

You can use the pipe (|) character to specify multiple metrics. If you don't specify a value for the end parameter, the system considers the current time as the parameter value.

Request Header
Authorization: Bearer <Jwt_Token>
Content-Type: application/x-www-form-urlencoded

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

Example: Output
#The API will list the labels, values, and timestamps as shown in the following example
{
"metric": {
"__name__": "total1037",
"VictoriaMetrics_AccountID": "558679744",
"entityId": "co:HostA.bmc.com:Monitor_abcde1037:data1037",
"entityName": "data1037",
"entityTypeId": "Monitor_abcde1037",
"hostType": "application.lb",
"hostname": "HostA.bmc.com",
"isKpi": "true",
"source": "co",
"unit": "#"
},
"values": [
50
],
"timestamps": [
1675239926000
]
}

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>
Encoding format: url-encoded key value format

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

Example - Request body

Example request body.png

Look at the following example to understand possible values for query:

Query examples
Syntax
query={<labels name>="<name>"}
Example
query={hostname="HostB.bmc.com", source="Helix"}

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 about obtaining the JWT token, see Access and authentication for the REST API.. 

Example - Request body

Example request body.png

Look at the following example to understand possible values for query:

Query examples
Syntax
query={<labels name>="<name>"}
Example
query={hostname="HostB.bmc.com", source="Helix"}

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 about 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>
Encoding format: url-encoded key value format

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

Example - Request body

Example request body post export.png

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

Match condition examples
match[]={entityName="data1111"}
match[]={__name__="total1111"}
match[]={entityName="data1111", __name__="total1111"}
match[]={entityName="NUK_CPU", source="HM", hostname="<hostname>"}

Response codes:

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

POST  /export

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
Request Header
Authorization: Bearer <Jwt_Token>
Content-Type: application/x-www-form-urlencoded

Example - Request body

Example request body post export.png

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

Match condition examples
match[]={entityName="data1111"}
match[]={__name__="total1111"}
match[]={entityName="data1111", __name__="total1111"}
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>'

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

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*