Customizing the Dashboard

Dashboards assemble data from different tabs in the Traffic Sentinel user interface and from queries into a single page. There are multiple strategies for organizing charts into dashboards: a dashboard may be used to capture peformance metrics related to a service and the server and network resources it consumes, or dashboards can be created for different parts of the network.

Choosing a Home Dashboard

The Home>Dashboard page is the first page you see after logging into Traffic Sentinel. The Page selector in the Filter: bar is used to select among the dasbhoard pages that the user has permission to view. The last dashboard page viewed is remembered and will be the first dashboard you see when you next log in.

Building a custom dashboard

Access to the File>REST page is required to create or modify a dashboard (which typically requires admininistrative privileges). The REST API Builder tutorial provides additional information on editing and testing REST API scripts.

A dashboard is a special kind of REST script built to provide data to an HTML5 client running in a web browser.

// description: My First Dashboard
// author: My Name
// date: 1/28/16
// version: 1.0
// authLevel:operator
// clientJS:dashboard-2.0.js
// ttl: 60
// resultFormat: json

include('dashboard-2.0.js');

var trends  = new Trends({columns:2,interval:'last-60min,last'});

// add charts here
trends.addTrafficTopN({chart:'pairs'});
trends.addTrafficTopN({chart:'protocols'});

trends.printResult();

The authLevel setting can be set to guest, operator, or administrator, depending on the group of users that will be allowed to view the dashboard.

The clientJS:dashboard-2.0.js instructs Traffic Sentinel to include the Dashboard 2.0 html, javascript and style sheet components when the dashboard script is accessed. The client makes periodic queries to retreive JSON encoded data to display in the dashboard. The include('dashboard-2.0.js') statement loads the Trends object to help build the queries and return the data in the format that the client expects. The final printResult() runs the queries and return the results.

The easiest way to start is to Copy an existing dashboard that has elements that are close to what you want.

Interface Trend

Interface charts from the Traffic>Trend page:

trends.addInterfaceTrend({
  chart:'bytes',
  interface:'10.0.0.253>24',
  includeStatus: true
});

The interface parameter is required and specifies the switch port to trend. The easiest way to identify the IP address and ifIndex number used to identify a switch port is to navigate to the port using any of the tabs under Traffic. Click on the Agent Details button in the Filter: bar and the Search>Agent/Interface page will show the port id. The includeStatus option colors the heading to reflect the threshold status.

The following chart values are defined:

  • utilization Utilization in / out switch port.
  • bytes Bits/second in/out switch port.
  • frames Frames/second in/out switch port.
  • errors Errors/second in/out switch port.
  • discards Discards/second in/out switch port.

Traffic TopN

Select charts from the Traffic>Top N page:

Either select a pre-defined Top N chart:

trends.addTrafficTopN({chart:'pairs'});

The following chart values are defined:

  • sources Top source addresses
  • destinationsTop destination addresses
  • pairs Top source,destination address pairs
  • protocols Top server ports

Or explicity specify the flow attributes:

trends.addTrafficTopN({
  keys:'sourceaddress,destinationaddress',
  value:'bps',
  title:'Top Pairs'
});

The keys attribute is a comma seperated list of keys that are valid for the traffic database view.

The following value options are defined:

  • bps Bits per second
  • Bps Bytes per second
  • fps Frames per second

Include a where filter to select specific traffic, e.g. where:"ipsource=10.0.0.1"

Hosts Trend

Charts from the Hosts>Trend page:

trends.addHostTrend({chart:'loadavg'});

The follow chart values are defined:

  • loadavg Load averages
  • utilization CPU utilization
  • processes Processes
  • interrupts Interrupts
  • memory Memory utilition
  • swapping Swapping activity
  • paging Paging activity
  • iooperations Read/write operations
  • iobytes Read/write bytes
  • iotime Read/write times
  • networkbytes Network bytes in/out
  • networkpacketsNetwork packets in/out
  • vutilization Virtual machine/container CPU utilization
  • vmemory Virtual machine/container memory utilization
  • viooperations Virtual machine/container read/write operations
  • viobytes Virtual machine/container read/write bytes
  • vnetworkbytes Virtual machine/container network bytes in/out
  • vnetworkpackets Virtual machine/container network packets in/out
  • jvmheap Java virtual machine heap memory size
  • jvmnonheap Java virtual machine non-heap memory size
  • jvmthreads Java virtual machine threads
  • jvmgc Java virtual machine garbage collection
  • jvmfd Java virtual machine open files
  • jvmthreadsstarted Java virtual machine threads started

Include a where filter to select groups or individual hosts, e.g. where:"hostname=dns1"

Services Trend

Charts from the Services>Trend page:

trends.addServicesTrend({chart:'http_method'});

