Setting Up Stackdriver Debugger for Ruby

The Stackdriver Debugger agent for Ruby can be used to inspect the state of Ruby applications running on Google Cloud Platform, on other cloud providers, in your data centers, or on your local workstation.

Before you begin

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. Select or create a Cloud Platform project.

    Go to the Manage resources page

  3. Enable the Stackdriver Debugger API.

    Enable the API

  4. Install Ruby 2.2+ or greater.

Installing the agent

Stackdriver Debugger agent for Ruby lets you inspect the state of a Ruby application, at any code location, without stopping or slowing down the running app.

  1. Add the Stackdriver gem to your Gemfile:

    gem "stackdriver"
  2. Use Bundler to install the gem:

    bundle install

Enabling the agent

If you're using Ruby on Rails, bundler automatically loads the library into your application when it starts.

Other Rack-based applications can use the Rack Middleware provided by the library:

require "google/cloud/debugger"

use Google::Cloud::Debugger::Middleware

Pure Ruby applications can start the agent explicitly at the entry point of your application:

require "google/cloud/debugger"

Google::Cloud::Debugger.new.start

For more information on installation, see the documentation for the Stackdriver Debugger agent for Ruby. You can also report issues using the issue tracker.

Configuring the agent

You can customize the behavior of the Stackdriver Debugger agent for Ruby. See the agent configuration on GitHub for a list of possible configuration options.

Running on Google Cloud Platform

Using the Stackdriver Debugger agent for Ruby requires the Cloud IAM Debugger Agent role. Most Google Cloud Platform compute platforms provide this role by default.

App Engine

Google App Engine grants the Debugger Agent role by default.

The Stackdriver Debugger agent for Ruby can be used without needing to explicity provide credentials.

Stackdriver Debugger is automatically enabled for App Engine environment applications. No additional setup is required.

Container Engine

On Google Container Engine, you must add the cloud_debugger access scope when creating the cluster:

gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud_debugger

Compute Engine

When using Google Compute Engine VM instances, add the cloud-platform access scope to each instance. When creating a new instance through the Google Cloud Platform Console, you can do this in the Identity and API access section of the Create Instance panel. Use the Compute Engine default service account or another service account of your choice, and select Allow full access to all Cloud APIs in the Identity and API access section. Whichever service account you select, ensure that it has been granted the Debugger Agent role in the IAM & admin section of the Cloud Platform Console.

Running locally and elsewhere

To use the Stackdriver Debugger agent for Ruby outside of Google Cloud Platform, you must supply your GCP project ID and appropriate service account credentials directly to the Stackdriver Debugger agent for Ruby. This applies to running the agent on your own workstation, on your data center's computers, or on the VM instances of another cloud provider. For more information see Obtaining and providing service account credentials manually.

Using Ruby on Rails configuration interface

Provide the parameters through the Ruby on Rails configuration interface if you are using the Ruby on Rails framework:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Debugger specific parameters
  config.google_cloud.debugger.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.debugger.keyfile    = "/path/to/service-account.json"
end

You can also set shared configuration for all stackdriver gems using:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Using instrumentation configuration interface

Provide the parameters through the configuration interface when used in other Rack-based applications:

require "google/cloud/debugger"

Google::Cloud.configure do |config|
  # Stackdriver Debugger specific parameters
  config.debugger.project_id = "YOUR-PROJECT-ID"
  config.debugger.keyfile    = "/path/to/service-account.json"
end

You can also set shared configuration for all stackdriver gems using:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

Using agent parameters

Provide the parameters to the Stackdriver Debugger agent for Ruby when it starts:

require "google/cloud/debugger"

Google::Cloud::Debugger.new(project: "YOUR-PROJECT-ID",
                            keyfile: "/path/to/service-account.json").start

Source version

Generate a source-context.json file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information in this file to display the correct version of the source.

gcloud beta debug source gen-repo-info-file

For more information see Selecting Source Code Manually.

Debugging

After deployment, you can begin debugging in the Cloud Platform Console Debugger dashboard:

Go to the Debugger dashboard

For more information, see Using Debug Snapshots and Using Debug Logpoints.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Debugger