Cockpit Guide |
---|
cockpit.js: Series Datacockpit.js: Series Data — Representing series data |
Series data consists of values along a continuous (usually time) axis. We can place these in grids which expose a distinct subset of these values. These are the underlying mechanism for displaying metrics data in graphs.
grid = cockpit.grid(interval, [beg, end])
Creates a grid object to contain series data.
The interval
is the granularity of the grid. Usually this is
a number of milliseconds, when used with time series data. The beg
and end
are the bounds of the grid. If omitted they will be set to
zero for an initially empty grid.
If beg
and/or end
are negative (including negative
zero) then they are interpreted in number of intervals relative to the current
time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most recent
5 minutes.
row = grid.add(series, path) row = grid.add(callback, [early]) row = grid.add()
Adds a row to the grid. The returned row
is a Javascript array that will contain
series data. The arguments control how the row is populated from the series data.
The row
is a sparse array. Its row.length
will not match the
expected size of the grid, unless and until the row has been completely filled in. The first
index of the row
will contain the data from the series data at the
grid.beg
offset.
When no arguments are passed, an empty row is added, and it is not populated with data.
When called with a series
and path
argument then the row
will be populated directly with series data. The series
can either be a
series object or an object that has an obj.series
property. The series interval must match the
interval of this grid.
If path
is missing or empty, then the series data is placed into the row
directly. Otherwise path
indicates which part of the series data to place in the
row. When path
is an array, it is used as a set of property names or array indexes
to follow into nested series data. When path
is a dotted string, it is split and used
the same way to locate the correct value in nested series data. The exact format of the series
data depends on its producer, and relevant paths will be documented there.
If a callback
function is specified, then it will be invoked to provide series data
for the row. The function is invoked as callback(row, index, count)
, where the
row
is the row to fill in, the index
is the index to start filling in and
count
is the number of items to fill in. The this
variable will be set
to the grid while invoking the callback
. The callback is called after other data
rows for a given series have been filled in. Callbacks are called in the order added, unless the
early
argument is set to true
, in which case the callback is called earlier
than callbacks without the early
argument set.
To remove the row use the
grid.remove()
method.
The row will start being populated with data when the series
produces data.
To make this happen right away, use the
grid.sync()
method.
grid.remove(row)
Remove a previously added row
from the grid. The row will no longer be updated
with series data.
grid.sync()
Load or reload data from the series into the rows. This does not clear the rows before
populating them. Some data may be populated immediately, others may have to wait until data
can be loaded. Internally this function calls
series.load()
for each series.
All rows with callbacks will be invoked to regenerate all the data. The
grid.onnotify
event will be triggered.
It is not necessary to call this function after a call of the
grid.move()
method.
grid.move(beg[, end])
Move the grid to new beg
and end
range. Data will be
discarded from the rows and grid.sync()
will be called to load or reload series data for the new range of offsets.
If end
is not specified it will be set to beg
. If beg
and/or end
are negative (including negative zero) then they will be set to the
number of intervals prior to the current time taken as an interval.
If beg
and/or end
are negative (including negative
zero) then they are interpreted in number of intervals relative to the current
time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most recent
5 minutes.
grid.walk()
Move the grid forward every
grid.interval
milliseconds. To stop
moving forward, call grid.move()
.
grid.notify(index, count)
This function is called to have rows with callbacks recalculate their data. It is not
normally necessary to call this function, as it will be invoked automatically when new
series data is available or has been loaded. This function triggers the
grid.onnotify
event.
grid.addEventListener("notify", function(index, count) { ... });
An event that is triggered when some part of the series data in grid changes. The
index
is the row index where things changed, and the count
is the length of the data that changed.
The granularity of the grid. For time series data this is an interval in milliseconds. In order to use a given grid and series together, their interval properties must match.
The beginning offset of the series data in the grid. Do not set this property directly. Use the grid.move() method instead.
The ending offset of the series data in the grid. Do not set this property directly. Use the grid.move() method instead.
series = cockpit.series(interval, [cache, fetch])
Create a new sink of series data. This is usually done by producers of series data, and it is rare to invoke this function directly.
The interval
is the granularity of the series data. For time series data
this is an interval in milliseconds. If a cache
string is specified, series data
will be cached across frames for series with the same cache
cache identifier
to load and/or reload.
If a fetch
callback
is specified, then it will be invoked when grids request certain ranges of data. The
fetch
callback is invoked with function fetch(beg, end) { ... }
range offsets. The series.input() should be
called with data retrieved, either immediately or at a later time. The callback may be
called multiple times for the same ranges of data. It is up to the callback to determine
when or whether it should retrieve the data more than once.
A producer of series data, usually calls this function and creates itself a
obj.series
property containing this series object.
series.input(beg, items[, mapping])
Send series data into the series sink. Any grids that have added rows based on this
series, will have data filled in. The beg
is the beginning offset of
items
. The items
are an array one or more series data items.
Producers may wish to provide additional properties that can be used in lookup paths that
rows can pull from. This is done in the mapping
argument. If specified it is
a tree of objects. Each sub object should have a property with the name ""
empty string, which will be used as the property name or index in place of the one used
in the lookup path.
series.load(beg, end)
Load data from the series into any grids that have rows based on this series data. Any cached data will be filled in immediately. Any data not cached, will be requested from the producer, if possible, and may arrive at a later time.
The beg
and end
denote the range of data to load.
The granularity of the series. For time series data this is an interval in milliseconds. In order to use a given grid and series together, their interval properties must match.
The maximum number of items to cache for loading and/or reloading. You can
change this value to a different number. Having a number close to zero will break
certain usage of grids, such as
grid.walk()
.