This add-on is operated by Scout

Track down memory leaks, N+1s, slow code and more. For Ruby & Elixir apps.

Scout

Last updated 12 April 2017

Scout is an add-on that analyzes your Ruby and Elixir app behavior, helping you identify and resolve critical performance and stability issues like:

• Memory leaks and bloat
• Slow SQL queries and expensive N+1 logic
• Capacity issues

In many cases, Scout is able to track problems down to a line-of-code - and if the optional Git integration is enabled - the developer and commit date.

In addition to deep transaction analysis, Scout automatically tracks key performance indicators in your app, allowing you to guage your app’s health over time:

• View response times by tier (ActiveRecord, Net::HTTP, Redis, and more) to identify problems in backend services
• Identify your most expensive controller-actions
• CPU and memory usage of your app processes

Scout is distributed as a Ruby gem and Elixir Hex package.

Compatibility and requirements

• Ruby: supports Ruby on Rails 2.2+ and Ruby 1.8.7+.
• Elixir: Phoenix 1.2+ and and Elixir 1.3+.

Provisioning the add-on

Scout can be attached to a Heroku application via the CLI:

$ heroku addons:create scout
-----> Adding scout to sharp-mountain-4005... done, v18 (free)

Once Scout has been added a SCOUT_KEY setting will be available in the app configuration and will contain the the authentication key used to report metrics to your Scout account. This can be confirmed using the heroku config:get command.

Following the add-on provisioning, one additional step is required: add scout_apm to your Gemfile and deploy your application. Detailed instructions are presented in the Scout add-on dashboard. You will begin seeing metrics a couple of minutes after deploying your application.

Attaching the add-on to multiple applications

Scout can be attached to multiple applications, allowing you to view your apps from a single account. To attach Scout to another application:

$ heroku addons:attach scout
-----> Adding scout to sharp-mountain-4005... done, v18 (free)

Attaching the add-on to multiple app environments

Scout aggregates metrics by application name. By default, if you’ve attached the add-on to multiple environments, the metrics will be aggregated into a single application within Scout. Typically, it is beneficial to view your app metrics separated by environment. To monitor an app running in another environment:

$ heroku addons:attach scout
-----> Adding scout to sharp-mountain-4005... done, v18 (free)

Then, set a heroku config var with the name SCOUT_NAME:

heroku config:set SCOUT_NAME="YOUR_APP_NAME - YOUR_ENVIRONMENT"

Disabling monitoring

To turn off monitoring (for example, if you wish to disable monitoring for your staging environment), toggle the SCOUT_MONITOR Heroku config var:

heroku config:set SCOUT_MONITOR=false

Gem functionality

Once installed, the scout_apm gem will automatically instrument your app’s controller-actions and popular gems/libraries (ActiveRecord, Redis, Net::HTTP, etc). scout_apm reports timing and memory allocation metrics every minute to Scoutapp.com via a background thread.

Dashboard

The Scout dashboard is the entry point to your app’s performance analytics and Scout’s performance insights.

The dashboard can be accessed via the CLI:

$ heroku addons:open scout
Opening scout for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select Scout from the Add-ons menu.

The Scout dashboard is divided into two areas: Key Performance Indicators and Insights. More on those are below.

Key Performance Indicators

The top section of the dashboard displays an auto-refreshing view of key application health metrics. You can view metrics across a wide time range and compare performance to previous time periods.

Insights

Scout continually analyzes your app’s request behavior, identifying areas that may be leading to stability and performance issues. The result of this analysis is displayed on the dashboard beneath the key performance indicators.

Identifying memory bloat & leaks

If a user triggers a request to your application that results in a large number of object allocations (example: loading a large number of ActiveRecord objects), your app may require additional memory. The additional memory required to load the objects in memory is released back very slowly. Therefore, a single memory-hungry request will have a long-term impact on your app’s memory usage.

The Insights area of the dashboard identifies controller-actions and background jobs that have triggered significant memory increases. An overview of the object allocation breakdown by tier (ActiveRecord, ActionView, etc) is displayed on the dashboard.

Clicking on a memory-hungry endpoint listed in the Insights section of the dashboard reveals a detailed trace of object allocations:

Deploy Tracking

Scout can track deploys, making it easier to correlate changes in your app to performance.

Enable Dyno Metadata to begin tracking deploys. This adds a HEROKU_SLUG_COMMIT environment variable to your dynos, which Scout then associates with deploys.

Advanced configuration

Scout can be configured via Heroku config variables. View the configuration options for Scout.

Troubleshooting

By default, Scout logs with a WARN debug level. If you aren’t seeing metrics within the Scout interface, try the following:

1. Tail your Heroku logs, greping for the [Scout] prefix:

heroku logs --tail | grep [Scout]

2. Change the SCOUT_LOG_LEVEL config var to DEBUG. This will automatically restart your app:

heroku config:set SCOUT_LOG_LEVEL="DEBUG"

3. Check the output for any obvious errors. If you are stuck, send the output of the log stream to support@scoutapp.com along with the URL to your app (ie - https://apm.scoutapp.com/apps/ID).

Removing the add-on

Scout can be removed via the CLI.

$ heroku addons:destroy scout
-----> Removing scout from sharp-mountain-4005... done, v20 (free)

Billing

What is a “transaction”?

A transaction is a single web request or background job.

Exceeding the per-day transaction limit

If your app exceeds the per-day transaction limit for your subscription plan, transaction traces will be inaccessible for the remainder of the day. Monitoring of high-level metrics continues and trace collection resets on the following day.

Support

All Scout support and runtime issues should be submitted via one of the Heroku Support channels. We encourage you to send product feedback to support@scoutapp.com.