Collector

Wiki ▸ API Reference ▸ Collector

Collectors receive events from emitters (client programs that you write) and save them to Cube's Mongo database. The collector also invalidates any cached metrics that were associated with the incoming events, so that the latest values are always available to evaluator clients.

# /1.0/event/put

Post events to Cube. The endpoint supports both HTTP POST and WebSockets. For HTTP, the body of the request should be a JSON-encoded array of events. For example, to post a single "request" event:

[
  {
    "type": "request",
    "time": "2011-09-12T21:33:12Z",
    "data": {
      "host": "web14",
      "path": "/search",
      "query": {
        "q": "flowers"
      },
      "duration_ms": 241,
      "status": 200,
      "user_agent": "Chrome/13.0.782.112"
    }
  }
]

If the above is in a file events.json, you can use curl to POST the event:

curl -X POST -d @events.json http://localhost:1080/1.0/event/put

If the post is successful, the endpoint returns a status 200 with the body "{}". If the post fails, a status 400 is returned with the body "{error: message}", where message is a description of what went wrong.

For WebSockets, simply send events as messages. Each event should be JSON encoded. For example, to post a single "request" event:

var socket = new WebSocket("ws://localhost:1080/1.0/event/put");

socket.onopen = function() {
  socket.send(JSON.stringify({
    "type": "request",
    "time": "2011-09-12T21:33:12Z",
    "data": {
      "host": "web14",
      "path": "/search",
      "query": {
        "q": "flowers"
      },
      "duration_ms": 241,
      "status": 200,
      "user_agent": "Chrome/13.0.782.112"
    }
  }));
};

If the post is successful, no message is returned. If an error occurs, Cube replies with a JSON error message that you can log. For example:

socket.onerror = function(error) {
  console.log("error", error);
};

While you can use WebSockets to post events to Cube directly, see also Cube's Emitter client, which provides automatic reconnect and retry for Node.js-based daemon emitters. See cube-ruby for a Ruby client.

# UDP

You can also send events via UDP to another port, which defaults to 1180. For example:

var dgram = require("dgram");

var udp = dgram.createSocket("udp4");

var buffer = new Buffer(JSON.stringify({
  "type": "request",
  "time": "2011-09-12T21:33:12Z",
  "data": {
    "host": "web14",
    "path": "/search",
    "query": {
      "q": "flowers"
    },
    "duration_ms": 241,
    "status": 200,
    "user_agent": "Chrome/13.0.782.112"
  }
}));

udp.send(buffer, 0, buffer.length, 1180, "127.0.0.1");

While you can use UDP to post events to Cube directly, see also Cube's Emitter client, which provides a convenient abstraction for sending events via either UDP or WebSockets.

# /collectd

See Collectd.

Configuration

When constructing a cube.server (or running the default bin/collector), 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,
  "udp-port": 1180
}

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 Collector:

node bin/collector &

To stop the Collector, ^C the process:

fg
^C

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

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