Advanced Setup

Install, configure, and deploy the agent.

Supported Frameworks

Skylight has built in integration for Rails, Sinatra, and Grape. We also offer beta support for Phoenix!


Minimum: 3.0+

Skylight utilizes Rails’ Railties to autoload. It then watches the built ActiveSupport::Notifications to get information about controller actions, database queries, view rendering, and more.


Minimum: 1.2+

Not running Rails? We also support Sinatra apps, though the default instrumentation will be less detailed. By default, we’ll recognize your Sinatra routes and also instrument any supported gems. You can also add custom instrumentation).


Minimum: 0.10+, Preferred: 0.13+

We support Grape standalone as well as embedded in Rails and Sinatra. We recognize endpoints and instrument rendering and filters. As of version 0.13, ActiveSupport::Notifications is built-in to Grape making the instrumentation even more streamlined.

Phoenix (Beta)

While we still love Ruby, we know that a number of users have been exploring Phoenix as an alternative to Ruby and Rails. To that end we’ve been working on a version of the Skylight agent for Phoenix. You can find that on Github right now. It should work, though it’s definitely in an early state.

In order to create a Phoenix app in Skylight, you’ll need to enable our manual app creation beta feature. In Ruby apps, you can run bundle exec skylight setup but there’s no Phoenix equivalent yet. After enabling this feature, when you go to the Setup screen you can manually create a new app to connect to your Phoenix agent.

If you give the Phoenix agent a try, we’d love to hear how that goes. We’re pretty excited about it!


Ruby Version

Minimum: 1.9.2+, Preferred: 2.1+

The agent will run with 1.9.2+. However, 2.1+ is required for memory allocation tracking.

For the curious, our CI currently is testing against these versions. Intermediate versions are expected to work as well.

Server Requirements

We aim to support all *nix servers. Just add the gem to your Gemfile, add the configuration, then deploy as you normally would. You can also run the agent locally on OS X for testing, if desired.

The agent runs great on Heroku. No special actions required.

Installing the Agent

Note: See the information about individual installations below to find out how to run the agent in the environments you care about.
  1. Add Skylight to your Gemfile. Be sure to include it in all of your environments.
    1# Gemfile
    2gem "skylight"
  2. Get your setup token from

  3. Then run:
    bundle install
    bundle exec skylight setup {SETUP_TOKEN}

    This will automatically generate your config/skylight.yml file.

Deploying the Agent

Once you’ve run skylight setup you’ll need to get the configuration to your server. For this you have two options:

  1. Check in the config/skylight.yml file (which is automatically generated and includes the necessary auth token) OR
  2. Set the appropriate ENV vars, at the minimum SKYLIGHT_AUTHENTICATION. See below for more information.

After this, all you need to do is run your standard deployment process.


For Heroku, setup is as simple as setting the desired ENV vars and pushing your repo. Nothing fancy required!

To make your Skylight API token available:

heroku config:set SKYLIGHT_AUTHENTICATION="<token>"

Note that changing a config var in Heroku will cause your application to restart. Once the app has restarted and handled several requests, you should begin seeing performance data about your application in Skylight.

For more information about setting Heroku config vars, see Configuration and Config Vars in the Heroku documentation.

Agent Configuration

The only thing you need to set is the authentication token, but there are a number of other configuration options available.

Setting Configuration Variables

The automatically generated configuration file config/skylight.yml looks like this:

 2# The authentication token used when reporting data back to the
 3# Skylight service.
 5# Required in production.
 6authentication: <authentication token>
 8# Path to the Skylight log file
 9log_file: log/skylight.log
11# Path to store daemon-related temporary files
12daemon.sockdir_path: /var/run/myapp
14# Environment specific configuration. Any variable can be scoped by
15# an environment and will take precedence over a default.
16# NOTE: Currently this is only correctly utilized in Rails apps.
18  authentication: <production auth token>
21  authentication: <staging auth token>

The configuration file will be parsed as ERB so you can add additional logic if desired.

Alternatively, configuration can be set via ENV vars. In general, the ENV vars are capitalized versions of the YAML versions prefixed with SKYLIGHT_, e.g. SKYLIGHT_AUTHENTICATION, SKYLIGHT_LOG_FILE.

General Options

authentication (required) — The authentication token for the app. Available on the application settings page under the ‘Apps’ section.

log_file — Change the location of the Skylight log. By default this is log/skylight.log with Rails or STDOUT otherwise.

daemon.sockdir_path – The path where the socket file for the daemon is created. In general you will not need to change this. However, if you’re using an NFS mount (say with Vagrant) you’ll need to point this to a non-NFS location.

Ignoring heartbeat endpoints

Sometimes, an endpoint exists solely for your load-balancer to determine whether your Rails process is up. If you would like to ignore this endpoint, you can set the ignored heartbeat endpoint as follows:

1# config/skylight.yml
3  - HeartbeatController#status
4  - OtherController#heartbeat