The following chart values are defined:

  • http_method HTTP operations
  • http_status HTTP status codes
  • app_operations Application operations
  • app_errors Application errors
  • memcache_hitrate Memcache hit rate
  • memcache_hits Memcache hits
  • memcache_commands Memcache commands
  • memcache_misses Memcache misses
  • memcache_evictions Memcache evictions
  • memcache_rwbytes Memcache read/write bytes
  • memcache_bytes Memcache size
  • memcache_connections Memcache connections
  • memcache_items Memcache items
  • memcache_curritems Memcache current items
  • memcache_connectionrate Memcache connection rate
  • memcache_yieldrate Memcache connection yield rate
  • memcache_listendisabled Memcache connection listend disabled
  • memcache_cmdflush Memcache flush commands

Include a where filter to select groups or individual hosts, e.g. where:"hostname~web.*"

Services TopN

Charts from Services>TopN page:

trends.addServicesTopN({
  keys:'uriextension',
  value:'ops',
  title:'HTTP File Types'
});

The following value options are defined:

  • ops Operation per second
  • duration Average duration
  • bps Bits per second
  • Bps Bytes per second
  • fps Frames per second

Include a where filter to select groups or individual hosts, e.g. where:"hostname=web.*"

Trend

The utility functions described above simplify the creation of pre-defined trend charts. It is also possible to explicitly constuct the trend chart using the addTrend function and providing the paremeters for generating the data and the chart.

trends.addTrend({
  title:'Total Traffic',
  view:'traffic',
  select:'time,rate(bytes)',
  scale:8,
  step:true,
  legendHeadings:[],
  ylabel:'Bits per Second',
  type:'trend'
});

The following parameters are defined:

  • view The database view, e.g. traffic, ifcounters, host, application
  • select Comma separated list of fields to retrieve
  • type Type of chart, e.g. trend, topn
  • title Title for the chart
  • ylabel Units label for chart
  • scale Scale factor to apply to values
  • where Filter to apply to query
  • sort Field to sort results by
  • ascending Boolean flag to reverse sort direction
  • step Boolean flag to plot stepped value chart
  • mirror Boolean flag to plot mirrored value chart, alternate values are plotted above and below the zero y-axis
  • stack Boolean flag to stack values in plot
  • colors Comma separated list of color values for trend lines
  • legendHeadings Array of strings to label legend columns
  • legendLinks Set to true to add Search links to legend items
  • truncate Number of entries to keep in legend
  • globaltruncate Boolean flag to show only the top keys over the whole interval
  • includeother Boolean flag to include sum of other (non-legend) entries

For more information, see Scripting Queries

Scheduled Reports

Trend charts from the Reports>View page:

trends.addReportTrend({group:'base',report:'protocols',section:0,instance:1});

The following parameters must be specified:

  • group The directory name containing the report template.
  • report The name of the report template file.
  • section The section number within the report template.
  • instance The chart number within the section.

To find the parameters, navigate to the Report>View tab and drill down to a specific report. Click on the TXT, HTML, or Image link under the trend chart and note the query parameters in the URL. The query parameter names match the names in the addReportTrend() function and the values are required to include the trend chart in the dashboard.

Particle Vizualization

Traffic Sentinel ships with an example "particle.js" script. Make a Copy and edit the north, south, east and west axes to customize, using the Zones configured for your site, see Configuring Traffic Sentinel.

// description: InMon Site Traffic
// author: InMon
// date: 1/28/16
// version: 1.0
// authLevel:guest
// clientJS:flow-1.0.js
// ttl:60
// view:traffic
// resultFormat: json

include('flow-1.0.js');

new Flow({
  N:{zones:['EXTERNAL'],label:'External'},
  S:{zones:['Data Center'],label:'Data Center'},
  E:{zones:['Cloud'],label:'Cloud'},
  W:{zones:['HQ'],label:'HQ'},
  height:600,
  links:true
}).printResult();

Sankey Flow Vizualization

Traffic Sentinel ships with an example "sankey.js" script. Make a Copy and edit to customize. The list of layers defines the columns in the Sankey chart.

// description: sankeyflows
// author: InMon
// date: 5/15/2022
// version: 1.0
// authLevel:operator
// clientJS:sankey-1.0.js
// ttl:60
// view:traffic
// resultFormat: json

// Copy this REST script to create new dashboards
// See http://www.inmon.com/tutorials8/dashboard.php

include('sankey-1.0.js');

new Sankey({
    height: 600,
    layers: ['sourceaddress','protocol','destinationaddress'],
    value: "bps",
    interval: "last5minutes",
    colors: '#000000,#db3a34,#f0c808,#56926e,#6c4f77,#4281a4',
    refresh: true,
    debug: false
}).printResult();

Stand alone dashboards

Stand alone dashboards are a way to share selected information from Traffic Sentinel with a wider audience without requiring a Traffic Sentinel account for each viewer. Access to the dashboard is controlled using the authClients:, authUser: and authPasswd: options in the script header (see REST API Builder tutorial.)

Enabling caching of query results with the ttl: and view: options allows the dashboard to be shared with a large number of viewers without overloading the server since results will only be re-computed when needed, not with every request (see REST API Builder tutorial.)


Related Topics