dash-javascript

dash-javascript makes it easy to fetch recent data from your applications using the FiveRuns Dash service for use on web pages. You can choose the granularity of data you’d like; 1 hour, 12 hours, 24 hours, etc.

The current version of dash-javascript is 0.6.0.

Dependencies

jQuery >= 1.3.1 (may work with jQuery 1.2.6)

Examples

For the impatient:

Use .dash(options, callback) to fetch data from Dash.
Required keys are token, fetch, and metric.
Depending on which fetch parameter you use, your callback function will either receive a single value, an array of values, or an object.
In your callback, this will refer to an element matching your selector.

Fetching the most recent value for the cpu metric:

<div id="demo0">
  Latest CPU value: 
</div>

$('#demo0').dash({fetch: 'latest', token: token, metric: 'cpu'},
  function(value) {
    $(this).append(value);
});

Latest CPU value:

Fetching a data series:

<div id="demo1">
  Recent CPU values:
</div>

$('#demo1').dash({fetch: 'series', token: token, metric: 'cpu'},
  function(values) {
    $(this).append(values.join(','));
  });

Recent CPU values:

Fetching metadata and metric data:

$('#demo2').dash({fetch: 'all', token: token, metric: 'cpu'},
  function(obj) {
    $(this).children('h4').replaceWith("<h4>" + obj.metric + " from " + obj.app + "</h4>");
    $(this).children('.values').append("Most recent value: " + obj.data.reverse()[0][1]);
  });

<div id="demo2">
  <h4>Placeholder</h4>
  
  <p class="values"></p>
</div>

Placeholder

Dash options

The dash method takes a parameters object and a callback function. The value of the fetch key determines the data that is returned to your callback function.

`fetch` option	Callback arguments
`latest`	The latest value for the specified metric.
`series`	An array of data values for the specified metric.
`all`	Metric metadata plus the data values.

In addition to fetch, other parameters are respected:

Parameter name Required/Default Meaning

metric Yes The name of the metric to fetch. This is specified when you define a recipe.

token Yes This is the read token for your Dash application.

Parameter name	Required/Default	Meaning
`metric`	Yes	The name of the metric to fetch. This is specified when you define a recipe.
`token`	Yes	This is the read token for your Dash application.
`window`	No/1 hour	This specifies the time window to use when fetching results. 0 1 hour 1 12 hours 2 24 hours 3 48 hours 4 1 week Due to the way Dash stores metrics, you will receive between 48 and 60 data points. This means that each data point represents a progressively longer interval. For example, when you pull one hour of data, each point represents one minute of data. When you pull 12 hours of data, each point represents 15 minutes of data. Dash will return zero-padded results if there isn't enough data to completely populate the specified window.

window

No/1 hour

This specifies the time window to use when fetching results.

0: 1 hour
1: 12 hours
2: 24 hours
3: 48 hours
4: 1 week

Due to the way Dash stores metrics, you will receive between 48 and 60 data points. This means that each data point represents a progressively longer interval. For example, when you pull one hour of data, each point represents one minute of data. When you pull 12 hours of data, each point represents 15 minutes of data. Dash will return zero-padded results if there isn't enough data to completely populate the specified window.

The Dash response object

The Dash API returns a JSON object. When the fetch parameter is latest or series, this object is filtered before your callback function is called. When you specify all, you will get the raw object.

Attribute name	Description
`metric`	The human-friendly description of the metric.
`app`	The name of the application this metric belongs to.
`data`	An array of two-tuples. Each entry in the array is a data point. The tuple is of the form `[timestamp, metric value].`
`unit`	A label for the units of the fetched metric. For example, `cpu` is in "%", `vsz` (virtual memory size) is in kilobytes, etc.

Contact

FiveRuns Development Team (dev@fiveruns.com)

Download

You can download this project in either zip or tar formats.

You can also clone the project with Git by running:

$ git clone git://github.com/fiveruns/dash-javascript

See the README file for license and author info.