DX OI - Examples of how to query for Alarms, Metrics and Topology using REST APIs?
Article ID: 206461
Updated On:
Products
Issue/Introduction
How to programmatically query the multiple database alarms, metrics and topology information? What are the REST API available to query for this information?
Environment
DX Platform 20.2
Resolution
Table of Contents
- Query Alarms (ElasticSearch)
- Query Metrics (NASS)
- STEP 1: Select a REST API
- STEP 2: Generate a Tenant token
- STEP 2: Query for Metrics
- a) Body example # 1: List data for all UIM metrics
- b) Body example # 2: List data for metric matching “Total Device Count”
- c) Body example # 3: List data for only “Aggregate CPU Usage pct” metric, past hour, frequency at 10 min
- Query Topology (TAS)
Query Alarms (ElasticSearch)
STEP 1: Generate Authentication token
a) Open your REST API Client tool, for example https://www.postman.com/
b) Perform a POST call to generate a token:
- Endpoint: http(s)://<adminui.endpoint>/ess/security/v1/token
- Params tab:
Add grant_type = Password (Note: this is a static value)
Add username and password = <your tenant admin credentials>
- Headers” tab
Add Authorization = Basic <encoded value of your tenant name>
How to generate the "encoded value of your tenant name" ?
- Your tenant name is available from the DX Platform Login prompt or from DX Cluster Management (contact your DX Administrator)
In this example, it is support
- Open https://www.base64encode.org/
- Encode your tenant name
- Copy the encoded value , then click "Send" to generate the authorization token
c) Perform a POST call to refresh the token:
The authentication token (tkn) will expires after 30 minutes, before the expiry the token API should be called again to fetch a new token
- Endpoint: http(s)://<adminui.endpoint>/ess/security/v1/token
- Params tab:
grant_type = Refresh_Token
refresh_token = <refresh token (rtkn) generated in this step>
Remove the username and password paramers
For example:
Go to Params tab, set:
Set grant_type = Refresh_Token
Add refresh_token = <token>
Click Send.
A new refresh token and refresh token will be generated
STEP 2: Generate Authorization token
a) Open https://www.base64encode.org/
b) Enter below line, replace highwith your information and encode the string:
{"tkn":"<authentication token>","<tenant_scope_argument>":"true"}
About:
- authentication token : generated in previous step
- tenant_scope_argument : possible values “t”, “all” and “global” . For more information refer to: https://techdocs.broadcom.com/us/en/ca-enterprise-software/it-operations-management/digital-operational-intelligence/20-2/reference/authentication-and-authorization-of-apis.html#concept.dita_751d69ef83b42918d5634ffc5b35ca57bb2c826b_PasstheAuthorizationDetails
In this example:
{"tkn":"<token>","all":"true"}
IMPORTANT:
Before the 30 minutes, refresh the token as explained in step 1c No additional change should be required for the Authentication token
STEP 3: Query data
Main reference: https://techdocs.broadcom.com/us/en/ca-enterprise-software/it-operations-management/digital-operational-intelligence/20-2/reference/digital-operational-intelligence-query-apis.html
a) List all sources for alarms:
Perform a GET call against : http(s)://<adminui.endpoint>/mdo/v2/aoanalytics/alarms/datatypes/
No Params
No Headers
Set Authorization = Bearer Token <value generated in STEP 2>
b) List Open UIM Alarms for specific date range
Perform a GET call against : http://<adminui.endpoint>/mdo/v2/aoanalytics/alarms/alarms_apm/_search?q=<encoded query string>
About <query string>:
-You can use fields from the indexes to build complex queries, here is an example:
(doc_type_id:itoa_alarms_uim AND status:(NOT CLOSED) AND product:UIM AND (timestamp:[2021-09-21T11:00:17+0000 TO 2021-09-22T11:50:17+0000]))
-You can encode the query string using for example: https://www.urlencoder.org/
Below would be the final URL to query to use to query for all Open UIM Alarms on the given time range:
http://adminui.example.com/mdo/v2/aoanalytics/alarms/alarms_all/_search?q=%28doc_type_id%3Aitoa_alarms_uim%20AND%20status%3A%28NOT%20CLOSED%29%20AND%20product%3AUIM%20AND%20%28timestamp%3A%5B2021-09-22T11%3A00%3A17%2B0000%20TO%202021-09-24T11%3A50%3A17%2B0000%5D%29%29
Query Metrics (NASS)
STEP 1: Select a REST API
You have the below 2 options:
b) /atc/metric/queryMetric :https://techdocs.broadcom.com/us/en/ca-enterprise-software/it-operations-management/application-performance-management/20-2/api-reference/apm-rest-api/QueryMetric-REST-API.html
In this example, we cover examples using option b) queryMetric
STEP 2: Generate a Tenant token
Two options available:
a) From APM: Go to Security > Create a new Token
b) From Cluster Management > Tenant> Create a Tenant Token
STEP 2: Query for Metrics
1. Syntax:
POST http(s)://<apmservices-gateway.endpoint>/atc/metric/queryMetric
Authorization: Bearer Token <tenant token>
2. Examples:
a) Body example # 1: List data for all UIM metrics
{
"querySpecifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)UIM(.*)"
},
"attributeNameSpecifier": {
"op": "ALL"
}
},
"queryRange": {
"endTime": 0,
"rangeSize": 3600,
"frequency": 120
},
"clampSize": 1000
}
OR
{
"size": 10000,
"specifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)UIM(.*)"
},
"attributeNameSpecifier": {
"op": "ALL"
}
}
}
b) Body example # 2: List data for metric matching “Total Device Count”
{
"querySpecifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)UIM(.*)"
},
"attributeNameSpecifier": {
"op": "REGEX",
"pattern": ".*Total Device Count"
}
},
"queryRange": {
"endTime": 0,
"rangeSize": 3600,
"frequency": 120
},
"clampSize": 1000
}
c) Body example # 3: List data for only “Aggregate CPU Usage pct” metric, past hour, frequency at 10 min
{
"querySpecifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)UIM(.*)"
},
"attributeNameSpecifier": {
"op": "REGEX",
"pattern": ".*Aggregate CPU Usage pct.*"
}
},
"queryRange": {
"endTime": 0,
"rangeSize": 3600,
"frequency": 600
},
"clampSize": 1000
}
Result #2: Validation that values reported by REST API matches those reported by DX OI UI:
NOTES:
1) About Range section:
"queryRange": {
"endTime": 0,
"rangeSize": 3600,
"frequency": 120
},
- Range is width of range you want to query. Day is 86400.
- End time is Unix timestamp of right edge of such a range. Zero is special value for current time to make last N minutes query easy. Otherwise just use absolute time.
- Frequency is required aggregation per sample (that interval selection in our metric browser). 120 is two minute interval.
2) About how to read the Metric Values
For example:
[
1633686000, => Timestamp
600, => Interval size
2.73, => Value Min across all data points in the interval
3.1708, => Value Max across all data points in the interval
2.9504, => Value in the interval (depends on aggregation type, but in this case average)
2 => Count is number of samples in interval. It is required to have more precise aggregation.
For example, average response time is used to calculate weight average.
If you had 1000 requests in your app in 15 seconds then the count will be 1000.
Query Topology (TAS)
STEP 1: Generate a Tenant token
Two options available:
a) From APM: Go to Security > Create a new Token
b) From Cluster Management > Tenant> Create a Tenant Token
STEP 2: Query for Topology data
1. Syntax:
POST http(s)://<APMServices Gateway Host>/tas/graph/query
Authorization: Bearer Token <tenant token>
2. Examples:
a) Body example # 1: List all UIM devices
{
"filter": {
"op": "JOIN",
"input": {
"op": "AND",
"input": [
{
"op": "ATTRIBUTE",
"expressions": [
{
"name": "Product",
"values": [
"UIM"
]
}
]
}
]
}
},
"universe": null,
"version": null,
"time": 0,
"stitchingEnabled": true,
"includeStatus": true
}
b) Body example # 2: List all NetOps devices
{
"size": 10000,
"specifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)NetOps\\|CAPM(.*)|(.*)NetOps\\|ADA(.*)|(.*)NetOps\\|NFA(.*)"
},
"attributeNameSpecifier": {
"op": "ALL"
}
}
}
c) Body example # 3: List all APM devices
{
"size": 10000,
"specifier": {
"op": "SPEC",
"sourceNameSpecifier": {
"op": "REGEX",
"pattern": "(.*)APM(.*)"
},
"attributeNameSpecifier": {
"op": "ALL"
}
}
}
Additional Information
Feedback
