Skip to content
mbostock edited this page Apr 2, 2012 · 35 revisions

API Reference

A context keeps track of the metric resolution (the step, in milliseconds) and the number of metric values to fetch and display (the size). Contexts are the root object of any Cubism dashboard, and are used to create charts and metrics, while keeping them in-sync.

To create a default context, say:

var context = cubism.context();

To create a custom context, you might say:

var context = cubism.context()
    .serverDelay(30 * 1000) // allow 30 seconds of collection lag
    .step(5 * 60 * 1000) // five minutes per value
    .size(1920); // fetch 1920 values (1080p)

Contexts are required to create sources (such as Cube and Graphite), which are in turn required to create metrics. Contexts are also required to create charts (such as horizon charts and comparison charts).

# context.step([step])

Get or set the context step in milliseconds. If step is specified, sets the new context step and returns the context; if step is not specified, returns the current step. The step defaults to ten seconds (1e4). Note: the step cannot be changed after the context is initialized, which occurs shortly after creation via a brief timeout.

# context.size([size])

Get or set the context size in number of values. If size is specified, sets the new context size and returns the context; if size is not specified, returns the current size. The size defaults to 1440 (four hours at the default step of ten seconds). Note: the size cannot be changed after the context is initialized, which occurs shortly after creation via a brief timeout.

# context.serverDelay([delay])

Get or set the context server-side delay in milliseconds. If delay is specified, sets the new context server delay and returns the context; if delay is not specified, returns the current server delay. The server delay defaults to four seconds (4e3). The server delay is the amount of time the context waits for the server to compute or collect metrics. This delay may result from clock skew (either between the client and server, or between the server and the hosts generating metrics) or from delays collecting metrics from various hosts.

# context.clientDelay([delay])

Get or set the context client-side delay in milliseconds. If delay is specified, sets the new context client delay and returns the context; if delay is not specified, returns the current client delay. The client delay defaults to one second (1e3). The client delay is the amount of additional time the context waits to fetch metrics from the server. The client and server delay combined represent the age of the most recent displayed metric. The client delay exists so that the charts can be redrawn concurrently, rather than redrawing each chart as the associated metric arrives; this reduces the distracting effect of many charts updating simultaneously. Note: the client delay need only consider the expected delay when incrementally fetching the next metric value, not the (typically much more expensive) initial load.

# context.graphite(url)

Create a source for Graphite metrics.

# context.cube(url)

Create a source for Cube metrics.

# context.constant(value)

Create a constant-value metric.

# context.horizon()

Create a horizon chart.

# context.comparison()

Create a comparison chart.

# context.on(type[, listener])

Add, get or remove a listener for "beforechange" or "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 metrics are displayed (such as custom visualizations). Two types of events are supported:

  • change events are dispatched at the time new metrics should be displayed. 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). The this context of the listener is the context. Note that the stop time will be slightly before the current time (now) based on the server delay plus the client delay. For example, if the combined delay is five seconds, and the step interval is ten seconds, then change events will be dispatched at :05 seconds past the minute, :15 seconds, :25 seconds, etc.

  • beforechange events are dispatched shortly before change events, typically to prefetch new metric values. Listeners are passed two arguments: the start time (a Date, inclusive) and the stop time (a Date, exclusive). The this context of the listener is the context. Note that the stop time will be slightly before the current time (now) based on the server delay. For example, if the server delay is four seconds, and the step interval is ten seconds, then beforechange events will be dispatched at :04 seconds past the minute, :14 seconds, :24 seconds, etc.

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 context; 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 context. 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 "beforechange.foo" and "beforechange.bar" to register two listeners for beforechange events.

Given an element with the id "update-time", here's how you might display the most recent update time:

context.on("change", function(start, stop) {
  d3.select("#update-time").text("Last updated at " + stop + ".");
});
Clone this wiki locally