= 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!"

-Floyd

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 {CM1}[http://carbon.brighterplanet.com],
{Brighter Planet's}[http://brighterplanet.com] carbon emissions calculation service.
Specifically, the {computation emitter}[http://carbon.brighterplanet.com/models/computation] 
is used.

== Getting Started

If you haven't already, go to http://keys.brighterplanet.com and sign up for an
API key. Non-commercial use of CM1 is free, but commercial use is 
{charged}[http://carbon.brighterplanet.com/pricing] per-query. Heroku users are 
charged per-month.

=== Rails

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.

==== Heroku

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

The tronprint gem will handle API key setup for you, but you will still 
need to configure your app to store statistics in MongoDB.

The easiest way to get started on Heroku is to sign up for a free MongoHQ 
account to be used for the Tronprint::Aggregator. Since Heroku doesn't 
allow access to the filesystem, Tronprint::Aggregator's default YAML 
storage option will not work. Once you have MongoDB set up, configure 
tronprint with a Rails initializer:

1. Open a new file, config/initializers/tronprint.rb
1. In it, write: 
  Tronprint.aggregator_options = {
    :adapter => :mongodb,
    :uri => ENV['MONGOHQ_URL'],
    :collection => 'tronprint'
  }

=== Other Ruby Apps

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.emission_estimate. This 
returns an instance of {Carbon::EmissionEstimate}[https://github.com/brighterplanet/carbon/blob/master/lib/carbon/emission_estimate.rb].
It can be converted to a float for the amount in kilograms or other 
methods, such as EmissionEstimate#methodology can provide a link to the 
methodology statement used to derive the estimate.

== Configuration

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}[http://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}[http://github.com/dkastner/moneta]. All other sub-options given are passed on to the moneta adapter's initializer.

=== Configuring the aggregator

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.

== Examples

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

== Note on Patches/Pull Requests

* 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

Copyright © 2010 Brighter Planet. See LICENSE for details.