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.

shortName

Required. 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, max and ‘wavg’. 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.

Aggregations using ‘wavg’, or weighted average, also requires a weight, which should be the name of another value in the metric decriptor. This is given by the field ‘valueAsWeight’, and is required when using ‘wavg’.

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:

timestamp	ipAddress	vlan	packages	frames
01-01-2018 07:01	10.10.0.1	101	10	50
01-01-2018 08:01	10.10.0.1	105	15	40
01-01-2018 08:01	10.10.0.1	101	0	30

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.

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"
}'

Tip

| You can check the Swagger API 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

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

Tip

| You can check the Swagger API 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.

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"
    ],
}'

Tip

| You can check the Swagger API 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.

Add 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"
    }]
}'

Remove 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" ]
}'

Tip

| You can check the Swagger API 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.

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