Metric

API Reference

A metric; a mechanism for fetching time-series data. To create a metric, you need a context and a source, such as Cube or Graphite. For example:

var context = cubism.context(), // a default context
    cube = context.cube("http://cube.example.com"), // a Cube source
    requests = cube.metric("sum(request)"); // count request events

# metric.valueAt(index)

Returns the value of the metric at the given index.

# metric.extent()

Returns the minimum and maximum metric value as a two-element array, [min, max].

# metric.add(operand)

Derive a new metric by adding this metric to another metric or constant. If operand is a metric, returns a new metric that represents this metric plus operand. Otherwise, operand is implicitly converted to a numeric constant using context.constant.

# metric.subtract(operand)

Derive a new metric by subtracting another metric or constant from this metric. If operand is a metric, returns a new metric that represents this metric minus operand. Otherwise, operand is implicitly converted to a numeric constant using context.constant.

# metric.multiply(operand)

Derive a new metric by multiplying this metric by another metric or constant. If operand is a metric, returns a new metric that represents this metric times operand. Otherwise, operand is implicitly converted to a numeric constant using context.constant.

# metric.divide(operand)

Derive a new metric by dividing this metric by another metric or constant. If operand is a metric, returns a new metric that represents this metric divided by operand. Otherwise, operand is implicitly converted to a numeric constant using context.constant.

# metric.shift(offset)

Derive a new metric by time-shifting this metric by the specified offset in milliseconds. Unless you have a time machine, the offset should be negative.

# metric.on(type[, listener])

Add, get or remove a listener for "change" events. This method is typically used only by other Cubism components, but can be used if you want to perform other actions concurrently when new metric values are available (such as custom processing). One type of event is currently supported:

• change events are dispatched at the time new metric values are available. This event is used, for example, by charts to render the new values. Listeners are passed two arguments: the start time (a Date, inclusive) and the stop time (a Date, exclusive), based on the original context change event. The this context of the listener is the metric.

This method follows the same API as D3's dispatch.on. If listener is specified and non-null, sets the callback function for events of the specified type and returns the metric; any existing listener for the same type will be replaced. If listener is specified and null, clears the callback function for events of the specified type (if any) and returns the metric. If listener is not specified, returns the current callback function, if any. The type can be further qualified with a namespace so that multiple listeners can receive the same events; for example, you might use "change.foo" and "change.bar" to register two listeners for change events.

Note: metrics only fetch new data if at least one listener is receiving change events. Typically, this is the chart visualizing the metric.

# metric.context

The metric's parent context.

# metric.toString()

Returns the metric's associated expression, if any. For example, for Graphite and Cube metrics this is the first argument to the constructor.