Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
206 lines (123 sloc) 5.52 KB


Pathways allows you to see the pathways that users are using within your application. When we can see the flows through the app then we can pave the cowpaths and validate the features that we build.

Pathways uses your default Rails logger to store the information from a successful response so it doesn't slow our request/response cycle. We can then parse the logfile and store the results in a MongoDB database at a later date.

It has been created by those delightful fellows at Mint Digital.

Another set of Metrics?

Pathways was created so that we can understand the impact of our development on the behaviour of our users. Metrics shouldn't just be about page view counters it should understand where the user has been within that viewing session. By using a non relational database like MongoDB we can map_reduce all the pages that a user visits in a session so that we can truly analyse what is going on within our applications.

The Blog Post

For the backstory, philosophy, and history of why we created Pathways, please see the blog post.


Pathways allows you to track the flow users take within your application. Each successful request is logged into your Rails.logger which can then be asynchronously parsed and stored in a MongoDB table later.

We store a user session (Pathways::Session) which has many visits (Pathways:Visit), these are MongoMapper documents which can be queried accordingly.


To start tracking the paths your users are taking all you need to do is add this to your controllers.

class ApplicationController
  include Pathways::Tracker
  after_filter :log_visit

This will create an entry in your default logfile that is later collected and parsed by Pathways.


You can also track the iteration/deployment that is currently running so that we can easily track the impact of each deployment.

class ApplicationController
  include Pathways::Tracker
  after_filter :log_visit
  Pathways::Tracker.iteration  = "iteration-001"


Now that we're tracking the paths our users take we need to parse these so that we can mine this like a mofo (note you might need to require 'pathways/parser').


This will run ever 5 seconds and create records for Pathways::Session and Pathways::Visits. By default this will look at the development.log using Rails.root.

If you want to specify the name of the logfile then you can pass it as the first parameter.


You can also control the interval (in seconds) that parser will check your logfile, the default is set to 60 seconds.


The Front End

Pathways has a huge crush on Resque, so like Resque it comes with a Sinatra-based front end for seeing the sessions users are creating in your app.


If you've installed Pathways as a gem running the front end standalone is easy:

$ pathways-web

It's a thin layer around rackup so it's configurable as well:

$ pathways-web -p 8282


Using Passenger? Pathways ships with a you can use. See Phusion's guide:

Apache: Nginx:


If you want to load Pathways on a subpath, possibly alongside other apps, it's easy to do with Rack's URLMap:

require 'pathways/server'

run \
  "/"       =>,
  "/pathways" =>

Rails 3

You can also easily mount Pathways on a subpath in your existing Rails 3 app by adding this to your routes.rb:

require 'pathways/server'
mount, :at => "/pathways"

Installing MongoDB

Pathways requires MongoDB.


If you're on OS X, Homebrew is the simplest way to install MongoDB:

$ brew install mongodb
$ mongod run --config /usr/local/Cellar/mongodb/1.8.1-x86_64/mongod.conf

You now have a MongoDB instance running on 27017.

Pathways Dependencies

$ gem install bundler
$ bundle install

Installing Pathways

In a Rails 2.x app, as a gem

First install the gem.

$ gem install pathways

Next include it in your application.

$ cat config/initializers/load_pathways.rb
require 'pathways'

Now start your application:

$ ./script/server

Ta da! Your application is now logging the pathways your users make.

In a Rails 3 app, as a gem

First include it in your Gemfile.

$ cat Gemfile
gem 'pathways'

Next install it with Bundler.

$ bundle install

Now start your application:

$ rails server

Ta da! Your application is now logging the pathways your users make.


Once you've made your great commits:

  1. Fork Pathways
  2. Create a topic branch - git checkout -b my_branch
  3. Push to your branch - git push origin my_branch
  4. Create a Pull Request from your branch
  5. That's it!



Simon Reed :: :: @simonreed