Configuration

Dashiki dashboard configurations are written as javascript, with one file per dashboard view. Files live under cfg/, must end with .js and may be organised to any desired depth of directories. The top-level directories are used to represent major sections in index view (for example, different projects, or to distinguish business/engineering/ops, etc).

Simple example

A simple dashboard to view two graphite metrics:

Dash.stats()
  .add(
    {
      title:  'Carbon Metrics Received',
      target: 'carbon.agents.*.metricsReceived'
    },
    {
      title:  'Carbon Cache Errors',
      target: 'carbon.agents.*.errors',
    }
  );

Dash.stats() declares a new dashboard view, and has methods called on the returned object to configure the dashboard.

.add() method can be called multiple times, with one or more object arguments to define metrics to be displayed.

Metric arguments

Standard object arguments are:

• title: display name of the metric
• target: for graphite, full metric path to display, may include wildcards and graphite functions; see pages for other source types for detailed target formatting
• type: data source type, default is 'graphite'
• source: url of data source, default is: 'http://graphite'
• headers: object hash describing http headers to send in data requests
• display: numeric value to display in stat box, options are 'sum' (default), 'avg' (or 'mean'), 'max', 'min', 'last' (most recent value in series)
• aggregate: how to combine multiple series (e.g. pulled using a wildcard metric) for small graph and display value calculation, options are 'sum' (default) and 'avg' ( or 'mean')
• format: a function which takes raw value as argument and reformats it for display value; some useful predefined format functions are available in public/js/Dash.Format.js; default is Dash.Format.Metric, which rounds scales large numbers to human-friendly units
• thresholds: an array of threshold object to apply to display value; see threshold page
• filter: a function, taking raw data from source as arg and returning a munged version for further processing
• renderer: render type for large graph, options are 'area' (default), 'line', 'bar', 'scatterplot'
• colors: array of hex colors to use for rendering multiple metrics in large graph

Specific data source types may have their own additional metric arguments, either optional or required. See source pages for details.

Application-wide defaults

Dashiki will load cfg/_defaults.js which defines a defaults object. This object's values will be applied as defaults to any new stat created with .add().

Dash.defaults = {
  type:    'graphite',
  source:  'http://graphite-web',
  format:  Dash.Format.Metric,
  display: 'sum',
  renderer: 'area',
  colors:  [ "#657b83", "#6c71c4", "#859900", "#d33682", "#b58900", "#cb4b16", "#268bd2", "#2aa198", "#dc322f" ]
};

Dashboard-wide defaults

Within a single dashboard configuration, the .config() method can be used to set defaults. Values will be applied to any subsequent calls to .add(). Further calls to .config() may be used to override values down the method chain.

Example, to change graphite server source and display option:

Dash.stats()
  .config({
    source:  'http://graphite-dev.foo.com',
    display: 'avg'
  })
  .add(
    {
      title:  'Mean Dev Carbon Metrics Received',
      target: 'carbon.agents.*.metricsReceived'
    },
    {
      title:  'Mean Dev Carbon Cache Errors',
      target: 'carbon.agents.*.errors',
    }
  );

Format functions

Format functions describe how to format the display value for a metric. They handle making numbers human-friendly: rounding, appending units, or anything you want. They receive the display value as argument. Some useful functions are provided in public/js/Dash.Format.js.

Examples to format a time-based metric, and a percentage metric:

Dash.stats()
  .add(
    {
      title:   'Carbon Cache avgUpdateTime',
      target:  'carbon.agents.*.avgUpdateTime',
      display: 'avg',
      format:  Dash.Format.Time
    },
    {
      title:   'Carbon CPU Usage',
      metric:  'carbon.agents.*.cpuUsage',
      display: 'avg',
      format:  function(x) { return x.toFixed(0) + '%' }
    }
  );

Thresholds

Thresholds work in a similar fashion to format functions: they take the display value and if function returns true, apply the given CSS class(es) to the display box. All matching classes will be applied.

Dash.stats()
  .add({
    title:   'Volume',
    target:  'stats.gauges.amp.volume',
    display: 'last',
    thresholds: [
      { class: 'green',     test: function(x) { return x<8 } },
      { class: 'red',       test: function(x) { return x>=8 && x<=10 } },
      { class: 'spinaltap', test: function(x) { return x==11 } }
    ]
  });

Dynamically finding metrics

For graphite it is possible to configure stats dynamically using a wildcard metric:

Dash.stats()
  .find({
    target: 'stats.gauges.amp.*',
    done: function(metrics) {
      metrics.forEach(function(metric) {
        var control = metric.split('.').slice(-1).join();
        this.add({
          title:   Dash.capitalize(control),
          target:  metric,
          display: 'last',
        });
      }, this);
    }
  })

There are convenience callbacks that may be used as alternatives to done: each: function(metric) {...} puts an implicit loop over metrics, and add: function(metric) {...} is each with an implicit this.add on the object returned.