[TraceView](http://addons.heroku.com/traceview) is an [add-on](http://addons.heroku.com) for full-stack application performance insight. Adding TraceView to an application provides deep performance monitoring. * Understand application architecture, and issues’ root cause, in a single glance. * Isolate interesting calls and drill down to line of code and dyno it ran on. * Drill down on spikes in latency, even if the cause is only a single outlying request. TraceView is integrated tightly with Heroku for easy access via your Heroku account and supports Ruby-based applications on Heroku. (Elsewhere, we also support Java, PHP, and Python.) __Note: Our addon currently has an issue on the Heroku `cedar-14` stack where no performance metrics are generated. Users on the Heroku `cedar` stack are unaffected. We're working on this issue and plan to have a fix out soon. If you have any questions, please open a support ticket or contact us directly at traceviewsupport@appneta.com.__ ## Provisioning the add-on TraceView can be added to your application via the [add-on marketplace](https://addons.heroku.com/traceview), or via the CLI. ### CLI TraceView can be added to a Heroku application via the CLI: A list of all plans available can be found [here](http://addons.heroku.com/traceview). $ heroku addons:add traceview:beaker -----> Adding traceview to sharp-mountain-4005... done, v18 (free) After adding TraceView add-on to the application, it should be configured to fully integrate with the add-on. ## Using with Rails 2.3 - 4.x Ruby on Rails applications will need to add the following entry into their `Gemfile` specifying the TraceView instrumentation gem. gem 'oboe-heroku' Update application dependencies with bundler. $ bundle install $ git commit -am "Update Gemfile for Appneta's TraceView addon." $ git push heroku master And that's it! _Note: If you're running a forking webserver such as Unicorn, remember that there is an [extra step](#forking-webservers)!_ ## Using with Sinatra You can instrument your Sinatra application by adding the following code to your `config.ru` Rackup file: ```ruby # If you're not using Bundler.require. Make sure this # is done after the Sinatra require directive. require 'oboe-heroku' # You may want to replace the Oboe.logger with whichever # logger you are using # Oboe.logger = Sinatra.logger ``` Make sure that the oboe gem is loaded _after_ Sinatra either by listing `gem 'oboe-heroku'` after Sinatra in your Gemfile or calling the `require 'oboe-heroku'` directive after Sinatra is loaded. With this, the oboe-heroku gem will automatically detect Sinatra on boot and instrument key components. _Note: If you're running a forking webserver such as Unicorn, remember that there is an [extra step](#forking-webservers)!_ ## Using with Padrino As long as the oboe-heroku gem is in your `Gemfile` (inserted after the `gem 'padrino'` directive) and you are calling `Bundler.require`, the oboe-heroku gem will automatically instrument Padrino applications. If you need to set `Oboe::Config` values on stack boot, you can do so by adding the following to your `config/boot.rb` file: ```ruby Padrino.before_load do # The oboe Ruby client has the ability to sanitize # query literals from SQL statements. By default # this is disabled. Enable to avoid collecting and # reporting query literals to TraceView. # Oboe::Config[:sanitize_sql] = true # Verbose output Oboe::Config[:verbose] = true end ``` _Note: If you're running a forking webserver such as Unicorn, remember that there is an [extra step](#forking-webservers)!_ ## Need to profile a custom bit of code? The TraceView Ruby instrumentation offers the ability to profile any arbitrary block of code using the following code pattern: ```ruby # A layer name that will identify this performance # data in the TraceView dashboard layer = "code_block_1" # You can report any related data by populating # a hash with key-value pairs report_kvs = { :id => @id } Oboe::API.trace(layer, nil, report_kvs) do x = "This is a string" y = x.reverse z = y.reverse puts z end ``` More details can be found [here](https://github.com/appneta/oboe-ruby#custom-tracing). ## Accessing the TraceView Dashboard TraceView collects performance information about your application, then makes it available in real-time. To see the data, you can head to your [Heroku app manager](http://heroku.com/myapps), or use the CLI. ### Heroku app manager Simply visit the [Heroku apps web interface](http://heroku.com/myapps) and selecting the application in question. Select TraceView from the Add-ons menu. ### CLI To open TraceView from your Heroku CLI tools: $ heroku addons:open traceview Opening traceview for sharp-mountain-4005... ## Forking Webservers ### Unicorn If you are using the TraceView add-on with Unicorn, you should add the `preload_app true` directive in your Unicorn configuration file or TraceView may not be able to fully initialize and instrument your application. You should also add in before and after hooks so that TraceView can instrument properly after a fork operation. This involves simply calling `::Oboe.disconnect!` and `::Oboe.reconnect!` in the `before_fork` and `after_fork` hooks respectively. An example Unicorn configuration file can be found in this Github [gist](https://gist.github.com/pglombardo/5884933). ## Deploy Hooks To help understand the correlation between system events and performance trends, TraceView provides the ability to log arbitrary events to your TraceView dashboard. You can use Heroku’s [Deploy Hooks add-on](https://addons.heroku.com/deployhooks) to automatically log deployment annotations in TraceView every time you push new code to Heroku. See [this post](http://www.appneta.com/blog/heroku-deployment-hook/) for details on how to quickly add this functionality to your Heroku/TraceView application. ## Troubleshooting Having trouble getting set up with TraceView? Not seeing something you expected, or seeing something you didn't? Here's three ways to get help: * The TraceView [Knowledge Base](http://support.tv.appneta.com) has documentation covering the [Ruby instrumentation and common questions](https://support.tv.appneta.com/support/solutions/articles/86393-installing-ruby-instrumentation-for-ruby-rails-sinatra-or). * You can reach our support engineers via email or IRC: [traceviewsupport@appneta.com](mailto:traceviewsupport@appneta.com) or on Freenode at #appneta . * TraceView Ruby instrumentation is open-source! Contact us on [Github](https://github.com/appneta/oboe-ruby), browse the code, view commit history and/or file an issue in our [oboe-ruby repository](https://github.com/appneta/oboe-ruby/issues). To double-check that the add-on is installed, you can run the `heroku addons` CLI command for your application: ```sh $ heroku addons === pwpush Configured Add-ons traceview:einstein ``` ## Selecting the right TraceView plan  TraceView plans are based on the number of dynos being monitored. The plans start with the free Beaker plan (up to 3 dynos), which is full-featured except for limited data retention (1 hour) and no alerting. The other plans, named for scientists more famous (or at least more professional) than [Beaker](http://en.wikipedia.org/wiki/Beaker_\(Muppet\)) are full-featured with 45 days of data retention and alerting. The plans are priced based on the number of dynos your application uses. We provide a number of tiers of service, each covering up to a certain number of dynos. You can match up the number of dynos your application uses to find the appropriate plan tier. **If you're autoscaling, or wish to monitor a large number of dynos, please [contact us](mailto:traceview@appneta.com) - we have plans for that.** Full plan descriptions are available on the [add-on page](http://addons.heroku.com/traceview). Section [image source](https://en.wikipedia.org/wiki/File:Solvay_conference_1927.jpg). ### Migrating plans As you adjust the number of dynos your application uses, you may wish to upgrade or downgrade your TraceView plan. Use the `heroku addons:upgrade` command to migrate to a new plan. $ heroku addons:upgrade traceview:feynman -----> Upgrading traceview:feynman to sharp-mountain-4005... done, v18 ($49/mo) Your plan has been updated to: traceview:enterprise ## Removing the add-on TraceView can be removed via the CLI. $ heroku addons:remove traceview -----> Removing traceview from sharp-mountain-4005... done, v20 (free) **Your TraceView data will only be available for a short time after add-on removal. Re-adding the add-on will re-enable access.** Before removing TraceView you can export collected performance data using the [Data API](http://dev.appneta.com/docs/api-v2/). ## Support Any support issues or product feedback? Reach out via email or IRC: [traceviewsupport@appneta.com](mailto:traceviewsupport@appneta.com) or on Freenode at #appneta . Documentation is available at [TraceView Support](http://support.tv.appneta.com/) and in the [Github repository](https://github.com/appneta/oboe-ruby).