hummingbird

Hummingbird is a self-hosted site tracking and analytics storage server written for Node.js. It serves a 1x1 tracking pixel to visitors; the browser's GET request carries tracking data generated by a small JavaScript snippet. Requirements and installation It requires node.js v0.8.0 or higher. The README's setup steps are to clone the repository, run npm install to fetch dependencies, and optionally download MaxMind's GeoLiteCity.dat GeoIP database into the root directory if the map feature is wanted. The server is started with `node server.js`. Dashboard and deployment A dashboard runs on port 8080 by default and can be disabled for production use in config/config.js. The dashboard is plain HTML served out of public/, so any web server can host it. The README warns that the dashboard should be secured if it should not be publicly visible, typically by placing it behind nginx or apache with basic auth. The dashboard's 'listen' function accepts a second argument for the interface to bind — for example "127.0.0.1" for localhost only, or "0.0.0.0" for all interfaces — and the tracking pixel should be run on a separate port so it stays reachable from the outside world. Setting up tracking client/hummingbird.js contains a small script that triggers a Hummingbird event. It can be pasted into the page body or uploaded and referenced with a script tag. Calling HummingbirdTracker.track() with no arguments sends standard parameters such as the page URL; arbitrary data can be attached, for example HummingbirdTracker.track({logged_in: true}), and that data can be used inside Hummingbird's metrics to filter events on the backend. Architecture Hummingbird is organized in two parts: a Node.js tracking server that records user activity via the tracking pixel, and a set of JavaScript widgets that display that activity. The server broadcasts all activity to clients over WebSockets when possible, falling back to Flash sockets or long polling. The Hummingbird.WebSocket object receives WebSocket events from the server as JSON objects, and individual widgets subscribe to a metric and register handler functions called whenever that metric is present. Custom metrics and widgets Metrics live in lib/metrics and are auto-loaded. Each metric contains a handler function invoked every time a new user event occurs, and stores data in a `data` object property that is emitted to clients at intervals specified by the metric. total_views.js is given as a basic example, and cart_adds.js as an example of filtering on query parameters. Stock widgets (Counter, Logger, Graph) demonstrate how to hook into the server's data; a minimal widget example is public/js/widgets/logger.js. A widget is an object whose prototype extends Hummingbird.Base and implements onMessage. The README also notes a tip: to run the UI locally while streaming data from a production server, use an URL such as http://localhost:8080/?ws_server=your-host.com&ws_port=12345. Project notes Hummingbird is licensed under the MIT License. The README lists Michael Nutt, Benny Wong and a number of additional contributors.