Metric

Wiki ▸ API Reference ▸ Metric

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.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 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 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 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 constant.

For example, if the context step interval is five minutes, you can convert a count metric to a per-second rate by dividing by 300 (5 * 60):

var requestsPerSecond = cube.metric("sum(request)").divide(5 * 60);

Or, more generally:

var requestsPerSecond = cube.metric("sum(request)").divide(context.step() / 1000);

# 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.

For example, to compare the number of requests this week to the number of requests last week, you might say:

var requestsThisWeek = cube.metric("sum(request)"),
    requestsLastWeek = requestsThisWeek.shift(-7 * 24 * 60 * 60 * 1000),
    changeInRequests = requestsThisWeek.subtract(requestsLastWeek);

# metric.valueAt(index)

Returns the value of the metric at the given index. This method is typically used only by Cubism's chart components to visualize the fetch values. The index is a nonnegative integer ranging from 0, indicating the context's start time (the first argument from the context's change event, inclusive), to size - 1, indicate the context's stop time (the second argument, exclusive).

# metric.extent()

Returns the minimum and maximum metric value as a two-element array, [min, max]. This method is typically used only by Cubism's chart components to visualize the fetch values. If metric data is unavailable, returns [-Infinity, Infinity].

# 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.