Page tree
Skip to end of metadata
Go to start of metadata

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 sizeRequired. The expected time frames for the metric, given in milliseconds, and is used by ElasticSearch to place the metric in the correct bucket.
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, hostName, integer or string

Any submitted metric record for this descriptor must contain these keys, and they are case sensitive.

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.


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.

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

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

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), keywordField (set), keywordMatchStrategy (deafults to all), 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"
  	],
}'

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.

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

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.

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, and with a json object containing the data. Its important that this object 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'.

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, as such its necessary to explicitly state the 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.

It should be noted that unlike a search without a specific customer, a search without a specific domain will default to the user's domain and not include every domain the user has access to. This is because the search uses a customer's shortname which is unique for each domain.

Search for partial key values or using wildcards are not supported yet.

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


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


Adding 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, as such its necessary to explicitly state the end timestamp.

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

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


Setting 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.



  • No labels