opCharts TopN API

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

PropertyDescriptionType
_idAuto-created by database, used to identify document internallyMongo ObjectId
nameUnique name used to access the documentString
typeshould be "topN"String
data_source_typeshould be "topn"String
parametersStructure detailed belowHash/Object
optionsstructure detailed belowHash/Object
orderused to define the order of the tables in TopN Favourites, value >= 0

integer

filterFilter 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

PropertyDescriptionType
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

PropertyDescriptionType
limitthe number of TopN values returned for this table by defaultinteger - 0/1
show_elementinternal - used by GUI to decide if the Element column should be shown, does not change TopN Datainteger - 0/1
show_in_favouritesinternal - used by backend to decide if table should be displayed in TopN Favouritesboolean
show_sparklineif 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" arrrayinteger - 0/1
show_valueinternal - used by GUI to decide if the value column should be displayedinteger - 0/1
titleTextinternal - title text to display at the header of the TableString

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>
]