https://github.com/faradayio/tronprint

Estimate your Ruby application's carbon footprint
https://github.com/faradayio/tronprint

Last synced: 3 months ago
JSON representation

Estimate your Ruby application's carbon footprint

• Host: GitHub
• URL: https://github.com/faradayio/tronprint
• Owner: faradayio
• License: mit
• Created: 2010-12-22T23:38:44.000Z (over 15 years ago)
• Default Branch: master
• Last Pushed: 2012-09-06T15:22:24.000Z (almost 14 years ago)
• Last Synced: 2025-01-22T21:47:34.982Z (over 1 year ago)
• Language: Ruby
• Homepage: http://brighterplanet.github.com/tronprint
• Size: 3.52 MB
• Stars: 11
• Watchers: 4
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.rdoc
  • License: LICENSE

Awesome Lists containing this project

README

          
= 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}[http://impact.brighterplanet.com], the impact estimate web service from {Brighter Planet}[http://brighterplanet.com].

Specifically, the {computation emitter}[http://impact.brighterplanet.com/models/computation] 

is used.

{}[http://travis-ci.org/brighterplanet/tronprint]

== 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://impact.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.

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

  class FoosController

    helper TronprintHelper

  end

==== Helper Methods

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}[http://impact.brighterplanet.com/computations?duration=128372]

==== 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 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`

1. In it, write: 

  Tronprint.aggregator_options = {

    :adapter => :mongodb,

    :uri => ENV['MONGOHQ_URL'],

    :collection => 'tronprint'

  }

==== ActiveRecord

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`

=== 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.statistics.emission_estimate.

You can also call Tronprint.statistics.impact. This returns a +Hashie::Mash+ per {the carbon gem RDoc}[http://rdoc.info/github/brighterplanet/carbon].

== 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.