Tronprint¶ ↑

“The Grid: a digital frontier. I tried to picture clusters of information as they moved through the computer. Ships, motorcycles… Were the circuits like freeways? I kept dreaming of a world I’d never see. And then, one day, I got in!”

-Flynn

Tronprint helps you visualize the carbon footprint of all of those little Ruby processes zooming around on your system in their light cycles. You can then show this footprint to the world of the Users via Rails helpers.

The emission estimates are calculated using Brighter Planet CM1, the impact estimate web service from Brighter Planet. Specifically, the computation emitter is used.

<img src=“https://secure.travis-ci.org/brighterplanet/tronprint.png” />

If you haven’t already, go to keys.brighterplanet.com and sign up for an API key. Non-commercial use of CM1 is free, but commercial use is charged per-query. Heroku users are charged per-month.

Add tronprint to your Gemfile:

gem 'tronprint'

And install the gem from the command line:

bundle update

Once you start your Rails app, Tronprint will automatically begin collecting usage data. If you have multiple Rails processes running, Tronprint will keep track of aggregate statistics for all processes. This is where Tronprint.application_name comes into play. By default, your application’s directory name is used.

In order to display your application’s footprint, you can use Tronprint’s built-in view helper: TronprintHelper. Feel free to cache your footprint to minimize the number of API requests made to CM1.

In whichever controller(s) that will use TronprintHelper (or in ‘ApplicationController`), simply require the helper:

class FoosController
  helper TronprintHelper
end

TronprintHelper comes with a few helper methods:

• footprint_badge - A badge that displays total footprint and current rate of emissions for your app.

• cm1_badge - Displays a CM1 badge

• footprint_methodology - A URL for a live methodology statement reporting how your total footprint was calculated. Example

Tronprint is available as a Heroku add-on. Add tronprint to your app, and your app will have an environment variable provided: ‘ENV`.

The tronprint gem will handle API key setup for you, but you will still need to configure your app to store statistics in a persistent data store. By default, Tronprint will use the yaml storage option, but this won’t fly on Heroku. The easiest way to get up and running is to add the MongoHQ add-on to your app. Once you have MongoHQ set up, configure tronprint with a Rails initializer:

1. Open a new file, ‘config/initializers/tronprint.rb`

2. In it, write:

Tronprint.aggregator_options = {
  :adapter => :mongodb,
  :uri => ENV['MONGOHQ_URL'],
  :collection => 'tronprint'
}

If you’d like to use your Rails app’s existing ActiveRecord datastore for storing Tronprint statistics, simply add the following to a new file, config/initializers/tronprint.rb:

Tronprint.aggregator_options = { :adapter => :active_record }

Tronprint automatically creates a storage table, ‘moneta_store` the next time your app is run.

If you need to create the table manually, add to your Rakefile:

require 'tronprint/rake_tasks/active_record'

And run ‘rake tronprint:moneta`

Tronprint will work with any Ruby app, but you have to do a little self-configuration.

When your application has started, all you have to do is make a call to Tronprint.run. This starts up a thread that collects statistics at a certain interval and stores the results in a key/value store.

To retrieve the footprint, make a call to Tronprint.statistics.emission_estimate.

You can also call Tronprint.statistics.impact. This returns a Hashie::Mash per the carbon gem RDoc.

There are several properties of Tronprint that can be configured. The configuration is persisted in ‘pwd`/config/tronprint.yml. Here is a list of options that can be set:

:zip_code

The ZIP code where the server or host computer resides.

:brighter_planet_key

Your Brighter Planet CM1 key. Get one from keys.brighterplanet.com.

:application_name

The name of your application.

:aggregator_options

A hash of options to send to the aggregator. A sub-option of :adapter is required. This corresponds to the name of an adapter supported by moneta. All other sub-options given are passed on to the moneta adapter’s initializer.

Tronprint needs to write the statistics it collects to a persistent data store. There are two ways to configure this.

The first way is to edit config/tronprint.yml as mentioned above.

The second way is to manually set the aggregator options before Tronprint.run is called. In Rails, this can be done with an initializer. Just set Tronprint.aggregator_options to the options you would normally set in config/tronprint.yml.

You can see an example Rails app using tronprint at github.com/brighterplanet/yaktrak. Files of note: ‘config/initializers/tronprint.rb`, `Gemfile`, `app/views/trackings/_form.html.rb`. The live example is at yaktrak.org

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright © 2010 Brighter Planet. See LICENSE for details.