TopN Tables (opCharts v4.6+)

Manage create, read, update and delete of TopN Table definitions.

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.

API Endpoint - omk/opCharts/components/topns

TopN Table definition

The root of the TopN definition has

Property	Description	Type

Property	Description	Type
`_id`	Auto-created by database, used to identify document internally	Mongo ObjectId
`name`	Unique name used to identify and access the TopN table definition	String
`type`	should be "topN"	String
`data_source_type`	should be "topn"	String



`parameters.data_section`	Where the data for the TopN Favourites is gathered from, can be `data` or `derived_data` data: value gathered directly from node derived_data: value that has been determined using "stats" calculation	`data` or `derived_data`
`parameters.topn_key`	key within "data_section" that contains the value to run TopN calculation on When 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. When data_section='derived_data': topn_key can be any key defined as a 'stat' in NMIS, most are found in Common-stats.nmis	eg `ifOutDiscards`

`options.limit`	the number of TopN values returned for this table by default	integer - 0/1
`options.show_element`	internal - used by GUI to decide if the Element column should be shown, does not change TopN Data	integer - 0/1
`options.show_in_favourites`	internal - used by backend to decide if table should be displayed in TopN Favourites	boolean
`options.show_sparkline`	if true, TopN Favourites will display a sparkline graph for each row in the TopN. 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
`options.show_value`	internal - used by GUI to decide if the value column should be displayed	integer - 0/1
`options.titleText`	internal - title text to display at the header of the Table	String

`order`	used to define the order of the TopN tables displayed 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
filter.nodes	TODO

GET topns (fetch list of topn definition documents)

GET /omk/opCharts/components/topns.json

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

payload

queryParams = {
	page: 1,
	per_page: 25,
	sort_by: "name",
	order: "asc",
	fields_hash: {
		"name": 1,
		"parameters.topn_key": 1,
		"order": 1,
		"options.show_in_favorites": 1,
		"edited_by": 1,
	"edited_at": 1
	}
};

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 topns (create topn definition)

POST /omk/opCharts/components/topns/

body:

payload

{ submitData:
    {
		"options" : {
			"limit" : 10,
			sort: "desc",
			titleText: "Test Response TopN",
			show_in_favorites: true,
			show_value: true,
			show_element: true,
			show_sparkline: true
		},
		type: "topN",
		parameters: {
			data_section: "derived_data",
			topn_key: "response"
		},
		name: "Response TopN Test",
		order: 0,
		addFilter: false,
		filter: {
			catchall: {
				data: {
					group: "",
					roleType: "",
					nodestatus: "",
					nodeType: "",
					nodeVendor: ""
				}
			}
		}
	}
}

Create a new TopN definition.

PUT topns (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.

PUT call payload

options: {
	limit: 10,
	sort: "desc",
	show_element: true,
	show_in_favorites: true,
	show_sparkline: true,
	show_value: true,
	titleText: "Modified TopN Test"
	},
	type: "topN",
	parameters: {
	data_section: "derived_data",
	topn_key: "diskHealth" // Changed from 'response' to 'diskHealth'
	},
	name: <topn document name>,
	order: 0,
	addFilter: true,
	filter: {
		catchall: {
			data: {
			group: "DataCenter",
			nodeType: "",
			nodeVendor: "",
			nodestatus: "",
			roleType: ""
		}
	}
}

DELETE topns (delete topn definition)

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

DELETE an existing TopN definition.

API Endpoint - omk/opCharts/components/topns/name/topndata

GET topndata (fetch TopN data)

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

Retrieves the topn data for a specific TopN defintion. This is the data that is displayed in the TopN Favourites GUI. Parameter topn name is required and specifies which topn to get the data for. Also takes a query parameter named count which will limit the results to the top X results.

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>


]

topndata definition

Array of topndata items

Property	Description	Type

Property	Description	Type
`node_name`		Mongo ObjectId
`node_uuid`	Unique name used to identify and access the TopN table definition	String
`description`	should be "topN"	String
subconcept	should be "topn"	String
topn_data
data

