Evaluator

Wiki ▸ API Reference ▸ Evaluator

Evaluators compute metrics and stream events to clients, and are typically used to drive time-series visualizations and alerts. The evaluator reads events from Cube's Mongo database and caches computed metrics in capped collections.

# /1.0/event/get

Request events from Cube. The endpoint supports both HTTP GET and WebSockets. For HTTP, the supported query parameters are:

• expression - an event expression specifying the desired events.
• start - the start date for events, inclusive, ISO 8601; defaults to UNIX epoch.
• stop - the stop date for events, exclusive, ISO 8601; defaults to now.
• limit - the maximum number of events to return; defaults to ten thousand.

For example, to get the time and IP address of the most recent "cube_request" event, say:

http://localhost:1081/1.0/event?expression=cube_request(ip)&limit=1

To see all the requests to this endpoint on April 16, 2012, say:

http://localhost:1081/1.0/event?expression=cube_request.eq(path,'/1.0/event')&start=2012-04-16&stop=2012-04-17

If the request is successful, the endpoint returns a status 200 and an array of JSON-encoded events. If the request fails, a status 400 is returned with "{error: message}", where message is a description of what went wrong.

For WebSockets, send event requests as messages. Each request should be JSON-encoded. For example, to repeat the above request over WebSockets:

var socket = new WebSocket("ws://localhost:1081/1.0/event/get");

socket.onopen = function() {
  socket.send(JSON.stringify({
    "expression": "cube_request.eq(path,'/1.0/event')",
    "start": "2012-04-16",
    "stop": "2012-04-17"
  }));
};

socket.onmessage = function(message) {
  console.log(JSON.parse(message.data));
};

The WebSockets endpoint also supports a streaming interface, where the stop time is omitted. In this case, Cube will continuously send new events as they arrive. If there is lag in the arriving events (for example, because your emitters are replicating data from a secondary source, such as a SQL database), you may wish to specify a delay parameter to time-shift the event stream by some milliseconds. The default delay is five seconds (5000). If events are further delayed, the streaming API may skip events.

# /1.0/metric/get

Request metrics from Cube. The endpoint supports both HTTP GET and WebSockets. For HTTP, the supported query parameters are as follows:

• expression - a metric expression specifying the desired metric.
• start - the start date for metrics, inclusive, ISO 8601; defaults to UNIX epoch.
• stop - the stop date for metrics, exclusive, ISO 8601; defaults to now.
• step - the step interval for metrics, in milliseconds.
• limit - the maximum number of metrics to return; defaults to ten thousand.

Cube supports five metric resolutions:

• 1e4 - 10-second
• 6e4 - 1-minute
• 3e5 - 5-minute
• 36e5 - 1-hour
• 864e5 - 1-day

For example, to get the number of "cube_request" events in the last minute, say:

http://localhost:1081/1.0/metric?expression=sum(cube_request)&step=6e4&limit=1

To see all the requests on April 16, 2012 between 4:00 PM and 5:00 PM UTC, say:

http://localhost:1081/1.0/metric?expression=sum(cube_request)&start=2012-04-16T16:00Z&stop=2012-04-16T17:00Z&step=6e4

If the request is successful, the endpoint returns a status 200 and an array of JSON-encoded metric values. If the request fails, a status 400 is returned with "{error: message}", where message is a description of what went wrong.

For WebSockets, send metric requests as messages. Each request should be JSON encoded. For example, to repeat the above request over WebSockets:

var socket = new WebSocket("ws://localhost:1081/1.0/metric/get");

socket.onopen = function() {
  socket.send(JSON.stringify({
    "expression": "sum(cube_request)",
    "start": "2012-04-16T16:00:00Z",
    "stop": "2012-04-16T17:00:00Z",
    "step": 6e4
  }));
};

socket.onmessage = function(message) {
  console.log(JSON.parse(message.data));
};

# /1.0/types/get

Request known event types from Cube. The endpoint supports both HTTP GET and WebSockets. For example, to query the known event types using d3.json, you can say:

d3.json("/1.0/types", function(types) {
  console.log(types);
});

Which will return an array of names, such as:

["collectd", "cube_compute", "cube_request", "random", "test"]

A WebSockets interface is provided for consistency, though there's little reason to use it over the simpler HTTP GET request:

var socket = new WebSocket("ws://localhost:1081/1.0/types/get");

socket.onopen = function() {
  socket.send(JSON.stringify({}));
};

socket.onmessage = function(message) {
  console.log(JSON.parse(message.data));
};

Static Files

The evaluator also provides static file serving by default, via node-static. Any files you put in the static directory will be served by the evaluator. This is a convenient place to put dashboards that you write for visualizing data from Cube!

The evaluator sets the Access-Control-Allow-Origin header to "*". Therefore, you can communicate with the evaluator from any server. If you want to write a point-and-click dashboard constructor on top of Cube, you can write that as a separate server; there's no need to integrate it directly with Cube. This is particularly nice if you want to integrate metrics from multiple back-ends (say, Splunk and Graphite).

Configuration

When constructing a cube.server (or running the default bin/evaluator), you may specify a configuration object that controls its behavior. The default configuration is as follows:

{
  "mongo-host": "127.0.0.1",
  "mongo-port": 27017,
  "mongo-database": "cube_development",
  "mongo-username": null,
  "mongo-password": null,
  "http-port": 1080
}

The mongo-host, mongo-port and mongo-database controls where the collector saves events, and where it finds metrics to invalidate. If your Mongo database requires authentication, specify the optional mongo-username and mongo-password parameters. The http-port parameter specifies the port the collector listens to.

Starting and Stopping

To start the evaluator:

node bin/evaluator &

To stop the evaluator, ^C the process:

fg
^C

Alternatively, find the process via ps and then kill it:

ps aux | grep -e 'evaluator' | grep -v grep | awk '{print $2}' | xargs -i kill -SIGINT {}