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: 4.2+

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.

Rails 3.0+ should work, but is no longer actively supported.


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

IMPORTANT: The following steps should be performed in your local development environment.
  1. Add Skylight to your Gemfile. Be sure to include it in all of your environments.
    # Gemfile
    gem "skylight"
  2. Get your setup token from

  3. Then run the following commands in your terminal:
    bundle install
    bundle exec skylight setup <setup token>

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

  4. Deploy your application to production.

See the information about individual installations below to find out how to run the agent in the environments you care about.

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.

Manual App Creation

In some cases, you might need to set up an app on Skylight manually, including if you’re using the Phoenix agent. Manual app creation is a way of setting up an app in Skylight without having to run bundle exec skylight setup <setup token>, and can be an easier way of setting up multiple environments without having to create temporary directories.

In order to manually create an app on Skylight, you must first enable the manual app creation beta feature. After enabling this feature, you can navigate to your app’s setup screen, and click the “Or create the application manually.” link towards the bottom of the page. Then, you’ll be able to type in the name of your new app.

Screenshot of adding an app manually

Next, you will need to set the authentication token for your application. You will find your app’s authentication token on your app’s settings page.

Screenshot of adding an app manually

There are two ways to set the auth token for your Skylight app. One option is to create a config/skylight.yml file, and set the authentication token for your new app within it.

# The authentication token for the application.
authentication: <authentication token>

Alternatively, you can set the token as the SKYLIGHT_AUTHENTICATION environment variable, in which case you will not need to create a config/skylight.yml file.

Once you have set an auth token in either one of these two ways, you can deploy your application to production. After deploying, be sure to check your Skylight dashboard; you should begin seeing request data appear shortly!

Agent Configuration

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

# The authentication token for the application.
authentication: <authentication token>

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

Setting Configuration Variables

Add additional configuration options to config/skylight.yml. This configuration file will be parsed as ERB so you can add additional logic if desired.

Alternatively, configuration can be set via environment variables. In general, the ENV variables are capitalized versions of the YAML versions prefixed with SKYLIGHT_.

See also: Environment-Specific Configuration

General Options

Setting Authentication Tokens

The authentication token is required when reporting data back to the Skylight service. You can find your authentication token on your app settings page under “Your Apps” or “Shared Apps.”

# The authentication token for the application.
authentication: <authentication token>

Or set the SKYLIGHT_AUTHENTICATION environment variable.

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:

# config/skylight.yml
  - HeartbeatController#status
  - 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. You can find the name in the Skylight endpoints list if you’re unsure.

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


You can not add an endpoint name using a wildcard like ControllerName#*. We generally discourage folks from ignoring any endpoints that are not heartbeat endpoints, as it can reduce the usefulness of Skylight. If you don’t think an endpoint is going to be a problem, but then you ignore it, you won’t know that it’s causing an issue until it’s too late!

Log File

To change the location of the Skylight log:

# config/skylight.yml
log_file: log/skylight.log

Or set the SKYLIGHT_LOG_FILE environment variable. By default the log can be found at log/skylight.log with Rails or STDOUT otherwise.

Daemon Socket 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.

# config/skylight.yml
# Path to store daemon-related temporary files
daemon.sockdir_path: /var/run/myapp

Deploy Tracking

Skylight’s deploy tracking feature allows you to see your deployments marked on the Response Timeline

If You Deploy a Git Repository

If you deploy a git repository, deploy tracking should Just Work™ (not actually trademarked). You can, however, override the default deploy id, git sha, and deploy descriptions with configuration variables as shown below.

If You Use Heroku

You may need to enable Heroku’s Dyno Metadata feature in order to send deploy information to Skylight.

Manual Configuration

If you don’t deploy a git repo (e.g. you use a script that copies your files onto a server or a non-git VCS), deploy tracking will not be automated. Instead, you’ll need to manually configure Skylight to track your deployments:

# config/skylight.yml
  # Set an id and/or a sha. If no id is provided, the sha will be used.
  id: <%= some_code_that_returns_a_unique_id %>
  git_sha: <%= some_code_that_returns_the_sha %>
  # The deploy description is optional.
  description: <%= some_code_that_returns_a_description %>

Screenshot showing deploy tracking variables

Alternatively, you can set SKYLIGHT_DEPLOY_ID, SKYLIGHT_DEPLOY_GIT_SHA, and SKYLIGHT_DEPLOY_DESCRIPTION as environment variables.

Pro Tip: If you link your app to GitHub and provide a valid git sha, you can leave the description blank. We’ll get it for you from GitHub!
IMPORTANT: If you override one of these variables, our server will assume they are all overridden. For example, if you deploy with Heroku and override your deploy descriptions, you’ll also need to override the deploy id and/or sha.


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:

# config/application.rb
config.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:

# config/application.rb
config.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. For a full list of probes see our Available Instrumentation Options. You may also want to learn more about how probes work.

You can add additional probes in your Rails config:

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

In the event that you want to disable a probe that is on by default, you can also remove it from the list:

# config/application.rb
config.skylight.probes -= ['middleware']

If you’re not using Rails, you can require probes instead:

require 'skylight/probes/PROBE_NAME'

Middleware Stack

By default, Skylight is positioned at the top of the middleware stack. You can check Skylight’s position in the middleware stack by running rake middleware. In the unlikely event that you need to change this, you can require Skylight in a specific location in the middleware stack:

# config/application.rb

# To give Skylight a specific index:
config.skylight.middleware_position = 0 # default

# To position Skylight before a specific middleware:
config.skylight.middleware_position = { after: MiddlewareName }

# To position Skylight after a specific middleware:
config.skylight.middleware_position = { before: MiddlewareName }


In Rails

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

# config/application.rb
config.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:

configure :production do
  require "skylight/sinatra"

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

Skylight.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.10+, it works out of the box with no further configuration! Congrats!

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:

require "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:

require "skylight"
# If you’re running grape 0.10 - 0.12 or earlier, you’ll also
# need to explicitly require the probe:
require "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:

Skylight.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:

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

Environment-Specific Configuration

Any variable can be scoped to an environment’s namespace and will take precedence over a default.

IMPORTANT: Currently, environment-specific configuration is correctly utilized only in Rails apps.
# config/skylight.yml
  authentication: <production auth token>

  authentication: <staging auth token>

For an alternative method of creating multiple environments, check out our manual app creation beta feature.

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.