For a Top Interface In Discards on the TopN Favourites that displays

The request is

https://example.com/omk/opCharts/components/topns/top_test_discardProc/topndata.json

[
    {
        "data": {
            "1773119334.89388": 33.08,
            "1773119620.93404": 33.09,
            "1773119906.86084": 33.08,
            "1773120192.60385": 33.07,
            "1773120478.43032": 33.07,
            "1773120764.76585": 33.06,
            "1773121050.54823": 33.08,
            "1773121336.98068": 33.08,
            "1773121622.67874": 32.99,
            "1773121908.714": 32.9,
            "1773122194.50769": 32.89,
            "1773122480.35696": 32.97
        },
        "data_section": "derived_data",
        "description": "bond0",
        "index": "1",
        "inventory_id": "68f97274387fb8f0acad5916",
        "latest_data_id": "68f97286387fb8f0acad70b5",
        "node_name": "deimos-cimc",
        "node_uuid": "4333eeb5-2297-4a2c-b50f-d45a6ae2f867",
        "subconcept": "pkts_hc",
        "topn_data": 32.97,
        "topn_key": "ifInDiscardsProc"
    },
    {
        "data": {
            "1773119692.36081": 0.87,
            "1773119978.29767": 0.9,
            "1773120264.26194": 1.05,
            "1773120560.39605": 1.05,
            "1773120580.36646": 1.05,
            "1773120866.89793": 1.03,
            "1773121153.13623": 0.95,
            "1773121439.04066": 0.9,
            "1773121725.02954": 0.93,
            "1773122010.94136": 0.98,
            "1773122296.64879": 1,
            "1773122582.83021": 0.93
        },
        "data_section": "derived_data",
        "description": "ens160",
        "index": 2,
        "inventory_id": "641abb28da587f637423f9da",
        "latest_data_id": "6424e2f7da587f637498d65d",
        "node_name": "demo",
        "node_uuid": "f4225a19-d084-49d6-ae93-76a6e7cc8ba0",
        "subconcept": "pkts_hc",
        "topn_data": 0.93,
        "topn_key": "ifInDiscardsProc"
    },
    {
        "data": {
            "1773119304.28537": 0.56,
            "1773119590.31091": 0.52,
            "1773119876.22609": 0.56,
            "1773120161.7381": 0.65,
            "1773120447.82364": 0.69,
            "1773120734.08737": 0.66,
            "1773121019.95713": 0.61,
            "1773121306.45": 0.6,
            "1773121591.98112": 0.63,
            "1773121878.01666": 0.67,
            "1773122163.96428": 0.69,
            "1773122449.73004": 0.66
        },
        "data_section": "derived_data",
        "description": "vnet0",
        "index": 3,
        "inventory_id": "641a8d9bda587f6374cd3ae3",
        "latest_data_id": "641a8ec1da587f6374d045e4",
        "node_name": "vrouter_host",
        "node_uuid": "58f4bd9f-a9c1-4507-8bdf-30873d9a16b5",
        "subconcept": "pkts_hc",
        "topn_data": 0.66,
        "topn_key": "ifInDiscardsProc"
    },

topn (opCharts v2.2.2 - v4.5)

Before TopN Tables was added so you could create your own TopN for any data in opCharts, this was the API in use.

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

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

opCharts TopN API

TopN Tables (opCharts v4.6+)

API Endpoint - omk/opCharts/components/topns

TopN Table definition

GET topns (fetch list of topn definition documents)

payload

Successful Response

POST topns (create topn definition)

payload

PUT topns (update topn definition)

PUT call payload

DELETE topns (delete topn definition)

API Endpoint - omk/opCharts/components/topns/name/topndata

GET topndata (fetch TopN data)

Successful Response

topndata definition

topn (opCharts v2.2.2 - v4.5)

API Endpoint - topn

GET topn (fetch list of topn documents)

Successful Response

GET topn document (fetch TopN document)

Successful Response

See Also