You can enable Stackdriver Trace for Ruby applications by using the Stackdriver Trace library for Ruby.
Installing the library
Install Ruby 2.2+ or greater.
Add the Stackdriver gem to your Gemfile:
Use bundler to install the gem:
Enabling the library
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/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
Configuring your platform
You can use Trace on Google Cloud and when your application runs outside of Google Cloud.
Running on Google Cloud
When your application is running on Google Cloud, your application is automatically authenticated and you don't need to provide authentication credentials. However, you do need to ensure that your Google Cloud platform has the Stackdriver Trace API access scope enabled.
For the following configurations, the default settings for the access scopes have the Stackdriver Trace API enabled:
- App Engine flexible environment
App Engine standard environment
Google Kubernetes Engine
If you use custom access scopes, then you must ensure that
Stackdriver Trace API access scope
gcloud users, specify access scopes using the
and include the
trace.append Stackdriver Trace API access scope.
For example, to create a GKE cluster with only
the Stackdriver Trace API enabled, do the following:
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
Running locally and elsewhere
When your application is running outside of Google Cloud, you must provide authentication credentials in the form of a service account to the client library. The service account must contain the Cloud Trace agent role. For instructions, see Creating a service account.
The Google Cloud client libraries for Ruby use Application default credentials (ADC) to find your application's credentials. The following section describes how to set these credentials and the Google Cloud project ID.
Setting the Google Cloud project ID and credentials
This section describes three different approaches you can use to set the Google Cloud project ID, the authentication credentials, or both of these in your Ruby application.
When you don't explicitly set the Google Cloud project ID,
google-cloud Ruby library automatically determines if
the environment variable
GOOGLE_CLOUD_PROJECT is set, and if so, the
library uses the value of
GOOGLE_CLOUD_PROJECT as your Google Cloud
project ID. For more information, go to
As described earlier, the Google Cloud client libraries use
Application default credentials (ADC) to find your
application's credentials. You can provide these credentials
by setting the
GOOGLE_APPLICATION_CREDENTIALS environment variable:
Ruby on Rails configuration interface
If you're using Ruby on Rails, one alternative for Ruby is to provide the parameters through the configuration interface:
# 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 gem 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
Instrumentation configuration interface
Another alternative for Ruby is to 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 Cloud Console Trace Viewer.