This documentation supports an earlier version of BMC Helix Operations Management.

To view the documentation for the latest version, select 23.2 from the Product version picker.

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 Open link

Metric Ingestion

POST /insert


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. Open link

Important

The request payload for this endpoint is case-sensitive.

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

Parameter NameValue TypeMandatoryDescription

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.
    Notes:
    • The metricName is stored as __name__ label in the timeseries database.
    • All ASCII letters and digits, as well as underscores and colons are supported. The parameter must match the regex [a-zA-Z_:][a-zA-Z0-9_:]*. No other special character is supported. The colons are reserved for user-defined recording rules and should not be used by exporters or direct instrumentation.
  • 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:

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

POST  /prometheus

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

 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. Open link

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. Open link

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


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


Syntax - Request body
{
"devices": [
{
"hostname": "<hostname>",
"source": "<source name>"
}
]
}
Example - Request body
{
"devices": [
{
"hostname": "clm-HostA",
"source": "co"
}
]
}

Parameter NameValue TypeMandatoryDescription

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:

  • 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.

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. Open link

GET  /query?query=<query>


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. Open link

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

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

Parameter NameValue TypeMandatoryDescription

query

StringYes

Specify a query to retrieve the time series data. you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

query={hostname="<host name>", hostType="<host type>"}

time

IntegerNo

Epoch time (in seconds)

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>


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. Open link

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

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

Parameter NameValue TypeMandatoryDescription

query

StringYes

Specify a query to retrieve the time series data. you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

query={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endInteger
NoEpoch time (in seconds)
stepIntegerInteger

Step width in duration format or float number of seconds to resolve the query.

The default value is 5 minutes.

Response codes:

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

GET  /labels


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. Open link

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

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

Parameter NameValue TypeMandatoryDescription

match[]

StringYes

Specify a match condition to retrieve the time series data. You can specify the condition by using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

match[]={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endInteger
NoEpoch time (in seconds)

Response codes:

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

GET  /label/<label_name>/values


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. Open link

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


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. Open link

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

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

Parameter NameValue TypeMandatoryDescription

match[]

StringYes

Specify a match condition to retrieve the time series data. You can specify the condition by using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

match[]={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endInteger
NoEpoch time (in seconds)
stepIntegerNo

Step width in duration format or float number of seconds to resolve the query.

The default value is 5 minutes.

Response codes:

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

GET  /series/count


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. Open link


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>


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. 

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. Open link

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

Parameter NameValue TypeMandatoryDescription

match[]

StringYes

Specify a match condition to retrieve the time series data. You can specify the condition by using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

match[]={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endInteger
NoEpoch time (in seconds)

Response codes:

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

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

POST  /query

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. Open link

Example - Request body

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

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

Parameter NameValue TypeMandatoryDescription

query

StringYes

Specify a query to retrieve the time series data. you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

query={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endIntegerNoEpoch time (in seconds)

Response codes:

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

POST  /query_range

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. Open link

Example - Request body

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

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

Parameter NameValue TypeMandatoryDescription

query

StringYes

Specify a query to retrieve the time series data. you can query the time series using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

query={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endIntegerNoEpoch time (in seconds)
stepIntegerNo

Step width in duration format or float number of seconds to resolve the query.

The default value is 5 minutes.

Response codes:

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

POST  /labels


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. Open link


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

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. Open link

Example - Request body

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

Parameter NameValue TypeMandatoryDescription

match[]

StringYes

Specify a match condition to retrieve the time series data. You can specify the condition by using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

match[]={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endIntegerNoEpoch time (in seconds)
stepIntegerNo

Step width in duration format or float number of seconds to resolve the query.

The default value is 5 minutes.

Response codes:

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

POST  /export

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

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. Open link

Parameter NameValue TypeMandatoryDescription

match[]

StringYes

Specify a match condition to retrieve the time series data. You can specify the condition by using any of the labels such as, __name__, hostname, entityId, entityTypeId, entityName, hostType, isKpi, unit, source, etc.

For example,

match[]={hostname="<host name>", hostType="<host type>"}

start

IntegerNo

Epoch time (in seconds)

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

endIntegerNoEpoch time (in seconds)
Response codes:

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

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


Was this page helpful? Yes No Submitting... Thank you

Comments