Setting up Cloud Debugger for Ruby

Overview

This page describes how to configure your environment and your Ruby application to use Cloud Debugger. For some environments, you must explicitly specify the access scope to let the Cloud Debugger agent send data. We recommend setting the broadest possible access scope and then using Identity and Access Management to restrict access. In keeping with this best practice, set the access scope to be all Cloud APIs with the option cloud-platform.

Language versions and compute environment

Cloud Debugger is available for Ruby versions 2.2 and higher.

App Engine Standard environment App Engine Flexible environment Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos on Google Cloud VMs and Containers running elsewhere Cloud Functions

Setting up Cloud Debugger

To set up Cloud Debugger, complete the following tasks:

  1. Verify the Cloud Debugger API is enabled for your project.

  2. Install and configure the Debugger on the compute environment you're using.

  3. Select your source code.

Verifying the Cloud Debugger API is enabled

To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled. Cloud Debugger is enabled by default for most projects.
Enable Cloud Debugger API

App Engine flexible environment

  1. Add the stackdriver gem to your Gemfile:

    gem "stackdriver"
    
  2. Enable the agent.

Rails

Bundler automatically loads the library into your app when it starts. No configuration is required.

Rack

Use the Rack Middleware provided by the library:

require "google/cloud/debugger"

use Google::Cloud::Debugger::Middleware

Other

For pure Ruby apps, start the agent explicitly at the entry point:

require "google/cloud/debugger"

Google::Cloud::Debugger.new.start

The debugger is now ready for use with your app.

Google Kubernetes Engine

GCLOUD

To enable Debugger using gcloud, complete the following steps:

  1. Create your cluster with one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform grants your cluster access to all Google Cloud APIs.

    • https://www.googleapis.com/auth/cloud_debugger grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Add the stackdriver gem to your Gemfile:

    gem "stackdriver"
    
  3. Add the following line to your Dockerfile to add the Debugger agent:

    Run bundle install
    
  4. Enable the Debugger agent:

    Rails

    Bundler automatically loads the library into your app when it starts.

    You can optionally provide a service and version through the Ruby on Rails configuration interface:

    # Add this to config/environments/*.rb
    Rails.application.configure do |config|
      config.google_cloud.debugger.service_name = "SERVICE-NAME"
      config.google_cloud.debugger.service_version = "SERVICE-VERSION"
    end
    

    Where:

    • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
    • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

    Debugger is enabled by default when Rails is running in production mode. To enable Debugger in development mode, add the following:

    # Add this to config/environments/development.rb
    Rails.application.configure do |config|
      config.google_cloud.use_debugger = true
    end

    Rack

    Use the Rack Middleware provided by the library:

     require "google/cloud/debugger"
    
     Google::Cloud::Debugger.configure do |config|
       config.service_name = "SERVICE-NAME"
       config.service_version = "SERVICE-VERSION"
      end
    
     use Google::Cloud::Debugger::Middleware
    

    Where:

    • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
    • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

    Other

    For pure Ruby apps, start the agent explicitly at the entry point:

    require "google/cloud/debugger"
    
    Google::Cloud::Debugger.new(service_name: "SERVICE-NAME",
                        service_version: "SERVICE-VERSION").start
    

    Where:

    • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
    • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

    We recommend setting these from environment variables so you do not need to change the source code with each deployment.

    Debugger is now enabled for your app.

CONSOLE

To enable Debugger using the console, complete the following steps:

  1. After selecting your cluster type, click More options from the Node pools pane:

    Node pools options

  2. Select one of the following from the Security pane:

    • Allow full access to all Cloud APIs.

    • Allow access for each API and then select Enabled for Cloud Debugger.

Compute Engine

  1. Make sure your Compute Engine instances are created with the access scope option Allow full access to all Cloud APIs, or have one of the following access scopes:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  2. Add the stackdriver gem to your Gemfile:

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

    bundle install
    
  4. Enable the agent.

Rails

Bundler automatically loads the library into your app when it starts.

You can optionally provide a service and version through the Ruby on Rails configuration interface:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  config.google_cloud.debugger.service_name = "SERVICE-NAME"
  config.google_cloud.debugger.service_version = "SERVICE-VERSION"
end

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

Debugger is enabled by default when Rails is running in production mode. To enable Debugger in development mode, add the following:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_debugger = true
end

Rack

Use the Rack Middleware provided by the library:

require "google/cloud/debugger"

Google::Cloud::Debugger.configure do |config|
  config.service_name = "SERVICE-NAME"
  config.service_version = "SERVICE-VERSION"
end

use Google::Cloud::Debugger::Middleware

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

Other

For pure Ruby apps, start the agent explicitly at the entry point:

require "google/cloud/debugger"

Google::Cloud::Debugger.new(service_name: "SERVICE-NAME",
                            service_version: "SERVICE-VERSION").start

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

The debugger is now ready for use with your app.

Local and elsewhere

  1. Add the stackdriver gem to your Gemfile.

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

    bundle install
    
  3. Download service account credentials.

    To use the Cloud Debugger agent for Ruby on machines not hosted by Google Cloud, the agent must use a Google Cloud service account credentials to authenticate with the Cloud Debugger Service.

    Use the Cloud Console Service Accounts page to create a credentials file for an existing or new service account. The service account must have at least the Cloud Debugger Agent role.

  4. Configure and enable the agent with the downloaded credentials.

Rails

Provide the parameters through the Ruby on Rails configuration interface:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
  config.google_cloud.debugger.service_name = "SERVICE-NAME"
  config.google_cloud.debugger.service_version = "SERVICE-VERSION"
end

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

Debugger is enabled by default when Rails is running in production mode. To enable Debugger in development mode, add the following:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_debugger = true
end

Rack

Use the Rack Middleware provided by the library:

require "stackdriver"
require "google/cloud/debugger"

Google::Cloud.configure do |config|
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
  config.service_name = "SERVICE-NAME"
  config.service_version = "SERVICE-VERSION"
end

use Google::Cloud::Debugger::Middleware

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

Other

For pure Ruby apps, start the agent explicitly at the entry point:

require "google/cloud/debugger"

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

Where:

  • SERVICE-NAME is a name for your app, such as MyApp, Backend, or Frontend.
  • SERVICE-VERSION is a version, such as v1.0, build_147, or v20170714.

We recommend setting these from environment variables so you do not need to change the source code with each deployment.

The debugger is now ready for use with your app.

The Debug page in the Cloud Console can display local source files, without upload, for local development. See Selecting Source Code Manually.