设置 Ruby 版 Cloud Trace

您可以使用 Ruby 版 Cloud Trace 库为 Ruby 应用启用 Cloud Trace。

安装库

  1. 安装 Ruby 2.2+ 或更高版本。

  2. 将 Stackdriver gem 添加到 Gemfile：

    gem "stackdriver"

  3. 使用 bundler 安装 gem：

    bundle install

启用库

Rails

如果您正在使用 Ruby on Rails，Bundler 会在启动时自动将库加载到您的应用中。

非 Rails

其他基于 Rack 的应用可以使用库提供的 Rack Middleware：

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

如需了解更多信息或报告有关库的问题，请参阅库的源代码库。

配置客户端

您可以自定义 Ruby 版 Cloud Trace 库的行为。如需查看可能的配置选项的列表，请参阅库的配置。

添加自定义 Trace span

Ruby 版 Stackdriver Trace 库会自动为您的 Rack 应用收到的每个请求创建跟踪记录。您还可以在每个请求中添加自定义跟踪 span：

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

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

配置平台

您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时，您无需向客户端库提供服务账号形式的身份验证凭据。但是，您需要确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围。

如需查看受支持的 Google Cloud 环境的列表，请参阅环境支持。

对于以下配置，默认的访问权限范围设置会启用 Cloud Trace API：

如果您使用自定义访问权限范围，则必须确保已启用 Cloud Trace API 访问权限范围：

  • 如需了解如何使用 Google Cloud 控制台为您的环境配置访问权限范围，请参阅配置 Google Cloud 项目。

  • 对于 gcloud 用户，请使用 --scopes 标志指定访问权限范围，并添加 trace.append Cloud Trace API 访问权限范围。例如，如需创建仅启用了 Cloud Trace API 的 GKE 集群，请执行以下操作：

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

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行，则必须向客户端库提供服务账号形式的身份验证凭据。该服务账号必须包含 Cloud Trace Agent 角色。如需查看说明，请参阅创建服务账号。

Ruby 版 Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。以下部分介绍了如何设置这些凭据和 Google Cloud 项目 ID。

设置 Google Cloud 项目 ID 和凭据

本部分介绍了您在 Ruby 应用中设置 Google Cloud 项目 ID 和/或身份验证凭据时可使用的三种不同方法。

环境变量

如果您未明确设置 Google Cloud 项目 ID，则 google-cloud Ruby 库会自动确定是否设置了环境变量 GOOGLE_CLOUD_PROJECT；如果已设置，则该库会将 GOOGLE_CLOUD_PROJECT 的值用作您的 Google Cloud 项目 ID。如需了解详情，请参阅身份验证。

如前所述，Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。您可以通过设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量来提供这些凭据：

Linux/macOS

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

Windows

命令窗口：

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 配置界面

如果您正在使用 Ruby on Rails，则可以通过 Ruby on Rails 配置界面提供参数：

# 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

您还可以使用以下命令为所有 Stackdriver gem 设置共享配置：

# 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

如果 Rails 在生产模式下运行，则默认启用 Trace。要在开发模式下启用 Trace，请添加以下内容：

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

插桩配置界面

在基于 Rack 的其他应用中使用时，请通过配置界面提供参数，将此作为 Ruby 的另一种替代方案：

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

您还可以使用以下代码为所有 Stackdriver gem 设置共享配置：

require "stackdriver"

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

查看跟踪记录

在 Google Cloud 控制台中，转到 Trace 探索器页面：

转到 Trace 探索器

您也可以使用搜索栏查找此页面。

问题排查

如需了解如何排查 Cloud Trace 的问题，请转到“问题排查”页面。

资源