...

1. NMIS collects statistics during polling and stores the data as timeseries in RRD files. 
2. NMIS9 also adds the latest values for certain metrics into the MongoDB nodes database.
   1. http://poller-nine.opmantek.com/omk/opCharts/v2/nodes/7949befd-c70e-4921-ad52-ced66489783b
   The Common-stats.nmis definitions control how the polled values are interpreted and how the value is stored in the Nodes MongoDB; either as it's dervied_data or data section.  
   1. Which metrics are stored and where they are stored is defined in Common-stats.nmis.
   2.  Common-stats.nmis definitions controls what metrics are stored in "data" section of the Node from the DEF statements.
   3. Common-stats.nmis can also calculate new values from other data the results are found in the "dervied_data" section of the node's MongoDB database entrye.  This derived_data is the Results of the PRINT statements - so the line which is printed by the statement.
   1. The data and derived data from Common-stats.nmis is
   2. The Common-stats.nmis controls how we "normalise" polled data into metrics which are common to all device types.  For example "cpuLoad" is normalised to a value between 0 and 100, this represents how much CPU has been used in each poll cycle.  This might have come from one device as "5 minute Avg Busy percentage" and need no conversion but might have been calculated from "Idle seconds" on another using the formula cpuLoad is (($r / 300) * 100)
3. opCharts reads the latest values from mongoDB under the nodes 's relevant "data_section" and "derived_data" for each node based on what is defined in the TopN components json document.
4. opCharts finds the Top N entries for that normalised metric and displays them
5. When a user views the TopN page, opCharts loads all components tagged with topn, and puts them into a dashboard which is dynamically created and presented
   1. If a TopN component is added to a user defined dashboard the specific components component is searched for and included in the dashboard

Understanding the TopN component document

Below is the definition for CPU Load TopN.   Note this is looking for a Statistic named cpuLoad and it looks for it in the derived_data section of the nodes MongoDB database entry.   This means to have this TopN work for your node there must be a PRINT line in Common-stats.nmis which returns "cpuLoad" calculated / normalised from that nodes CPU statistics.  See next section for more information on calculating.

The items y

// VERSION=2.46.0
{
  "name": "TopN CPU Load",
  "tags": [ "topn" ],
  "ep_template_file": "charts/topn/topn_table_component",
  "ep_configuration_file" : "charts/topn/topn_table_component_configuration",
  "options": {
    "titleText": "TopN CPU Load",
    "limit" : 10,
    "show_element": 0,
    "show_sparkline": 0,
    "show_value": 1
  },
  "order": 1,
  "parameters": {
    "topn_key": "cpuLoad",
    "data_section": "derived_data",
  },
  "type": "ep_template"
}

Have device Metrics appear in current TopN

...

First find the name of the normalised metric from the relevant component as abive.  If this is a new TopN then select a name for the new TopN metric type.

The document we saw in the previous section was fro cpuLoad.  Some examples of how cpuLoad is calculated for different Models with propriertary cpu statistics are here:

Net-SNMP (hr resources MIB)

'hrsmpcpu' => [
'DEF:hrCpuLoad=$database:hrCpuLoad:MAX',
'PRINT:hrCpuLoad:AVERAGE:hrCpuLoad=%1.2lf',
'PRINT:hrCpuLoad:AVERAGE:cpuLoad=%1.2lf'
],

Some Types of Cisco Router 

'cpuUtil' => [
'DEF:cpuUtil=$database:cpuUtil:AVERAGE',
'PRINT:cpuUtil:AVERAGE:cpuUtil=%1.2lf',
'PRINT:cpuUtil:AVERAGE:cpuLoad=%1.2lf',
],

or with a calculation before hand to convert some other metric style to a normalised value.  This shows converting Idle CPU seconds into a percentage busy over 5 minutes and then using that provide cpuLoad. 

'CDEF:avgBusy5= 300,idleSecs,-,300/,100,*',

'PRINT:avgBusy5:AVERAGE:cpuLoad=%1.2lf',

Add a new Table for a new type of metric

...

{
  "name": "TopN NEW THING", # set a new name here
  "tags": [ "topn" ], # leave this
  "ep_template_file": "charts/topn/topn_table_component", #leave this
  "ep_configuration_file" : "charts/topn/topn_table_component_configuration", # leave this
  "options": {
    "titleText": "TopN NEW THING", # set the component title here
    "limit" : 10, # set how many to show here
    "show_element": 0, 
    "show_sparkline": 1 , # 0 for no sparkline, 1 for sparkline
    "show_value": 1, # 0 to not show the value, 1 to show the value
  },
  "order": 1, # order the new TopN table will appear in the TopN list, see the others to get a total ordering
  "parameters": {
    "topn_idkey": "cpuLoadsomeNewThing", # theThe fieldvariable theor TopNPrint isstatement using,return this will be the same as the filename outputted by nmis_topn_export, and also the same as the "data" attribute in the opcharts_topn_properties that was addedfrom Common-stats.nmis
    "data_section": "derived_data",  # derived_data if the key comes from PRINT or data if the key comes from DEF or CDEF.
  },
  "type": "ep_template" # leave this
}

...