TraceView

This add-on is operated by AppNeta, Inc.

Application Performance Insight

TraceView

Last Updated: 07 April 2014

Table of Contents

Ruby TraceView

TraceView is an add-on 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.)

Provisioning the add-on

TraceView can be added to your application via the add-on marketplace, 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.

$ 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!

Using with Sinatra

You can instrument your Sinatra application by adding the following code to your config.ru Rackup file:

# 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!

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:

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!

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:

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

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, or use the CLI.

Heroku app manager

Simply visit the Heroku apps web interface 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.

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 to automatically log deployment annotations in TraceView every time you push new code to Heroku.

See this post 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:

To double-check that the add-on is installed, you can run the heroku addons CLI command for your application:

$ heroku addons
=== pwpush Configured Add-ons
traceview:einstein

Selecting the right TraceView plan

Solvay Conference 1927

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 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 - we have plans for that.

Full plan descriptions are available on the add-on page.

Section image source.

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.

Support

Any support issues or product feedback? Reach out via email or IRC: traceviewsupport@appneta.com or on Freenode at #appneta . Documentation is available at TraceView Support and in the Github repository.