Metric anomaly detection API

Edit online

Use the metric anomaly detection API to ingest and retrieve metric data. To interact with the metric anomaly detection API, you might use cURL or the Swagger UI.

To complete these actions, you need to generate an API key.

To generate an API key by using the UI, go to Administration > Integration with other systems > API Keys > Generate API Key.

Follow the steps in Working with cURL to learn how to generate the API key and password, and how to interact with the metric anomaly detection API by using the cURL commands. For retrieving and forecasting data, you might also use the Swagger UI by clicking a link similar to:
https://server_name/metrics/api/swagger
Where server_name is the name of the server where Netcool® Operations Insight® is running. The APIs are protected by a username and password. For more information, see Training with local data.

Ingest metric data

The API endpoint that the metric anomaly detection API uses to ingest data is:

https://server_name/metrics/api/1.0/metrics
The metric anomaly detection API accepts metric data in JSON format. The following limitations apply to the file formatting:
  • Resource names cannot be more than 500 characters.
  • Metric names cannot be more than 100 characters.
  • Group names cannot be more than 100 characters.
  • The group attribute is mandatory.
The following JSON schema is used. You can use various tools to verify that your schema is correct.
{
$schema: "http://json-schema.org/draft-04/schema#",
type: "object",
properties: {
	groups: {
		type: "array",
		items: {
			type: "object",
			properties: {
				timestamp: {
					type: "string",
					description: "Time in epoch"
					},
				resourceID: {
					type: "string",
					maxLength: 500,
					minLength: 1,
					description: "Resource Name - max length is 500 characters"
					},
				metrics: {
					type: "object",
					patternProperties: {
						"^[^ ]{1,100}$": {
							type: "number",
							description: "Metric Name - cannot contain white spaces and max length is 100 characters"
							}
						},
					additionalProperties: false,
					minProperties: 1
					},
				attributes: {
					type: "object",
					properties: {
						node: {
						type: "string",
						maxLength: 500,
						minLength: 1,
						description: "Node Name"
							},
					group: {
						type: "string",
						pattern: "^[^ ]+$",
						maxLength: 100,
						minLength: 1,
						description: "Group Name - cannot contain white spaces and max length is 100 characters"
							}
						},
					patternProperties: {
						"^(?!^node|group$)([^ ]){1,100}$": {
							type: "string",
							maxLength: 500,
							minLength: 1,
							description: "Any other attribute name and value can be defined. White space not allowed in the name. Max length is 500 characters"
							}
						},
					additionalProperties: false
					}
				},
			required: ["timestamp",
			"resourceID",
			"metrics"]
			}
		}
	},
required: ["groups"]
}

Example:


{
  "groups": [
	{
		"timestamp": "1480982400000",
		"resourceID": "ResourceId_5:Interface1",
		"metrics": {
			"Metric_1": 2.5292,
			"Metric_2": 0.0110
		},
		"attributes": {
			"group": "group_1",
			"node": "ResourceId_5",
			"interface": "Interface1"		
              }
	},
	{
		"timestamp": "1480982460000",
		"resourceID": "ResourceId_5:Interface1",
		"metrics": {
			"Metric_1": 0.0110,
			"Metric_2": 0.0110
		},
		"attributes": {
			"group": "group_1",
			"node": "ResourceId_5",
			"interface": "Interface1"

		}
	},
	{
		"timestamp": "1480982520000",
		"resourceID": "ResourceId_5:Interface1",
		"metrics": {
			"Metric_1": 0.0110,
			"Metric_2": 21.9515
		},
		"attributes": {
			"group": "group_1",
			"node": "ResourceId_5",
			"interface": "Interface1"

		}
	}
  ]
}

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"

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"

Retrieve metric data

The API endpoint that the metric anomaly detection API uses to retrieve the stored metric and baseline data is:
GET https://server_name/metrics/api/1.0/metrics
To retrieve metric data, run the command:
curl -X GET --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' 'https://server_name/metrics/api/1.0/metrics?resource=ABC001-2&group=DEFMetrics&metric=ResponseTime' -u "<api key>:<api password>" [--insecure]
Where --insecure is only required for nonproduction systems.

For more information about authentication, see Working with cURL.

What to do next

Click Training on metric data to learn how to train on metric data obtained from events on Netcool Operations Insight.