/usr/share/doc/cockpit/guide/cockpit-series-data.html is in cockpit-doc 164-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>cockpit.js: Series Data</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="api-base1.html" title="API: base1">
<link rel="prev" href="cockpit-metrics.html" title="cockpit.js: Metrics">
<link rel="next" href="cockpit-channels.html" title="cockpit.js: Raw Channels">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="cockpit-metrics.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="api-base1.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="cockpit-channels.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="cockpit-series-data"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>cockpit.js: Series Data</h2>
<p>cockpit.js: Series Data — Representing series data</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<p>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.</p>
</div>
<div class="refsection">
<a name="cockpit-grid"></a><h2>cockpit.grid()</h2>
<pre class="programlisting">
grid = cockpit.grid(interval, [beg, end])
</pre>
<p>Creates a grid object to contain series data.</p>
<p>The <code class="code">interval</code> is the granularity of the grid. Usually this is
a number of milliseconds, when used with time series data. The <code class="code">beg</code>
and <code class="code">end</code> are the bounds of the grid. If omitted they will be set to
zero for an initially empty grid.</p>
<p>If <code class="code">beg</code> and/or <code class="code">end</code> 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.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-add"></a><h2>grid.add()</h2>
<pre class="programlisting">
row = grid.add(series, path)
row = grid.add(callback, [early])
row = grid.add()
</pre>
<p>Adds a row to the grid. The returned <code class="code">row</code> is a Javascript array that will contain
series data. The arguments control how the row is populated from the series data.
The <code class="code">row</code> is a sparse array. Its <code class="code">row.length</code> will not match the
expected size of the grid, unless and until the row has been completely filled in. The first
index of the <code class="code">row</code> will contain the data from the series data at the
<a class="link" href="cockpit-series-data.html#cockpit-grid-beg" title="grid.beg"><code class="code">grid.beg</code></a> offset.</p>
<p>When no arguments are passed, an empty row is added, and it is not populated with data.</p>
<p>When called with a <code class="code">series</code> and <code class="code">path</code> argument then the row
will be populated directly with series data. The <code class="code">series</code> can either be a
<a class="link" href="cockpit-series-data.html#cockpit-series" title="cockpit.series()">series object</a> or an object that has an <code class="code">obj.series</code>
property. The <a class="link" href="cockpit-series-data.html#cockpit-series-interval" title="series.interval">series interval</a> must match the
interval of this grid.
If <code class="code">path</code> is missing or empty, then the series data is placed into the row
directly. Otherwise <code class="code">path</code> indicates which part of the series data to place in the
row. When <code class="code">path</code> is an array, it is used as a set of property names or array indexes
to follow into nested series data. When <code class="code">path</code> 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.</p>
<p>If a <code class="code">callback</code> function is specified, then it will be invoked to provide series data
for the row. The function is invoked as <code class="code">callback(row, index, count)</code>, where the
<code class="code">row</code> is the row to fill in, the <code class="code">index</code> is the index to start filling in and
<code class="code">count</code> is the number of items to fill in. The <code class="code">this</code> variable will be set
to the grid while invoking the <code class="code">callback</code>. 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
<code class="code">early</code> argument is set to <code class="code">true</code>, in which case the callback is called earlier
than callbacks without the <code class="code">early</code> argument set.</p>
<p>To remove the row use the
<a class="link" href="cockpit-series-data.html#cockpit-grid-remove" title="grid.remove()"><code class="code">grid.remove()</code> method.</a>
</p>
<p>The row will start being populated with data when the <code class="code">series</code> produces data.
To make this happen right away, use the
<a class="link" href="cockpit-series-data.html#cockpit-grid-sync" title="grid.sync()"><code class="code">grid.sync()</code></a> method.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-remove"></a><h2>grid.remove()</h2>
<pre class="programlisting">
grid.remove(row)
</pre>
<p>Remove a previously added <code class="code">row</code> from the grid. The row will no longer be updated
with series data.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-sync"></a><h2>grid.sync()</h2>
<pre class="programlisting">
grid.sync()
</pre>
<p>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
<a class="link" href="cockpit-series-data.html#cockpit-series-load" title="series.load()"><code class="code">series.load()</code></a> for each series.</p>
<p>All rows with callbacks will be invoked to regenerate all the data. The
<a class="link" href="cockpit-series-data.html#cockpit-grid-onnotify" title="grid.onnotify"><code class="code">grid.onnotify</code></a> event will be triggered.
It is not necessary to call this function after a call of the
<a class="link" href="cockpit-series-data.html#cockpit-grid-move" title="grid.move()"><code class="code">grid.move()</code></a> method.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-move"></a><h2>grid.move()</h2>
<pre class="programlisting">
grid.move(beg[, end])
</pre>
<p>Move the grid to new <code class="code">beg</code> and <code class="code">end</code> range. Data will be
discarded from the rows and <a class="link" href="cockpit-series-data.html#cockpit-grid-sync" title="grid.sync()"><code class="code">grid.sync()</code></a>
will be called to load or reload series data for the new range of offsets.</p>
<p>If <code class="code">end</code> is not specified it will be set to <code class="code">beg</code>. If <code class="code">beg</code>
and/or <code class="code">end</code> are negative (including negative zero) then they will be set to the
number of intervals prior to the current time taken as an interval.</p>
<p>If <code class="code">beg</code> and/or <code class="code">end</code> 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.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-walk"></a><h2>grid.walk()</h2>
<pre class="programlisting">
grid.walk()
</pre>
<p>Move the grid forward every
<a class="link" href="cockpit-series-data.html#cockpit-grid-interval" title="grid.interval"><code class="code">grid.interval</code></a> milliseconds. To stop
moving forward, call <a class="link" href="cockpit-series-data.html#cockpit-grid-move" title="grid.move()"><code class="code">grid.move()</code></a>.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-notify"></a><h2>grid.notify()</h2>
<pre class="programlisting">
grid.notify(index, count)
</pre>
<p>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
<a class="link" href="cockpit-series-data.html#cockpit-grid-onnotify" title="grid.onnotify"><code class="code">grid.onnotify</code></a> event.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-onnotify"></a><h2>grid.onnotify</h2>
<pre class="programlisting">
grid.addEventListener("notify", function(index, count) { ... });
</pre>
<p>An event that is triggered when some part of the series data in grid changes. The
<code class="code">index</code> is the row index where things changed, and the <code class="code">count</code>
is the length of the data that changed.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-close"></a><h2>grid.close()</h2>
<pre class="programlisting">
grid.close()
</pre>
<p>Close the grid, and stop updating the rows.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-interval"></a><h2>grid.interval</h2>
<p>The granularity of the grid. For time series data this is an interval in
milliseconds. In order to use a given
<a class="link" href="cockpit-series-data.html#cockpit-grid" title="cockpit.grid()">grid</a> and
<a class="link" href="cockpit-series-data.html#cockpit-series" title="cockpit.series()">series</a> together, their interval properties
must match.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-beg"></a><h2>grid.beg</h2>
<p>The beginning offset of the series data in the grid. Do not set this property
directly. Use the <a class="link" href="cockpit-series-data.html#cockpit-grid-move" title="grid.move()">grid.move()</a> method instead.</p>
</div>
<div class="refsection">
<a name="cockpit-grid-end"></a><h2>grid.end</h2>
<p>The ending offset of the series data in the grid. Do not set this property
directly. Use the <a class="link" href="cockpit-series-data.html#cockpit-grid-move" title="grid.move()">grid.move()</a> method instead.</p>
</div>
<div class="refsection">
<a name="cockpit-series"></a><h2>cockpit.series()</h2>
<pre class="programlisting">
series = cockpit.series(interval, [cache, fetch])
</pre>
<p>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.</p>
<p>The <code class="code">interval</code> is the granularity of the series data. For time series data
this is an interval in milliseconds. If a <code class="code">cache</code> string is specified, series data
will be cached across frames for series with the same <code class="code">cache</code> cache identifier
to load and/or reload.</p>
<p>If a <code class="code">fetch</code> callback
is specified, then it will be invoked when grids request certain ranges of data. The
<code class="code">fetch</code> callback is invoked with <code class="code">function fetch(beg, end) { ... }</code>
range offsets. The <a class="link" href="cockpit-series-data.html#cockpit-series-input" title="series.input()">series.input()</a> 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.</p>
<p>A producer of series data, usually calls this function and creates itself a
<code class="code">obj.series</code> property containing this series object.</p>
</div>
<div class="refsection">
<a name="cockpit-series-input"></a><h2>series.input()</h2>
<pre class="programlisting">
series.input(beg, items[, mapping])
</pre>
<p>Send series data into the series sink. Any grids that have added rows based on this
series, will have data filled in. The <code class="code">beg</code> is the beginning offset of
<code class="code">items</code>. The <code class="code">items</code> are an array one or more series data items.</p>
<p>Producers may wish to provide additional properties that can be used in lookup paths that
rows can pull from. This is done in the <code class="code">mapping</code> argument. If specified it is
a tree of objects. Each sub object should have a property with the name <code class="code">""</code>
empty string, which will be used as the property name or index in place of the one used
in the lookup path.</p>
</div>
<div class="refsection">
<a name="cockpit-series-load"></a><h2>series.load()</h2>
<pre class="programlisting">
series.load(beg, end)
</pre>
<p>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.</p>
<p>The <code class="code">beg</code> and <code class="code">end</code> denote the range of data to load.</p>
</div>
<div class="refsection">
<a name="cockpit-series-interval"></a><h2>series.interval</h2>
<p>The granularity of the series. For time series data this is an interval in
milliseconds. In order to use a given
<a class="link" href="cockpit-series-data.html#cockpit-grid" title="cockpit.grid()">grid</a> and
<a class="link" href="cockpit-series-data.html#cockpit-series" title="cockpit.series()">series</a> together, their interval properties
must match.</p>
</div>
<div class="refsection">
<a name="cockpit-series-limit"></a><h2>series.limit</h2>
<p>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
<a class="link" href="cockpit-series-data.html#cockpit-grid-walk" title="grid.walk()"><code class="code">grid.walk()</code></a>.</p>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>
|