You can enable Cloud Trace for Ruby applications by using the Cloud 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:
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:
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 Cloud Trace library for Ruby. See the library's configuration for a list of possible configuration options.
Add custom Trace span
The Cloud 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:
Configure your platform
You can use Cloud Trace on Google Cloud and other platforms.
Running on Google Cloud
When your application is running on Google Cloud, you don't need to provide authentication credentials in the form of a service account to the client library. However, you do need to ensure that your Google Cloud platform has the Cloud Trace API access scope enabled.
For a list of supported Google Cloud environments, see Environment support.
For the following configurations, the default access-scope settings enable the Cloud Trace API:
- App Engine flexible environment
App Engine standard environment
Google Kubernetes Engine (GKE)
Compute Engine
Cloud Run
If you use custom access scopes, then you must ensure that Cloud Trace API access scope is enabled:
For information about how to configure the access scopes for your environment by using the Google Cloud console, see Configuring your Google Cloud project.
For
gcloud
users, specify access scopes using the--scopes
flag and include thetrace.append
Cloud Trace API access scope. For example, to create a GKE cluster with only the Cloud 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
If your application is running outside of Google Cloud, then 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.
Environment variable
When you don't explicitly set the Google Cloud project ID,
the 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
Authentication.
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:
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"
Ruby on Rails configuration interface
If you're using Ruby on Rails, you can provide the parameters through the Ruby on Rails configuration interface:
You can also set shared configuration for all Stackdriver gem using:
Trace is enabled by default when Rails is running in production mode. To enable Trace in development mode, add the following:
Instrumentation configuration interface
Another alternative for Ruby is to provide the parameters through the configuration interface when used in other Rack-based applications:
You can also set shared configuration for all Stackdriver gems using:
View traces
In the Google Cloud console, go to the Trace explorer page:
You can also find this page by using the search bar.
Troubleshooting
For information on troubleshooting issues with Cloud Trace, go to the Troubleshooting page.