-
Notifications
You must be signed in to change notification settings - Fork 417
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:
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.
The WebSockets endpoint supports an additional parameter:
- id - an identifier to distinguish responses among concurrent requests.
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:
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));
};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).
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.
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 {}