Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mnutt/hummingbird

Real time web analytics using node.js and web sockets
https://github.com/mnutt/hummingbird

Last synced: 26 days ago
JSON representation

Real time web analytics using node.js and web sockets

Awesome Lists containing this project

README 

        
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 or higher



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.



Setting Up Tracking

-------------------



The file `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 `` tag.  Once you have done so,

in the footer of your page you can call



    HummingbirdTracker.track();



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:



    HummingbirdTracker.track({logged_in: true});



The data can be used within Hummingbird's metrics to filter events on the backend.



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.



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]>

 * mikecampo

 * caphrim007

 * brianjriddle

 * lbosque

 * robertjwhitney

 * Dan Thurman

 * thinkroth

 * markwillis82

 * ochronus

 * dannyakakong

 * xinbenlv



License

-------



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