Evaluator

Wiki ▸ API Reference ▸ Evaluator

The evaluator is a server that runs by default on port 1081. Evaluators compute metrics and stream events to clients on request, 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 as follows:

• 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));
};

Configuration

When constructing a cube.server, 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 {}