Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Detailed API documentation

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Metric Descriptors

Before submitting any metrics a descriptor for the metric recording must be defined and created. This should be done in cooperation with Mnemonic to ensure that the data the metric records matches the actual need to avoid excess, and to ensure the correct access to create a new descriptor. These Metric Descriptors are objects containing meta information about a type of metric, and describes how to interpret the data stored in the records. It should also be noted that the access functions that a user requires to read/submit metrics for this descriptor is also defined in the descriptor itself.

Below are descriptions of some of the more complex data fields.

ShortNameRequired. Is used as an identifier, an alternative to the numerical identifier,  in Argus and so much be unique to the domain.

Access functions

Read-, write- and admin-

Required. Functions defining a user's access. If you find that you can read the metrics, but not submit new ones, then you likely do not have the correct function assigned to your user.

They are defined and created in Argus, and assigned to a user by an administrator.

These functions are case sensitive.

Time frame size

Required. The expected time frames for the metric, and is used by ElasticSearch to place the metric in the correct bucket.

This is used in conjunction with the TimeFrameSizeUnit field, which can be milliseconds, seconds, minutes, hours, days.

Deduplication function

This is used by ElasticSearch to minimize storage space for when a duplicated record is submitted.

first takes the first record and ignores any other submitted duplicates.

last overwrites the existing record.

none simply submits the record without checking for duplicates. This is the default value.

These functions are case sensitive.

Keys

Required. A list of keys and their associated value type. Key types can be an ip, integer or string

Any submitted metric record for this descriptor must contain these keys, and they are case sensitive. Empty values are not allowed, although an empty string is still permissible for string types.

Key names must be unique per descriptor, even if their types are different.

Note: Should the key list be expanded after creation, any request that are missing keys will have a default value assigned for the missing keys. If the request has more keys, then there must be a match for every key in the descriptor, and any excess is discarded. This is to allow scripts to continue their use until they have been updated. The default values are 0 for integers and 0.0.0.0 for IP keys.

Values

Required. A list of value names and their associated default aggregation function. As keys are always a numerical value, you do not need to define a type. The possible function are sum, avg, min and max. These functions are case sensitive.

The default aggregation function is used by ElasticSearch during aggregation calls that does not explicitly defined how the value should be handled. If not defined in the descriptor, then it defaults to the sum function.

Any submitted metric record for this descriptor must contain these values.

Value names must be unique per descriptor.

Note: Should the value list be expanded after creation, any usage that are missing values will have a 0 assigned for the missing value. This is to allow scripts to continue their use until they have been updated. If the request has more values, then there must be a match for every one in the descriptor, and any excess is discarded.


The keys and values properties are used by to create columns for the metric and used alongside the timestamp can be used to generate a table with the metric's data. To submit data/metric record to a descriptor requires that the given key and value names matches. An example of a metric record using the example keys and values is shown below.

timestampipAddressvlanpackagesframes
01-01-2018 07:0110.10.0.11011050
01-01-2018 08:0110.10.0.11051540
01-01-2018 08:0110.10.0.1101030

Add new descriptor

To add a new descriptor to the database, the descriptor endpoint can be used with a POST operation, along with the descriptor information in a json format. If successful, the response will have an ID generated for that descriptor. The example below shows the minimum information to create a descriptor.

The "defaultAggregationFunction" property is used during an aggregation search, see bottom, unless a function is specified during the search. The different functions are sum, avg, min and max and decides how the value is aggregated.

Code Block
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/descriptor -d '{
  "shortName": "testCustomerMetric2",
  "description": "New test Metric",
  "readFunction": "viewMetric",
  "writeFunction": "submitMetric",
  "adminFunction": "adminMetric",
  "keys": [
    {
      "name": "ipAddress",
      "type": "ip"
    },
    {
      "name": "vlan",
      "type": "integer"
    }
  ],
  "values": [
    {
      "name": "packages",
      "defaultAggregationFunction": "avg"
    },
    {
      "name": "frames"
    }
  ],
  "timeFrameSize": 10
  "timeFrameSizeUnit": minutes 
}'


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Get descriptor using descriptor ID

An existing descriptor can be retrieved using its ID, or short name, and the descriptor endpoint

Code Block
curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/metrics/v1/descriptor/{descriptor ID or short name}


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Search for descriptors

Searches for existing descriptors can either be done simply by using a GET operation on the /descriptor endpoint, using any or all the parameters given: argus domain, customer, keywords (set), limit, and offset.

Alternatively a POST operation to the search endpoint can be done and using a json object to communicate the search criterias. This json can take the same values as the GET operation, with an example of some of them below.

Code Block
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/descriptor/search -d '{ 
	"keywords": ["test"]
	"keywordMatchStrategy": "any",
	"keywordFieldStrategy": [
    	"shortName"
  	],
}'


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Update descriptor

The descriptor can be updated using a PUT request to the specific descriptor endpoint, along with the domain as a parameter and a json object. Most attributes of the descriptor can be changed such as adding or removing keys or values. The exceptions are its ID, customer and domain.

When a descriptor is changed, metrics that has already been submitted will not be invalidated and can still be retrieved through the API. Any new metrics will need to conform to the changes in the descriptor.

