TopN (v 4.6.0+)

TopN data from v4.6.0+ is created upon request. By default the system ships with 6 TopN tables, the GUI provides an editor to create, modify and delete. The TopN definitions below are very similar to what was found in the files from earlier versions of opCharts.

Using file ending .json or Content-Type application/json is required, endpoints may return HTML if this is not done.

Authentication is required to access all methods below.

All requests are made under the following base URL:

http[s]://server/omk/opCharts/components/topns/

For clarity the methods below include the base of the URL in the HTTP request line.

TopN document definition

The root of the TopN definition has

Property	Description	Type
_id	Auto-created by database, used to identify document internally	Mongo ObjectId
name	Unique name used to access the document	String
type	should be "topN"	String
data_source_type	should be "topn"	String
parameters	Structure detailed below	Hash/Object
options	structure detailed below	Hash/Object
order	used to define the order of the tables in TopN Favourites, value >= 0	integer
filter	Filter to be applied to nodes before TopN is run, this is not currently documented, it must be used with care as it can have significant performance impacts on the server.	Hash/Object

Parameters Hash/Object

Property

Description

Type

data_section

location data is gathered from, can be "data" or "derived_data"

data: value gathered directly from noce

derived_data: value that has been determined using "stats" calculation

String

topn_key

key within "data_section" that contains the value to run TopN calculation on

data_section data: topn_key can be any value being read and stored as a time-series value, NMIS models determine what these will be

data_section derived_data: topn_key can be any key defined as a 'stat' in NMIS, most are found in Common-stats.nmis

String

Options Hash/Object

Property	Description	Type
limit	the number of TopN values returned for this table by default	integer - 0/1
show_element	internal - used by GUI to decide if the Element column should be shown, does not change TopN Data	integer - 0/1
show_in_favourites	internal - used by backend to decide if table should be displayed in TopN Favourites	boolean
show_sparkline	if true TopN Data will report back the last 12 values gathered for this entry (for 5 minute data is 1h), this appears in the result as the "data" arrray	integer - 0/1
show_value	internal - used by GUI to decide if the value column should be displayed	integer - 0/1
titleText	internal - title text to display at the header of the Table	String

GET topn (fetch list of topn definition documents)

GET /omk/opCharts/components/topns.json

Retrieves the TopN documents available to opCharts. No parameters are accepted.

Successful Response

Returns an array of hashes containing the definitions of all TopN definitions. The data returned will contain extra properties which can be ignored, eg. "current_user_privileges", "rbac_path".

[{
    "_id": "65d2c6c396dd0eba3c5d9b71",
    "data_source_type": "topn",
    "name": "TopN Out Discard Rates",
    "options": {
      "limit": 10,
      "show_element": 1,
      "show_in_favorites": true,
      "show_sparkline": 0,
      "show_value": 1,
      "titleText": "TopN Out Discard Rates"
    },
    "order": 6,
    "parameters": {
      "data_section": "derived_data",
      "topn_key": "ifOutDiscards"
    },
    "type": "topN"
  }]

POST topn (create topn definition)

POST /omk/opCharts/components/topns/

Create a new TopN definition.

PUT topn (update topn definition)

PUT /omk/opCharts/components/topns/<topn document name>

Update an existing TopN definition. This is not a patch, this will fully replace the document.

DELETE topn (delete topn definition)

DELETE /omk/opCharts/components/topns/<topn document name>

DELETE an existing TopN definition.

GET topn data (fetch TopN data)

GET /omk/opCharts/components/topns/<topn document name>/topndata.json[?count=X]

Retrieves the topn data for a specific TopN defintion. Parameter topn document name is required and specifies which topn definithion to run. Also takes a query parameter named count which will limit the results to TopX.

Successful Response

Returns an array of hashes, each hash holds the current value of the resource, the last 12 data points if the definition has it enabled (1h of 5 min data) of the resource along with various other info about the specific resource. The array is in order from #1 topn user to #N topn resource.

[  {
    "data": [],
    "description": "GigabitEthernet0/6",
    "index": "10106",
    "node_name": "node1",
    "node_uuid": "1a9b5afb-68f5-4d59-841c-e71837e22f0a",
    "subconcept": "pkts_hc",
    "topn_data": 235.98
  },
<snip>
]

TopN (v 2.2.2 - v 4.5.10)

TopN data is created after every NMIS collect cycle and represents the top users of each resource type. By default there are 6 topn documents created.

Authentication is required to access all methods below.

API Endpoint

All requests are made under the following base URL:

http[s]://server/omk/opCharts/topn/

For clarity the methods below include the base of the URL in the HTTP request line.

GET topn (fetch list of topn documents)

GET /omk/opCharts/topn/

Retrieves the topn documents available to opCharts. No parameters are accepted.

Successful Response

Returns an array of hashes containing the id's of the TopN documents along with the url they can be accessed from.

[
  {
    "url": "/omk/opCharts/topn/cpuLoad",
    "topn_id": "cpuLoad"
  },
  {
    "url": "/omk/opCharts/topn/ifInErrorRates",
    "topn_id": "ifInErrorRates"
  },
  {
    "url": "/omk/opCharts/topn/ifOutDiscardRates",
    "topn_id": "ifOutDiscardRates"
  },
  {
    "url": "/omk/opCharts/topn/ifOutUtil",
    "topn_id": "ifOutUtil"
  },
  {
    "url": "/omk/opCharts/topn/ifInUtil",
    "topn_id": "ifInUtil"
  },
  {
    "url": "/omk/opCharts/topn/MemoryUsed",
    "topn_id": "MemoryUsed"
  }
]

GET topn document (fetch TopN document)

GET /omk/opCharts/topn/[topn_id][?count=X]

Retrieves the topn document. Parameter topn_id is required and specifies the type of topn document to retrieve (which is generally a Resource). Also takes a query parameter named count which will limit the results to TopX.

Successful Response

Returns an array of hashes, each hash holds the current value of the resource, the last 12 data points (1h of 5 min data) of the resource along with various other info about the specific resource. The array is in order from #1 topn user to #N topn resource.

[
  {
    "chart": "resource_id",
    "display_suffix": "",
    "value": 32.02,
    "data": [
      16.2295279333333,
      58.91759035,
      35.2548943,
      12.14511871,
      34.8192241666667,
      22.7064218466667,
      24.85018748,
      48.7659871666667,
      28.0707958966667,
      11.7892433066667,
      38.6264594666667,
      32.42676128
    ],
    "node": "cupid",
    "element": "cpuLoad",
    "index": "0",
    "resource_id": "systemStats",
    "property": "ssCpuRawIdle"
  },
  {
    "chart": "resource_id",
    "display_suffix": "%",
    "value": "13.02",
    "data": [
      12.04003358,
      10.0483504933333,
      10,
      10,
      10,
      10,
      12.87057157,
      13,
      13,
      13.9743139933333,
      14,
      11.07988942
    ],
    "node": "meatball",
    "element": "cpuLoad",
    "index": "0",
    "resource_id": "nodehealth",
    "property": "cpu"
  },
<snip>
]