Assumptions:
- installed opCharts
Overview
opCharts has dashboards built into the heart of it's engine. Dashboards have the ability to display components, components can load data from many different sources and display it as a graph/table/pie/chart/etc. Right now only graphs are supported.
opCharts runs in 2 modes. Standalone and not-standalone (NMIS attached).
Operational mode (standalone or not)
Not-Standalone
When opCharts is not in standalone mode 'opcharts_running_standalone' => 'false', opCharts will be linked to NMIS and the index page will show a node search and a default dashboard (if the user has chosen one). In this mode there are no custom opcharts users or customers. Although the menu will allow the user to create them they will not be used. All users are loaded from the NMIS configuration as well as their privilege mode.
Node search: the search box for nodes will search by the ip address, node name or group name. Tokens are separated by spaces,-,_,etc, and the search is currently only starting from the beginning of a token.
Standalone
When opCharts is in standalone mode, no connection to NMIS is made or attempted. The index page will show a list of dashboards the user is able to view. If the user sets one of these dashboards as their default the index page will display that dashboard in the place of the list of dashboards. If the administrator would like to set a default dashboard for the customer that can be done. See default_for in the Dashboards seciton.
Data Sources
Non-Standalone
In non standalone mode the data sources specified are currently ignored. All data is taken from the NMIS configuration which is specified in conf/opCommon.nmis.
Standalone
/usr/local/omk/conf/data_sets.json defines the data sources that the system will make available to the charts. Currently only SQL data sources will work. The default configuration ships with examples for MSSQL and MySQL servers. The layout of a data source looks like this:
{
"name" : "mssql_example", # name used to access this data source in charts.json
"type" : "sql", # fixed, no other types are currently available
"data_models" : [ "sql_query" ], # also fixed.
"parameters" : {
"scheme" : "dbi", # fixed
"driver" : "ODBC:DRIVER=FreeTDS", # dbi options that have been installed are available, only MSSQL and MySQL are tested
"host" : "mani.opmantek.com", # SQL server host/ip
"port" : "1433", # port SQL can be found on
"database_name" : "testdb", # database to pull data from
"username" : "sa", # username
"password" : "password" #password
}
},
The name specified for your data source will be used in other configuration files to access the data from this data source.
Dashboards
Dashboards can be created and set as the default for many different views of the system (depending on standalone mode the options to do this differ).
- defined application wide (not stored per user)
- names are unique, cannot be changed after creation (because they are used to link into other places, like default dashboards
- permissions per dashboard define what roles can view the specific dashboard
- care should to be taken to ensure that a dashboard that is visible to a customer does not contain graphs that the customer should not see (no permissions exist for charts)
- allows admin to adjust if specific dashboards should override auto generated dashboards
- if a dashboard is deleted which is also set to a users default dashboard the user will just see the regular index page because the one picked cannot be found.
default_for
Standalone mode:
Specifying a dashboard with permissions checked for only Customer and a default for of "index_opCharts" will make that dashboard appear in the users index view. Same goes for operator permissions and administrator permissions. The same dashboard can be used for more than one role if both roles are selected.
Non-Standalone mode:
When opCharts is linked to NMIS it displays the information available from the model of the node, all graphs that exist for a node or node resource index are shown. To override these default dashboards to show only the information you prefer, create a dashboard with the charts you would like to show. Then enter the correct default for string. opCharts will search from most-specific default_for to least specific default_for, if nothing is found matching it will display an auto-generated dashboard.
The search is separated into 2 categories:
- Node only
- Node resource / indexed resource
Node Only
The search for node only dashboards goes like this:
"${model_name}",
"default"
In the shipping configuration, a dashboard is defined for "CiscoRouter", so this will display for all nodes that use the CiscoRouter model.
Node Resource / indexed resource
The search for this is more complex but it works the same way:
"${model_name}_${resource_name}_${dataset_name}",
"node_${resource_name}_${dataset_name}",
"${model_name}_${resource_id}_default",
"node_${resource_name}_default",
"${model_name}_resource_default",
"node_resource_default"
Example:
omk/opCharts/nodes/asgard/resources/nodehealth/datasets/MemoryFreeIO
omk/opCharts/nodes/asgard/resources/resource_name/datasets/dataset_name
So dashboards can be set per resource / dataset specifically for a model or for all nodes (in that case use word "node" instead of the model name). The default config ships with an example of this (with no dataset) for all node interfaces which is named "node interface defaults".
Charts
Charts can display several data sets in one place. The data sets can come from different sources if desired, each data set has it's own set of options and parameters. There are also options and parameters for the chart as a whole.
Creating an SQL Chart
SQL charts are not currently supported in the chart creator. To make an SQL chart you will need to edit /usr/local/omk/conf/charts/charts.json. The default configuration comes with several examples for SQL data sets. The layout of an SQL chart is this:
{
"parameters" : {
"time_period" : "time_difference",
"end_date" : "7-Mar-2014 14:03:01",
"start_date" : "7-Mar-2014 13:48:01"
},
"datasets" : [
{
"parameters" : {
"aggregation_function" : 1,
"lineType" : "column",
"query" : "select * from nodes",
"value_column" : "sum",
"axis" : "0",
"groupby" : [
"group_column"
]
},
"data_source" : "local_mysql",
"options" : {
"datasetTitle" : "Groups"
},
"name" : "sqlquery_dataset",
"type" : "sql_query"
}
],
"options" : {
"titleText" : ""
},
"name" : "SQL Test",
"type" : "non-time-chart"
},
Dataset:
Looking at an individual dataset will help us understand:
{
"parameters" : {
"query" : "select * from nodes",
"groupby" : [
"group_column"
],
"aggregation_function" : 1,
"value_column" : "unused",
"lineType" : "column",
"axis" : "0",
},
"data_source" : "local_mysql",
"options" : {
"datasetTitle" : "Groups"
},
"name" : "sqlquery_dataset",
"type" : "sql_query"
}
Breaking this down:
From the data_source "local_mysql", run the "sql_query" that is "select * from nodes", group the result by "group_column" and COUNT the number or rows in each group. Display the results in a column graph on the 0 axis.
query:
The SQL to run. This SQL can contain almost anything you would like.
query subsitutions
Currently supported subsitutions are:
| query token | substituted value |
|---|---|
| user.customer | The customer name of the current user is assigned to, if the user does not have a customer the query can fail. Administrators have an option to set this value in the advanced menu. |
| time.start | unix timestamp of the starting time selected from the advanced menu, default value is 15min before now |
| time.end | unix timestamp of the ending time selected from the advanced menu, default value is now |
For the timestamps the time column being queried may need to be converted into a unix timestamp to make a comparison valid. MySQL's timestamp function is UNIX_TIMESTAMP( timecolumn )
groupby:
If the data returned from the SQL statement needs to be grouped (for summing or counting, works much like SQL GROUP BY) use this field to specify the group, as an array, order matters. This works in tandem with the aggregation function to produce results. Just like in an SQL GROUP BY each column requires a function to aggregate it's result.
value_column:
The column in the dataset to run the aggregation function on. If you are not sure what the column name will be, use SELECT column AS some_unique_name. "some_unique_name" can then be used as the value column
aggregation_function:
PASSTHROUGH => 0, COUNT => 1, SUM => 2, MAX => 3, MIN => 4, AVG => 5
This function should be run on each entry in the "group" to produce one row. The value_column will be read and have this function run on it, unless PASSTHROUGH or COUNT are used. For PASSTHROUGH no grouping or aggregation are done. For COUNT the number of rows in each group is tallied. both PASSTHROUGH or COUNT ignore the value_column setting.
lineType:
column is most likely, other options are available, open the chart creator (go to charts and click new chart), there is a drop down with the options.
name:
this is of little consequence, functionally not used at all right now but a way for you to name the dataset for later recognition.
type:
must be sql_query for the above parameters to work.
Back to the chart
The name is the unique name that identifies this chart when using it elsewhere (like creating a dashboard). What is type for?
type
"type" : "non-time-chart"
"type" : "graph"
2 options exist for this. "non-time-chart" means the data will not be an "over time" graph, but a snapshot of the data at a specific time. This is the most likely candidate for an SQL chart. "graph" is a data over time view, the time base is in unix epoc, the SQL query must return the time column in this format and "time_column" must be specified in the dataset telling it what the column is that holds the time value.
Customising the opCharts GUI
Changing the Blue Login Message
To change the text when logging in from the default of "Authentication required: default credentials are nmis/nm188", change the configuration option in opCommon.nmis, "auth_login_motd" to the required text.
Hiding View in NMIS Link
To hide the "view in nmis" button, change the configuration option in opCommon.nmis, "opcharts_gui_display_view_in_nmis" to false, by default this is true.
Hiding Modules List in Menu Bar
To hide the "Modules" menu item in the menu bar, change the configuration option in opCommon.nmis, "opcharts_gui_display_modules_list" to false, by default this is true.