Code Block
titleAdd additonal key and set new timeframe
curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/descriptor/{descriptor ID or short name} -d '{   
	"timeFrameSize": 2000,
	"addKeys": [{
      "name": "ipAddressV2",
      "type": "ip"
    }]
}'


Code Block
titleRemove key and set new description
curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/descriptor/{descriptor ID or short name} -d '{  
	"description": "New description for the metric.",
	"removeKeys": [ "ipAddressV2" ]
}'


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Delete descriptor

A descriptor can be deleted by using a DELETE operation on the specific descriptor endpoint.

Any metrics that has been submitted under the descriptor will not be deleted from ElasticSearch, but will no longer be possible to retrieve using the API. To completely remove the metrics, it is necessary to do so through ES directly.

Code Block
curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/metrics/v1/descriptor/{descriptor ID or short name}


Metrics

Once an appropriate descriptor has been created, the metric recordings can be submitted to its corresponding endpoints using the descriptor's ID in the path.

Submit metric

Metric records can be submitted using a POST operation on the specific metric endpoint, using a json file that contains one or multiple records. Its important that each of these record objects contains a timestamp and the exact same keys and values as defined in the descriptor or it will be considered invalid. There is also the option to ignore these invalid metrics by setting the property 'ignoreOnFailed' on the top level of the json.

It should be noted that metrics requires a customer owner, and if none is given it defaults to the user's current customer. The exception for this is global metrics, for which the customer field should be left blank for both submission, search and aggregation.

Code Block
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID or short name} -d '{
  "records": [
    {
      "timestamp": 10000,
      "keys": {
        "ipAddress": "10.10.0.1",
        "vlan": "101"
      },
      "values": {
        "packages": 5,
        "frames": 10
      }
    }
  ]
}'


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Search metrics

The submitted metrics can be searched through for specific time frames using a POST operation on the search endpoint for the specific metric descriptor.  A json object encapsulates the search request, which only requires the start- and end- timestamps for the time frame searched. The search can be refined by expanding the json with specific key values to search for, searching across multiple customer's records or adding additional criterias for the data to be included or excluded in the result.

Default values for the timestamps are 0, and 'now' respectively for start and end timestamp.

Additional properties for the json can be added to help sort the result by grouping different keys together, set subcriterias, specify customers, or even whether the metrics should be aggregated across multiple customers.

Like most Mnemonic search API's the request can take limit and offset values, but the implementation is constrained by the Elasticsearch search window that allows for a maximum of ten thousand results and no pagination beyond this. As such the maximum limit is 10000, and the combined total of limit and offset can not exceed 10000 either.  A limit of 0 is considered 'unlimited', but if the total hits for the search criteria would be more than 10000 an error is thrown, asking you to narrow your search.

Search for partial key values, wildcards, scrolling or streaming are not supported yet.

Code Block
titleSpecifying keys
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID or short name}/search -d '{
	"startTimestamp": 0,
	"endTimestamp": 1000000,
	"keys": {
    	"ipAddress": "10.10.0.1"
	}
}'


Code Block
titleSearching the records of multiple customers
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID or short name}/search -d '{
	"startTimestamp": 0,
	"endTimestamp": 1000000,
	"customer": [
    	"mnemonic", "notmnemonic"
	]
}'


Code Block
titleAdding subcriterias to search
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID or short name}/search -d '{
	"startTimestamp": 0,
	"endTimestamp": 1000000,
	"subCriteria": [
    {
      "customer": [
        "mnemonic"
      ],
      "keys": {
        "ipAddress": "10.10.0.1"
      },
      "required": true
    }
  ]
}'


You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.

Aggregate metrics

An aggregation search of metric data can be done by using a POST operation on the aggregation endpoint for the specific metric descriptor, with a json object to encapsulate the aggregation search. An aggregation is much like a search, it requires the start- and end- timestamps, and you can add subcriterias or search across multiple customers. The difference is that it requires one or more value property that is to be aggregated, with an optional aggregation function which if missing will just be the default function given when creating the descriptor. Additional options is to specify the time resolution for the aggregation points,  days, hours, seconds or milliseconds, sorting the results together by  keys, and if you want the aggreagion to be done across multiple customers or not.

Default values for the timestamps are 0, and 'now' respectively for start and end timestamp.

Aggregation using partial key values or wildcards are not supported yet.

Code Block
titleSpecifying the aggregation function and grouping the result
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID/shortName}/aggregate -d '{
	"values": [{
		"name": "packages",
		"aggregationFunction": "min"			  
    }],
	"groupBy": [ "vlan" ],
	"startTimestamp": 0,
	"endTimestamp": 100000
}'


Code Block
titleSetting the time resolution
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/metrics/v1/metric/{descriptor ID/shortName}/aggregate -d '{
	"values": [{
		"name": "packages"		  
    }],
	"resolution": 2,
	"resolutionUnit": "day",
	"startTimestamp": 0,
	"endTimestamp": 100000
}'



You can check the swagger documentation for a more detailed description of the endpoint and the values that can be used in the Json object.






Table of Contents