Site tracking and analytics storage
- node.js v0.8.0 or higher
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
To start the analytics server, run the following:
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.
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.
Setting Up Tracking
client/hummingbird.js contains a small script to trigger a hummingbird event. You
can either paste the contents of the file into the body of your webpage or you can upload it
to your server as a .js file and reference it with a
<script> tag. Once you have done so,
in the footer of your page you can call
Called with no arguments, it will send over some standard parameters such as the page URL. You can also pass arbitrary data with the event:
The data can be used within Hummingbird's metrics to filter events on the backend.
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.
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
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.
- 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
- Michael Nutt firstname.lastname@example.org
- Benny Wong email@example.com
- Dan Thurman
Hummingbird is licensed under the MIT License. (See LICENSE)