Project

charted

0.0
No commit activity in last 3 years
No release in over 3 years
A Sinatra app for tracking web traffic on multiple sites.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 5.4
~> 0.6
~> 1.3

Runtime

~> 0.0
~> 1.4
~> 1.10
~> 4.12
~> 1.4
~> 0.10
 Project Readme

Description

Charted is a minimal web traffic analytics app.

Installation

$ gem install charted

Also install the relevant database adapter, depending on which db you plan to use:

$ gem install dm-mysql-adapter

Setup a config.ru file and run it like any other Sinatra application.

require 'rubygems'
require 'charted'

Charted.configure do |c|
  c.delete_after 365                             # only keep a years worth of data
  c.error_email  'john@mailinator.com'           # production exceptions are sent here
  c.sites        ['hughbien.com', 'example.com']
  c.db_options(                                  # database config
    adapter:     'postgres',
    host:        'localhost',
    username:    'root',
    password:    'secret',
    database:    'charted')
  c.email_options(                               # error email config (see Pony gem for options)
    from:        'errors@mailinator.com',
    via:         :smtp,
    via_options: {host: 'smtp.example.org'})
end

run Charted::App if !ENV['CHARTED_CMD']

Stick this in your bashrc or zshrc:

CHARTED_CONFIG='/path/to/config.ru'

Then initialize the database:

$ charted --migrate

The app should be mounted to /charted path on your domain

In your app, generate a charted.js file. This can be safely concatenated with you other JavaScript assets.

$ charted --js > /path/to/my/project/public/charted.js

Updating

$ gem install charted

You may need to generate a charted.js file again:

$ charted --js > /path/to/my/project/public/charted.js

Usage

The web application is for end users, to get information about your traffic use the included command line application.

$ charted --site hugh # just needs the first few letters
+-------+--------+--------------------------------------+
| Total | Unique | Visits                               |
+-------+--------+--------------------------------------+
| 7,012 |  5,919 | February 2013                        |
| 6,505 |  4,722 | January 2013                         |
| 5,342 |  3,988 | December 2012                        |
...

Basic tracking of common stats like visits, referrers, or user agents are done automatically. You can also track events, conversions, and experiments.

Events can be recorded with JavaScript:

Charted.events("1st Button Clicked");
Charted.events("1st Button Clicked", "2nd Button Clicked");

To start a conversion, you'll need to set the data-conversions attribute of the <body> element:

<body data-conversions="RSS Subscribed; Item Purchased">

Just separate goal names with a semi-colon. When the conversion goal has been reached:

Charted.goals("RSS Subscribed");
Charted.goals("RSS Subscribed", "Item Purchased"); // calls can be batched

Experiments use the data-experiments attribute and use the format experiment: bucket1, bucket2, ...:

<body data-experiments="Buy Button: Blue, Green, Red">

The included JavaScript will automatically select a bucket for this user and append a relevant class name to the <body> element like:

<body class="buy-button-green">

The class name is just the experiment label and bucket lowercased with spaces replaced with dashes. Use CSS to tweak the buy button. When a user clicks on a button, use JavaScript to send a message to the server:

Charted.goals("Buy Button");

Running charted --clean will prune the database of old data. I recommend putting this as a cronjob. It can also be used to remove bad entries in the events/conversions/experiments table:

charted --clean "Buy Button"

Rack Extensions

I recommend using these extensions with Charted:

Development

Put this in your zshrc or bashrc:

export CHARTED_CONFIG="/path/to/charted/config.ru"

Then run:

$ bin/charted --migrate
$ shotgun

Head on over to http://localhost:9393/charted/prime.html. This is where recordings should occur.

Tests are setup to run via ruby test/*_test.rb or via rake.

TODO

  • handle case where visitor visits "/charted" or any other route directly (bad input)
  • record/display uniques for pages, etc... perhaps --unique option
  • add --limit NUMBER to limit number of rows per table outputted
  • add date range options (--start "3 days ago" --end "1 day ago")

License

geoip.dat is provided by MaxMind at http://dev.maxmind.com/geoip/geolite.

Copyright Hugh Bien - http://hughbien.com. Released under BSD License, see LICENSE.md for more info.