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; defaults to UNIX epoch.
• stop - the stop date for events, exclusive; 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 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:1080/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 the events are replicated from a secondary data 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 lag further than this delay, the streaming API may skip events.

# /1.0/metric/get

# /1.0/types/get

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 {}