runt18 / hummingbird

Real time web analytics using node.js and web sockets

HUMMINGBIRD

Site tracking and analytics storage

Description

Hummingbird serves a 1x1 tracking pixel to users. In the browser's GET request it sends back tracking data generated by javascript.

Requirements

• node.js v0.8.0

Installation

git clone git://github.com/mnutt/hummingbird.git
cd hummingbird

# Use npm to install the dependencies
npm install

# To use the map, download MaxMind's GeoIP database and extract to the root directory:
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
gunzip GeoLiteCity.dat.gz

Running Hummingbird

To start the analytics server, run the following:

node server.js

By default a dashboard will be run on port 8080. You can disable it for production use in config/config.js. The dashboard is just html served out of public/; you can serve it using any webserver.

Deployment

Make sure to properly secure the dashboard if you don't want outside people to see it. This typically means putting the dashboard behind nginx or apache using basic auth. The dashboard's 'listen' function takes a second argument that is the interface to bind; typically you would choose "127.0.0.1" to only allow access from localhost, or "0.0.0.0" to listen on all interfaces. You should then run the tracking pixel on a different port so that it is accessible to the outside world.

Architecture Overview

Hummingbird is organized into two parts: a node.js-based tracking server that records user activity via a tracking pixel, and a collection of javascript-based widgets that display that activity. The server broadcasts all activity to the clients using Websockets if possible, and falls back to Flash sockets or long polling if necessary.

The Hummingbird.WebSocket object receives websocket events from the server in the form of JSON objects. Individual widgets subscribe to a metric and register handler functions to be called whenever that metric is present.

Logging Customization

Metrics are stored in lib/metrics and auto-loaded. Each metric contains a handler function that is called every time a new user event occurs. Metrics store data in the data object property which gets emitted to clients in intervals specified by the metric. A basic example can be found in lib/metrics/total_views.js. An example of how a metric can filter based on query params is in lib/metric/cart_adds.js.

Display Customization

Hummingbird comes with some stock widgets (Counter, Logger, Graph) that demonstrate how to hook into the data provided by the node.js server. For the minimum amount required to create a widget, see public/js/widgets/logger.js. A widget is an object whose prototype extends Hummingbird.Base and implements onMessage.

Specs

sudo gem install jspec
jspec run --node

Tips

• To run the UI locally but stream data from your production server, use the url http://localhost:8080/?ws_server=your-host.com&ws_port=12345

Contributors

• Michael Nutt [email protected]
• Benny Wong [email protected]

License

Hummingbird is licensed under the MIT License. (See LICENSE)