Metric REST API

Endpoint URLs

$ROUTE/aiops/api/app/metric-api/v1/metrics

$ROUTE/aiops/api/app/metric-api/v1/metrics

$ROUTE/aiops/api/app/metric-api/v1/forecast

Authentication

The API uses Platform UI (Zen) authentication, so you either need a JWT token or ZenApiKey to be authenticated. The token or key is used to determine whether a user or service ID has access when you use the API.

Error handling

Ingest data

To inject data for metric analysis, you need to first log in to your cluster and authenticate for using APIs:

1. Log in to your cluster and authenticate your admin user credentials for running API commands:

   1. Adjust the project (namespace) for your system:

      NAMESPACE=cp4aiops
      

   2. Get the admin username and set it as an environment variable by running the following command

      USER=$(oc -n $NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 -d)
      

   3. Get the password for your admin username and set it as an environment variable by running the following command:

      PASS=$(oc -n $NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d)
      

   Note: Two methods of authentication are available:

   • JWT Bearer Token

     This token is temporary and lasts about 4 hours.

   • Platform UI (ZenApiKey) API key

     This key remains until deleted.

   For more information about API authentication, see Accessing APIs

2. Set your authentication.

   • If you are using the Platform UI (ZenApiKey) API key option, encode your admin username and API key with Base64 encoding:

     ZENAPIKEY=$(echo "<username>:<API_key>" | base64 -w 0); echo $ZENAPIKEY
     

   • If you are using the JWT Bearer Token option, set the token as an environment variable. The following command uses variables that are set in the previous step:

     TOKEN=$(curl -k -X POST https://$ROUTE/icp4d-api/v1/authorize -H 'Content-Type: application/json' -d "{\"username\": \"$USER\",\"password\": \"$PASS\"}" 2>/dev/null|awk -F'"' '{print $(NF-1)}')
     

3. Run a command to load the training data file. As an example, the following command uses cURL to access the API.

   • By using the route and the Platform UI (ZenApiKey) API key option:

     curl -k -v -X POST "https://${ROUTE}/aiops/api/app/metric-api/v1/metrics" --header 'Content-Type: application/json' --header "Authorization: ZenApiKey ${ZENAPIKEY}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --data @<FILEPATH/FILE>.json
     

     Where <FILEPATH/FILE> is the full path to the JSON file that includes your training data to load.

   • By using the route and the JWT Bearer Token option:

     curl -k -v -X POST "https://${ROUTE}/aiops/api/app/metric-api/v1/metrics" --header 'Content-Type: application/json' --header "Authorization: Bearer ${TOKEN}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --data @<FILEPATH/FILE>.json
     

4. To ensure that data is injected, run a command to return data with the API. As an example, the following command uses cURL to access the API.

   • By using the route and the Platform UI (ZenApiKey) API key option:

     curl -v "https://${ROUTE}/aiops/api/app/metric-api/v1/metrics?resource=MyApp&group=Latency&metric=calls.sum" --header "Authorization: ZenApiKey ${ZENAPIKEY}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --insecure
     

   • By using the route and the JWT Bearer Token option:

     curl -v "https://${ROUTE}/aiops/api/app/metric-api/v1/metrics?resource=MyApp&group=Latency&metric=calls.sum" --header "Authorization: Bearer ${TOKEN}" --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' --insecure
     

JSON schema for metrics data

JSON Payload:

{
    "groups": [
        {
            "timestamp": <timestamp>,
            "resourceID": "<resource ID>",
            "metrics": {
                "<kpi-1>": <value-1>,
                "<kpi-2>": <value-2>,
                ...
                "<kpi-n>": <value-n>
            },
            "attributes": {
                "group": "<metric namespace>",
                "node": "<top-level resource>"
            }
        }
    ]
}

• timestamp - The epoch time in milliseconds (13 digits) or ISO-8601.
• resourceID - The resource that is being measured.
• metrics - A map of metric name to metric value.
• attributes - Anything that helps provide context to the user.
• group - Field that you can use to namespace a metric. For example, "customer1". Therefore, group helps distinguish metrics names.
• node - The top-level resource.

Example JSON Payload:

{
    "groups": [
        {
            "timestamp": "1642516320000",
            "resourceID": "MyApp",
            "metrics": {
              "calls.sum": 476.0,
              "latency.mean": 1.6722689
            },
            "attributes": {
              "group": "Latency",
              "node": "MyApp"
            }
        }
    ]
}

Note: The attributes.group, resourceID, and the metrics (for example, metrics.access-denied) fields, along with the tenantID (part of the header in the HTTP request) make up the unique identifier for a KPI. Therefore, as part of the metric anomaly processing and detection, any data points with different values for these fields are considered as different metrics. For example, consider the following two data points:

{
  "groups": [
    {
      "timestamp": 1634846130000,
      "resourceID": "10.10.10.2",
      "metrics": {
        "access-denied": 14977
      },
      "attributes": {
        "group": "Org1",
        "node": "firewall-1"
      }
    },
    {
      "timestamp": 1634846130000,
      "resourceID": "10.10.10.2",
      "metrics": {
        "access-denied": 379
      },
      "attributes": {
        "group": "Org2",
        "node": "firewall-1"
      }
    }
  ]
}

These two data points have the same timestamp value (1634846130000) and resourceID value (10.10.10.2), but have two different group attribute names (Org1 and Org2). This difference causes the data points to be treated as different metrics.

The JSON metric field for correlating a metric anomaly with an element in a resource group depends on the data source for the corresponding topology data. For example, for topology data that is ingested through an Instana connection, the following matching rule is used for correlation: ${name}:::${uniqueId}. As another example, for topology data that is ingested through a file observer job, the resourceID field is used as the identifier for topology correlation.

Unpegging, accumulator and counter attributes: For metrics that count upwards only from when the system starts, the analytics wants to work on the delta values rather than the raw values.

• To identify which metrics are pegs, accumulators, or counters in metric anomaly detection, set an attribute per metric group, for example: "accumulators":"TotalConnections,SuccessfulLoginCount"
• Alternatively, you can set the attribute to ALL to apply to all metrics, for example: "accumulators":"ALL"

Aggregation attributes: Average is the default aggregation type, except for accumulators, where sum is the default.

• To identify which metrics are to be aggregated with sum in metric anomaly detection, set an attribute per metric group, for example: "sumAggregator":"newConnections,Logins"
• Alternatively, you can set the attribute to ALL to apply to all metrics, for example: "sumAggregator":"ALL"