Introduction

Each TopN table is really just a component in a dashboard, components are defined in json documents.   opCharts ships the Default components in omk/lib/json/opCharts/components.d/.   User defined components are loaded from omk/conf/components.d, and are loaded last so default components are overridden, if desired, by creating new versions in the User defined folder.  

opCharts 4 takes several steps to generate TopN data and display it (these are different and simpler than with opCharts3).   Understanding these steps will make the process of adding a new TopN table make more sense.

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
3. 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. 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)
4. opCharts reads the latest values from mongoDB under the nodes relevant data_section
5. opCharts finds the Top N entries for that normalised metric and displays them
6. 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 is searched for and included in the dashboard

Understanding the TopN component document

Have device Metrics appear in current TopN

If you have written a new device model or a current model does not show in one of the current TopN categories you may need to update Common-stats.nmis to include the metrics you collect as a Normalised metric.  Also, if you wanted to create a new TopN Metric you would need to make sure this new metric type appears in Common-stats.nmis

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

Add a new Table for a new type of metric

The easiest way to get started is to copy an existing topn component file from omk/lib/json/opCharts/components.d/topn_* into omk/conf/components.d (and rename the file).

Next open the new file and modify it to suite your new TopN data, the changes required are fairly straight forward and are outlined below: 

{
  "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_id": "cpuLoad" # the field the TopN is using, 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 added
  },
  "type": "ep_template" # leave this
}

The new TopN table should now appear in opCharts TopN page and also as an option when adding a component to a dashboard under the opCharts data source.

Last Step

After the previous steps have been completed, make sure the nmis_topn_export.pl script has run, then check the TopN page for the new data.  If there is none, verify the data is being created by checking <omkd_topn> directory for the new json file.  Verify the file has contents, if it does not run the nmis_topn_export.pl in debug and search the output for the new entry field/data.