<img height="1" width="1" style="display:none;" alt="" src="https://px.ads.linkedin.com/collect/?pid=1110556&amp;fmt=gif">
    April 20, 2021

    Using DX Operational Intelligence APIs to Extract AIOps Insights

    by: Nestor Falcon Gonzalez

    Today, more than ever, APIs are connecting apps and systems. They have become the glue of modern architectures, and it is imperative to leverage APIs for agility, flexibility, and ease of use.

    In this blog post, we will cover how to extract data via API from Broadcom’s AIOps platform. The data we can consume via API can be logs, events, devices, metrics, or alarms, but in this post, we will focus on relevant insights produced by the platform via AI/ML.

    The use case we will focus on in this blog post will be: How do I fetch all anomalies related to heap memory for a specific host via API?

    DX Operational Intelligence exposes data and insights from its data lake in several manners:

    • We can use DX Dashboards to consume OOTB reports or easily build new ones.
    • We can also leverage DX Gateway for integration with 3rd party systems via webhooks or ITSM tools. Or, we can choose to get value out of the several query APIs to consume information from the data lake directly.

    Remember, the option you choose will depend on your use case with APIs being the preferred option for custom integrations.

     

    Authentication

    Before invoking the REST APIs we need to get authenticated. The auth endpoint call will produce an authorization token to be used in subsequent calls. Mandatory information for this endpoint is listed below.

    1. Request type and endpoint: POST https://axa.dxi-na1.saas.broadcom.com/ess/security/v1/token
    2. Parameters (form type):
      • Grant_type: Password or Refresh_Token. Note that Auth token will expire after 1800 seconds if not used, hence the “refresh_token” grant type is necessary to refresh existing tokens.
      • Username and Password: Credentials associated with your SaaS account. Only necessary if grant_type is “Password”.
      • Refresh_token: Only used if grant_type is “Refresh”
    3. Authorization: This is the tenant name of your account in base64-encoding

    All this information put in a curl command would be:

    curl --location --request POST 'https://axa.dxi-na1.saas.broadcom.com/ess/security/v1/token?grant_type=Password&username=<username>&password=<password>' \

    --header 'Content-Transfer-Encoding: application/x-www-form-urlencoded' \

    --header 'Authorization: Basic <base64-encoded tenant>'

    The output received is a JSON document that contains several key fields, including “tkn”, the authorization token we will need for subsequent queries as an authorization parameter. Let’s see how.

    We start by building the authorization token for the query APIs. To do that, we must append our tenant name (e.g. MYTENANT) to the token obtained before (e.g. 4c15493c-4abe-45e5-9e14-4d666b52459e) like this:
    {"tkn":"4c15493c-4abe-45e5-9e14-4d666b52459e","t":"MYTENANT"}

    And we need to base64-encode the full string to pass it as an authorization token. After encoding it will look similar to this:

    eyJ0a24iOiIzYmJlZTA2Mi1jOWU5LTRlMTctYTFhMC1iNjM4Yzk4MDc2NTkiLCJ0IjoiQ1NBLUdPTlpBTEVaIn0=

    Now we are ready to use it as Bearer Authorization Header in subsequent calls.

     

    Using DX Operational Intelligence Query APIs

    Query APIs in AIOps need a data type category and data type name as optional parameters to narrow down our results. These two fields are embedded in the URL, for instance:

    https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/<data type category>/<data type name>/_search?

     

    An example of this call with a specific data type category and name is:

    https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/alarms_anomaly/_search?

    But how do we know the available data type names for a category (e.g. alarms_anomaly)?

     

    Let’s illustrate this by example. We want to know all data type names for category equals alarms. Then we need to trigger a GET against:

    https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/datatypes

    Using the Bearer Auth token from the previous section.

    For code lovers, it looks like this via Curl:

    curl --location --request GET 'https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/datatypes' \

    --header 'Authorization: Bearer eyJ0a2....TlpBTEVaIn0='

    And this call will produce all the data type names available for “alarms”. Sample output:

    {

       "category": "alarms",

       "datatypes": [

           "alarms_uim",

           "alarms_spectrum",

           "alarms_anomaly",

           "alarms_ada",

           "alarms_ada"

       ]

    }

    Cool, so now we are making progress. We have the auth token and the data type categories and names.

    Let’s now target our final use case: How do I fetch all anomalies related to heap memory for a specific host via API?

     We know we should target alarms and, more specifically, anomaly alarms. So this gives us the URL to attack:

    .../mdo/v2/aoanalytics/alarms/alarms_anomaly/_search

     So, connecting dots, we just need to launch a GET request against:
    https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/alarms_anomaly/_search

    (Note the data type category set to “alarms” and the data type name set to “alarms_anomaly”) using the Authorization Bearer token obtained in the previous section.

    This will produce a raw list of Anomalies (abnormal value of a metric detected by the platform), and to narrow down the results to heap memory, we can use the query parameter as follows:

    https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/alarms_anomaly/_search?q=(message:*Heap* AND host: muntest001220)&size=10

    Note: we query anomalies containing the keyword “Heap” in the anomaly message and belonging to a specific host. We have also capped the output to a max of 10 hits, and we could further limit the output by using the parameters “timefrom” and “timeto” in ISO8601 format.
    One more time, this request in Curl would be:

    curl --location --request GET 'https://axa.dxi-na1.saas.broadcom.com/mdo/v2/aoanalytics/alarms/alarms_anomaly/_search?q=(message:*Heap*%20AND%20host:%20muntest001220)&size=10' \

    --header 'Authorization: Bearer eyJ0a24iOiJmNDI……iQ1NBLUdPTlpBTEVaIn0='

    The sample output of this request is:

    {

       "took": 1906,

       "timed_out": false,

       "_shards": {

           "total": 19,

           "successful": 19,

           "skipped": 0,

           "failed": 0

       },

       "hits": {

           "total": {

               "value": 13,

               "relation": "eq"

           },

           "max_score": 32.585884,

           "hits": [

               {

                   "_index": "ao_itoa_alarms_anomaly_1",

                   "_type": "_doc",

                   "_id": "7424b19f-..9",

                   "_score": 32.585884,

                   "_source": {

                       "host": "muntest001220",

                       "alarm_name": "Heap Used Percent",

                          … (output trimmed)

     

    Conclusion

    So you have now seen how to consume insights from DX Operational Intelligence programmatically via API. This is a great kick start to orchestrate integrations and leverage the AI/ML-driven data produced by Broadcom’s AIOps platform.

    For advance usage and optional API fields, refer to the official documentation.

    Visit Broadcom Enterprise Academy for more AIOps resources.