Setting up Stackdriver Trace for Ruby

Stackdriver Trace can be enabled for Ruby applications using the Stackdriver Trace library for Ruby.

Installing the library

  1. Install Ruby 2.2+ or greater.

  2. Add the Stackdriver gem to your Gemfile:

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

    bundle install
    

Enabling the library

Rails

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

Not Rails

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

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

For more information or to report issues with the library, see the library's source code repository.

Configuring the client

You can customize the behavior of the Stackdriver Trace library for Ruby. See the library's configuration for a list of possible configuration options.

Add Custom Trace Span

The Stackdriver Trace library for Ruby automatically creates a trace record for each request your Rack application receives. You can also add custom trace spans within each request:

Google::Cloud::Trace.in_span "my_task" do |_span|
  # Insert task

  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
    # Insert subtask
  end
end

Running on Google Cloud Platform

You don't need to provide authentication credentials for instances running on Google Cloud Platform, provided Stackdriver Trace API access scope is enabled on that instance. However, we recommend setting the broadest possible access scope for your instance and then using Cloud Identity and Access Management to restrict access.

App Engine flexible environment

On App Engine flexible environment, the Stackdriver Trace API access scope is enabled by default, and the Stackdriver Trace library for Ruby can be used without providing credentials or a project ID.

App Engine standard environment

On App Engine standard environment, the Stackdriver Trace API access scope is enabled by default, and the Stackdriver Trace library for Ruby can be used without providing credentials or a project ID.

GKE

To use Trace with GKE, add the trace.append OAuth access scope when you create your cluster.

To create a cluster using gcloud, do the following:

  1. (Optional) Update gcloud to the latest version:
    gcloud components update
  2. Set your default project ID:
    gcloud config set project [PROJECT_ID]
  3. If you're working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  4. If you're working with regional clusters, set your default compute region:
    gcloud config set compute/region [COMPUTE_REGION]
  5. Issue the create command:
    gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/trace.append

For more detailed information on creating a cluster, see Creating a cluster.

Compute Engine

For Compute Engine VM instances, you need to explicitly enable the trace.append Stackdriver Trace API access scope for each VM instance. When creating a new instance through the Google Cloud Platform Console, select the following values in the Identity and API access section of the Create an instance panel:

  1. Select Compute Engine default service account for Service account
  2. Select Allow full access to all Cloud APIs for Access Scopes

To use something other than the Compute Engine default service account see the Creating and enabling service accounts for instances and Running locally and elsewhere sections. The important thing is that the service account you use has the Cloud Trace Agent role.

Running locally and elsewhere

To run Trace outside of GCP, you must supply your GCP project ID and appropriate service account credentials directly to Trace. This applies to running the library on your own workstation, on your datacenter's computers, or on the VM instances of another cloud provider. Here are the steps involved:

  1. Create a new service account in your GCP project. It must contain at least the Cloud Trace agent role. For instructions, see Creating a service account.

  2. Download the service account's key credentials file to your computer. For instructions, see Creating and managing service account keys.

  3. Provide your GCP project ID and the location of the credentials file to the Trace using either parameters (project_id and keyfile) or environment variables (GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS).

For more information, see Providing credentials to your application.

Using environment variables

Define the environment variables where they are visible to the Trace. If they are visible more widely, they could interfere with existing authorizations for other applications.

Linux/macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Command window:

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Using Ruby on Rails configuration interface

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

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Trace specific parameters
  config.google_cloud.trace.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.trace.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

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

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

Using instrumentation configuration interface

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

require "google/cloud/trace"

Google::Cloud.configure do |config|
  # Stackdriver Trace specific parameters
  config.trace.project_id = "YOUR-PROJECT-ID"
  config.trace.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

Viewing the traces

After deployment, you can view the traces in the GCP Console Trace Viewer.

Go to the Trace Viewer page

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Trace
Need help? Visit our support page.