rrdFlotSupport module

The rrdFlotSupport Javascript module implements a set of commonly used functions an classes that may be used while plotting RRD files with Flot.

Overview

This module provides two types of support:

Function rrdDS2FlotSeries

This function extracts a specific DS from a specific RRA and returns an object that contains the data in format flot expects.

Input parameters:

Parameter

Description

rrd_file

An object of type RRDFile or equivalent.

ds_id

Identifier of the desired DS (as accepted by RRDFile.getDS()).

rra_idx

Index of the desired RRA.

want_rounding

If not false, all timestamps will be truncated to the RRA step.

The output is an object containing:

Attribute

Description

data

A list of datapoints suitable to be fed to Flot. Each element is a (Timestamp in ms, value) pair.

An example of use with Flot:

var fd=rrdDS2FlotSeries(...);
var plot = $.plot("#myplot", [{data:fd.data}], options);

label

The DS name.

min

Min and max timestamp in ms.

max

Function rrdRRA2FlotObj

This function extracts a list of DSs from a specific RRA and returns an object that contains the data in format flot expects.

Input parameters:

Parameter

Description

rrd_file

An object of type RRDFile or equivalent.

rra_idx

Index of the desired RRA.

ds_list

List of DS identifiers (as accepted by RRDFile.getDS()).

want_ds_labels

Should the DS names be included as labels in the output? (If false, only the order distinguishes the requested DSs)

want_rounding

If not false, all timestamps will be truncated to the RRA step.

The output is an object containing:

Attribute

Description

data

A list of objects suitable to be fed to Flot. Each element is an object composed of two attributes:

  • data - A list of (Timestamp in ms, value) pairs.
  • label - The (optional) DS name.

An example of use with Flot:

var fd=rrdDS2FlotObj(...);
var plot = $.plot("#myplot", fd.data, options);

min

Min and max timestamp in ms.

max

Function rrdRRAStackFlotObj

This function extracts a list of DSs from a specific RRA, stacks them as requested and returns an object that contains the data in format flot expects.

Input parameters:

Parameter

Description

rrd_file

An object of type RRDFile or equivalent.

rra_idx

Index of the desired RRA.

ds_positive_stack_list

List of DS identifiers (as accepted by RRDFile.getDS()) to be stacked. All values must be positive if ds_negative_stack_list is not empty.

ds_negative_stack_list

List of DS identifiers (as accepted by RRDFile.getDS()) to be stacked. All values must be negative if ds_positive_stack_list is not empty.

ds_single_list

List of DS identifiers (as accepted by RRDFile.getDS()). No stacking for these ones.

want_ds_labels

Should the DS names be included as labels in the output? (If false, only the order distinguishes the requested DSs)

want_rounding

If not false, all timestamps will be truncated to the RRA step.

one_undefined_enough

If true, a whole stack is invalidated if a single element of the stack is invalid.

The output is an object containing:

Attribute

Description

data

A list of objects suitable to be fed to Flot. Each element is an object composed of two attributes:

  • data - A list of (Timestamp in ms, value) pairs.
  • label - The (optional) DS name.

An example of use with Flot:

var fd=rrdDS2FlotObj(...);
var plot = $.plot("#myplot", fd.data, options);

min

Min and max timestamp in ms.

max

Function rrdRRAMultiStackFlotObj

This function extracts a DS from a list of RRDs, using a specific RRA index, then stacks them and returns an object that contains the data in format flot expects.

Input parameters:

Parameter

Description

rrd_files

A list of RRDs. Each element of the list contains a [rrd_id,rrd_file] pair.

  • rrd_id - Logical name for the RRD.
  • rrd_file -An object of type RRDFile or equivalent.

rra_idx

Index of the desired RRA.

ds_id

DS indentifier (as accepted by RRDFile.getDS())

want_rrd_labels

Should the RRD names be included as labels in the output? (If false, only the order distinguishes the requested RRDs)

want_rounding

If not false, all timestamps will be truncated to the RRA step.

one_undefined_enough

If true, a whole stack is invalidated if a single element of the stack is invalid.

The output is an object containing:

Attribute

Description

data

A list of objects suitable to be fed to Flot. Each element is an object composed of two attributes:

  • data - A list of (Timestamp in ms, value) pairs.
  • label - The (optional) DS name.

An example of use with Flot:

var fd=rrdDS2FlotObj(...);
var plot = $.plot("#myplot", fd.data, options);

min

Min and max timestamp in ms.

max

Class rrdFlotSelection

Helper class to handle Flot selections.

Method

Description

reset()

Clear the selection. (isSet() will return False)

isSet()

Was a selection set?

setFromFlotRanges(ranges)

Set the selection to ranges.xaxis. See plotselected Flot event for more info on ranges. (isSet() will return True, and getFlotRanges() can now be called.)

getFlotRanges()

Return a ranges object. See plotselected Flot event for more info on ranges.

trim_flot_data(flot_data)

Create a new Flot data object by selecting only the data points within the current selection.

An example Flot data object is 

rrdDS2FlotObj(...).data

trim_data(data_list)

Create a new data list by selecting only the data points within the current selection.

An example data list is 

rrdDS2FlotSeries(...).data

Pseudo-example of use: 

  myplotplot.bind("plotselected", function (event, ranges) {
      // do the zooming
      selection_range.setFromFlotRanges(ranges);
      graph_options.xaxis.min=ranges.xaxis.from;
      graph_options.xaxis.max=ranges.xaxis.to;
      mygraph = $.plot("#mygraph", selection_range.trim_flot_data(flot_data), graph_options);
  });

This module is part of the javascriptRRD package hosted at http://javascriptrrd.sourceforge.net.
It is licensed under the MIT license.