Once configured, Skylight will not collect instrumentation and requests to this endpoint will not be counted in the application’s usage or be represented as part of the application’s aggregated response time and RPM graphs.

The name of the endpoint can be found in the endpoints list on your Skylight application dashboard. For Rails actions, it will be Controller#action, for Sinatra it will be VERB path, and for Grape it will be Module [VERB] path. Always use the name in the Skylight endpoints list if you’re unsure.

Alternatively, you may add the SKYLIGHT_IGNORED_ENDPOINTS environment variable. For example:



There are additional configuration options that can be set in the Rails environment. Unless otherwise noted, these settings should be added to config/application.rb. Do not attempt to set them via initializers as Skylight starts before initializers are run.

Skylight performs setup when the gem is required, at which time Rails will be detected and tapped into. However, you may find you have to manually require skylight/railtie if you need to load the Skylight gem before Rails.


By default, the Skylight agent only enables itself in the production Rails environment. If, for example, you wish to enable Skylight in staging, you can do the following:

1# config/application.rb
2config.skylight.environments += ["staging"]

Also be sure and check out the rest of our documentation on setting up multiple environments.


Perhaps you might want to tell Skylight to use a specific logger. This can be achieved like this:

1# config/application.rb
2config.skylight.logger =


In order to instrument other libraries outside of Rails, the agent includes probes which are only activated if the related files are required. Since this is an experimental feature, it’s opt-in for now.

We currently have probes for Net::HTTP, ActionView, Grape, Excon, Redis, ActiveModel::Serializers, Moped, Mongo, Sinatra, Tilt, and Sequel.

The Net::HTTP, ActionView, and Grape probes are enabled by default.

To enable other probes:

1# config/application.rb
2config.skylight.probes += %w(excon redis active_model_serializers)

See Getting More From Skylight to learn more about the probes.


In Rails

If your Sinatra app is mounted in Rails, all you have to do is require the correct probes:

1# config/application.rb
2config.skylight.probes += %w(sinatra tilt sequel)

See the Rails configuration instructions for more information.


Skylight works just as well in standalone Sinatra apps, though the instructions are just a touch more involved.

Sinatra apps usually do not require all gems in the Gemfile, so you will want to explicitly require Skylight. You will also need to boot up the Skylight agent explicitly. You generally do not want to run Skylight in development mode, so you will want to specify its use in the :production environment:

1configure :production do
2  require "skylight/sinatra"
3  Skylight.start!

NOTE: if you want to load your configuration from a file instead of from ENV, you can use:

1Skylight.start!(file: PATH_TO_CONFIG)

You don’t need to install any middleware manually, or do anything with unicorn forking settings.

Note: Padrino is not currently supported as it differs from base Sinatra in some significant ways. We are investigating adding support in future releases.


On Rails

If your Grape app is mounted in Rails and is version 0.13+, it works out of the box with no further configuration! Congrats!

If you’re running 0.10 - 0.12 all you have to do is require the following probe:

1# config/application.rb
2config.skylight.probes += ["grape"]

See the Rails configuration instructions for more information.

On Sinatra

If your Grape app is mounted in a Sinatra app, first follow the Sinatra instructions.

If you’re running Grape 0.13+, that’s all you need to do. For versions 0.10 - 0.12, you’ll also want to add this to your main file:

1require "skylight/probes/grape"


Grape apps usually do not require all gems in the Gemfile, so you’ll want to begin by adding a line like this to your main file:

1require "skylight"
2# If you’re running grape 0.10 - 0.12 or earlier, you’ll also
3# need to explicitly require the probe:
4require "skylight/probes/grape"

You will also need to boot up the Skylight agent explicitly.


If you want to load your configuration from a file instead of from ENV, you can use:

1Skylight.start!(file: PATH_TO_CONFIG)

Since you probably don’t want to instrument your app locally, you should set up a conditional to ensure this this is only run in production environments.

Finally, you’ll want to install the Skylight middleware in your base Grape or Rack app with:

1use Skylight::Middleware

Setting Up Multiple Environments

In many cases, your applications will have two or more production-like environments. These are typically referred to as “production” and “staging”, and you may also have “test”, “QA”, “dev”, etc. environments.

You can configure Skylight to separate data for each of these environments by creating a new application for each, then configuring Skylight to use the appropriate app on a per-environment basis.

To create a new environment, make a directory using the name you’d like:

mkdir /tmp/appname-staging
cd /tmp/appname-staging

Then follow the instructions available on the app setup screen, running them in this temporary directory instead of in your main Rails app.

If you are using Rails and have not already done so, also be sure to add the new environment to your application.rb file if you are using Rails.

This will create a new application on Skylight, using the directory name as the default. You can always change the application’s name via the Skylight web UI.

Once skylight setup has finished running, a new config/skylight.yml file will be generated containing a new application ID and authentication token.

You’ll need to configure this new environment with these new credentials.

Regenerating the App Token

If your application token may have been compromised, you can regenerate it from the settings page.

Screenshot of settings page

Once you have regenerated the token, you will need to update your production application with the new token.